Sprach-Verifizierung (OTP)

Das Modell „Wir rufen an und lesen den Code vor“: Sie übergeben die Nummer, die Telefonanlage ruft an und liest dem Angerufenen den Bestätigungscode Ziffer für Ziffer vor (bei 1 wird wiederholt) und legt auf. Sie können den Code selbst senden oder von Buluthat erzeugen und einmalig in der Antwort zurückgeben lassen. Der Code wird in der Datenbank nur hash wird gespeichert als; status erscheint nicht in der Antwort.

Endpunkt: https://api.buluthat.com/api/voice_otp.php — Integrationsschlüssel (bt_…, Geltungsbereich voice_otp / autocall / voicebot / *). Im Konto voice_otp Modul muss aktiviert sein.

POSTsend

{
  "action": "send",
  "phone": "05551112233",
  "code": "482913",
  "length": 6,
  "reference": "CARI-451",
  "caller_id": "02124119610",
  "trunk_slug": "hat-1",
  "repeat": 2,
  "ttl_minutes": 5,
  "company_name": "Byfix",
  "webhook_url": "https://crm.example.com/otp-sonuc.php",
  "webhook_secret": "gizli"
}

Antwort:

{ "ok": true, "code": "482913", "data": { "id": 17, "status": "calling", "expires_at": "2026-09-18 10:17:03" } }

code wird nur zurückgegeben, wenn Buluthat ihn erzeugt hat; wenn Sie ihn gesendet haben null.

Fehler (422): ungültige Nummer, mehr als 3 Anrufe an dieselbe Nummer in 10 Minuten (rate_limited), Tageslimit (daily_limit), laufender Anruf (in_progress), keine Leitung, kein TTS-Schlüssel, die Telefonanlage konnte den Anruf nicht aufbauen (Grund steht in der Meldung).

POSTverify

{ "action": "verify", "id": 17, "code": "482913" }

id statt phone (+ reference) kann ebenfalls angegeben werden; es wird der zuletzt zu dieser Nummer angelegte Datensatz verwendet.

• Richtig: { "ok": true, "verified": true }
• Falsch: 422 und error: wrong_code (Testnachrichten verbleibend), expired, too_many_attempts (5), not_delivered (Anruf nicht zustande gekommen), not_found

Der Code, wenn der Anruf angenommen wurde (answered/delivered) können verifiziert werden — auch wenn die Person nach dem Hören des Codes auflegt.

GETstatus

GET https://api.buluthat.com/api/voice_otp.php?action=status&id=17

Status: pending → calling → answered → delivered → verified; fehlgeschlagene no_answer, busy, failed, expired. final: true ist der Anruf beendet. Fragen Sie alle 2-3 Sekunden ab oder nutzen Sie Webhooks.

GETlist

GET ?action=list&phone=0555…&reference=CARI-451&limit=20

GETcaller_ids · trunks

Optionen für Anrufernummer und Leitung (identisch mit der Auto-Call-API).

Webhook

webhook_url wenn angegeben, bei Statusänderungen (delivered, verified, no_answer, busy, failed, expired) wird per POST gesendet:

{ "event": "voice_otp.delivered", "request": { "id": 17, "status": "delivered", "reference": "CARI-451", "phone": "05551112233" } }

Header X-Buluthat-Event, X-Buluthat-Delivery, webhook_secret wenn angegeben X-Buluthat-Signature: sha256=<hmac>. Bei einer Antwort außerhalb von 2xx erfolgt ein erneuter Versuch nach 1 Min., 5 Min., 15 Min., 1 Std., 3 Std., 6 Std.

PHP-Client

Aus dem Panel heruntergeladene buluthat-voice-otp-client.php:

require 'buluthat-voice-otp-client.php';
$otp = new BuluthatVoiceOtp('https://api.buluthat.com', 'bt_xxx');

$r = $otp->send('05551112233', ['reference' => 'CARI-451']);   // $r['code'], $r['data']['id']
// ... kullanıcı kodu girer ...
$v = $otp->verify($r['data']['id'], $girilenKod);               // $v['ok'] === true

Warum statt SMS?

• Erfordert keine İYS-Zustimmung und keine SMS-Absenderkennung, funktioniert auch bei Festnetz.
• Keine Probleme mit nicht zugestellten SMS: Es ist klar, ob der Anruf angenommen und der Code vorgelesen wurde.
• Für ältere oder sehbehinderte Nutzer ist das Anhören des Codes einfacher als das Lesen von Text.
• Abgerechnet werden nur angenommene Anrufe, nach den Regeln Ihres Pakets.