Zum Inhalt springen
Menü

Website durchsuchen

Tippe, um Anleitungen, Blog, API und Produkt zu durchsuchen.

↑ ↓ zum Wechseln · Enter zum Öffnen · Esc zum Schließen

API-Referenz

API

WhatsApp-OTP

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

Als Markdown ansehen

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.

MethodePfadBeschreibung
POST/v1/otp/templateAuthentifizierungsvorlage erstellen
GET/v1/otp/templateStatus der OTP-Vorlagen
POST/v1/otp/sendCode erzeugen und senden
POST/v1/otp/verifyCode 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.

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
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
  }'
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);
Antwort
{
  "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
curl "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);
Antwort
{
  "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
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
  }'
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);
Antwort
{
  "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
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"
  }'
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);
Antwort
{
  "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.

CodeHTTPWann
TEMPLATE_NOT_APPROVED409Die OTP-Vorlage dieser Sprache existiert nicht oder ist noch nicht von Meta genehmigt
OTP_RATE_LIMITED429Zu viele Codes für diese Nummer; nach Retry-After erneut versuchen
META_ERROR422Meta hat die Vorlage abgelehnt (z. B. nicht verifiziertes Unternehmen)
SEND_FAILED422Meta hat den Versand nicht angenommen
VALIDATION_ERROR400Ungültiger Body: Telefon, Länge, Sprache oder Code
NOT_FOUND404Die WhatsApp-Leitung existiert nicht oder gehört nicht zu diesem Agenten