API
WhatsApp-OTP
Bestätigungscodes per WhatsApp mit einer Schaltfläche „Code kopieren“ senden
# 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 |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.
| 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) |
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.
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.
/v1/otp/templatecurl -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
}'const response = await fetch('https://rest-api.tbit.app/v1/otp/template', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
language: 'es',
code_expiration_minutes: 10,
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/otp/template',
{
language: 'es',
code_expiration_minutes: 10,
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/otp/template',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'language': 'es',
'code_expiration_minutes': 10,
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/otp/template');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'language' => 'es',
'code_expiration_minutes' => 10,
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"created": true,
"template": {
"id": "6ac60aeaa2a9ed0cd9ca7fd4",
"name": "tbit_otp_es",
"language": "es",
"status": "PENDING",
"rejected_reason": null,
"code_expiration_minutes": 10,
"channel_id": "691deef351c7513d0c6a2a6f"
}
}
}Listet die OTP-Vorlagen des Agenten. Noch nicht genehmigte werden live bei Meta abgefragt: status ist PENDING, APPROVED oder REJECTED.
/v1/otp/templatecurl "https://rest-api.tbit.app/v1/otp/template" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/otp/template', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/otp/template',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/otp/template',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/otp/template');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": [
{
"id": "6ac60aeaa2a9ed0cd9ca7fd4",
"name": "tbit_otp_es",
"language": "es",
"status": "APPROVED",
"rejected_reason": null,
"code_expiration_minutes": 10,
"channel_id": "691deef351c7513d0c6a2a6f"
}
]
}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.
/v1/otp/sendcurl -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
}'const response = await fetch('https://rest-api.tbit.app/v1/otp/send', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '+57 300 123 4567',
length: 6,
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/otp/send',
{
to: '+57 300 123 4567',
length: 6,
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/otp/send',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '+57 300 123 4567',
'length': 6,
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/otp/send');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '+57 300 123 4567',
'length' => 6,
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"request_id": "be4ffa6c-f45a-4410-b38a-882bd3edd9b3",
"to": "573001234567",
"code": "054381",
"expires_in_minutes": 10,
"expires_at": "2026-10-07T09:17:26.278Z"
}
}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 }.
/v1/otp/verifycurl -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"
}'const response = await fetch('https://rest-api.tbit.app/v1/otp/verify', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '573001234567',
code: '054381',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/otp/verify',
{
to: '573001234567',
code: '054381',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/otp/verify',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'to': '573001234567',
'code': '054381',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/otp/verify');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '573001234567',
'code' => '054381',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"valid": false,
"reason": "invalid_code",
"attempts_left": 4
}
}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.
| 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 |