# WhatsApp-OTP

> Bestätigungscodes per WhatsApp mit einer Schaltfläche „Code kopieren“ senden

- Seite: https://tbit.app/de/docs/api/otp
- Basis-URL: `https://rest-api.tbit.app/v1`
- Authentifizierung: Header `X-API-Key` mit deinem Schlüssel in jeder Anfrage (die Beispiele lesen ihn aus der Umgebungsvariable `TBIT_API_KEY`)

## Überblick

TBit erzeugt einen numerischen Code, sendet ihn per WhatsApp über die Leitung deines Agenten mit einer Authentifizierungsvorlage (Schaltfläche „Code kopieren“) und gibt ihn in der Antwort zurück. Du kannst ihn in deinem System prüfen oder TBit mit /v1/otp/verify prüfen lassen. OTPs sind kostenlos und zählen nicht gegen dein Vorlagen-Kontingent.

## Endpoints

| Methode | Pfad | Beschreibung |
| --- | --- | --- |
| `POST` | `/v1/otp/template` | Authentifizierungsvorlage erstellen |
| `GET` | `/v1/otp/template` | Status der OTP-Vorlagen |
| `POST` | `/v1/otp/send` | Code erzeugen und senden |
| `POST` | `/v1/otp/verify` | Code prüfen (optional) |

## Voraussetzungen

Du brauchst eine mit deinem Agenten verbundene WhatsApp-Leitung. Meta erlaubt Authentifizierungsvorlagen nur für in Meta Business verifizierte Unternehmen (Unternehmenseinstellungen → Sicherheitscenter); ohne Verifizierung liefert das Erstellen der Vorlage META_ERROR mit „does not have permission to create message template“. Der Code wird von der Nummer der Leitung des Agenten gesendet, dem der API-Schlüssel gehört.

## Vorlage erstellen

Einmal pro Sprache (sie heißt tbit_otp_<sprache>). Den Text schreibt Meta, er lässt sich nicht anpassen: der Code, ein Sicherheitshinweis und die Gültigkeit in der Fußzeile. Optionale Felder: language (Standard es), code_expiration_minutes (1 bis 90, Standard 10) und channel_id, falls der Agent mehrere Leitungen hat. Existiert die Vorlage schon, kommt created: false mit ihrem Status zurück. Meta genehmigt sie meist in Sekunden.

`POST /v1/otp/template`

```bash
curl -X POST "https://rest-api.tbit.app/v1/otp/template" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "es",
    "code_expiration_minutes": 10
  }'
```

Antwort:

```json
{
  "data": {
    "created": true,
    "template": {
      "id": "6ac60aeaa2a9ed0cd9ca7fd4",
      "name": "tbit_otp_es",
      "language": "es",
      "status": "PENDING",
      "rejected_reason": null,
      "code_expiration_minutes": 10,
      "channel_id": "691deef351c7513d0c6a2a6f"
    }
  }
}
```

## Status der Vorlage

Listet die OTP-Vorlagen des Agenten. Noch nicht genehmigte werden live bei Meta abgefragt: status ist PENDING, APPROVED oder REJECTED.

`GET /v1/otp/template`

```bash
curl "https://rest-api.tbit.app/v1/otp/template" \
  -H "X-API-Key: $TBIT_API_KEY"
```

Antwort:

```json
{
  "data": [
    {
      "id": "6ac60aeaa2a9ed0cd9ca7fd4",
      "name": "tbit_otp_es",
      "language": "es",
      "status": "APPROVED",
      "rejected_reason": null,
      "code_expiration_minutes": 10,
      "channel_id": "691deef351c7513d0c6a2a6f"
    }
  ]
}
```

## Code senden

to ist die Telefonnummer mit Ländervorwahl (Leerzeichen, Bindestriche und + sind erlaubt). length liegt zwischen 4 und 8 Ziffern (Standard 6), language wählt die Vorlage (Standard es). Die Antwort enthält den Code für dein System; der Code wird nicht im Chatverlauf gespeichert.

`POST /v1/otp/send`

```bash
curl -X POST "https://rest-api.tbit.app/v1/otp/send" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+57 300 123 4567",
    "length": 6
  }'
```

Antwort:

```json
{
  "data": {
    "request_id": "be4ffa6c-f45a-4410-b38a-882bd3edd9b3",
    "to": "573001234567",
    "code": "054381",
    "expires_in_minutes": 10,
    "expires_at": "2026-10-07T09:17:26.278Z"
  }
}
```

## Code prüfen

Optional: Wenn du den Code nicht speichern willst, prüft TBit ihn. Jeder Code gilt nur einmal und läuft mit der Vorlage ab. Nach 5 Fehlversuchen wird er ungültig und ein neuer muss angefordert werden. reason kann invalid_code (mit attempts_left), too_many_attempts oder expired_or_not_found sein. Ein richtiger Code liefert { "valid": true }.

`POST /v1/otp/verify`

```bash
curl -X POST "https://rest-api.tbit.app/v1/otp/verify" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "573001234567",
    "code": "054381"
  }'
```

Antwort:

```json
{
  "data": {
    "valid": false,
    "reason": "invalid_code",
    "attempts_left": 4
  }
}
```

## Limits

Pro Telefon: ein Versand alle 30 Sekunden und 5 pro Stunde. Darüber hinaus kommt 429 OTP_RATE_LIMITED mit dem Header Retry-After. Zusätzlich gilt das allgemeine Limit von 100 Anfragen pro Minute und API-Schlüssel.

## Fehler

| Code | HTTP | Wann |
| --- | --- | --- |
| `TEMPLATE_NOT_APPROVED` | 409 | Die OTP-Vorlage dieser Sprache existiert nicht oder ist noch nicht von Meta genehmigt |
| `OTP_RATE_LIMITED` | 429 | Zu viele Codes für diese Nummer; nach Retry-After erneut versuchen |
| `META_ERROR` | 422 | Meta hat die Vorlage abgelehnt (z. B. nicht verifiziertes Unternehmen) |
| `SEND_FAILED` | 422 | Meta hat den Versand nicht angenommen |
| `VALIDATION_ERROR` | 400 | Ungültiger Body: Telefon, Länge, Sprache oder Code |
| `NOT_FOUND` | 404 | Die WhatsApp-Leitung existiert nicht oder gehört nicht zu diesem Agenten |
