Głosowa weryfikacja (OTP)

Model „Dzwonimy do Ciebie i odczytujemy kod”: podajesz numer, centrala dzwoni i odczytuje osobie, która odbierze, kod weryfikacyjny cyfra po cyfrze (po naciśnięciu 1 powtarza), po czym się rozłącza. Kod możesz wysłać samodzielnie albo Buluthat go wygeneruje i zwróci raz w odpowiedzi. W bazie danych kod jest przechowywany wyłącznie hash przechowywane jako; status nie jest widoczny w odpowiedzi.

Punkt końcowy: https://api.buluthat.com/api/voice_otp.php — Klucz integracji (bt_…, zakres voice_otp / autocall / voicebot / *). Na koncie voice_otp moduł musi być włączony.

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"
}

Odpowiedź:

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

code zwracany tylko wtedy, gdy wygeneruje go Buluthat; jeśli Ty wysłałeś null.

Błędy (422): nieprawidłowy numer, więcej niż 3 połączeń na ten sam numer w ciągu 10 minut (rate_limited), dzienny limit (daily_limit), trwające połączenie (in_progress), brak linii, brak klucza syntezy mowy, centrala nie zestawiła połączenia (przyczyna w komunikacie).

POSTverify

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

id zamiast phone (+ reference) można również podać; używany jest ostatni rekord otwarty dla tego numeru.

• Poprawnie: { "ok": true, "verified": true }
• Błędnie: 422 i error: wrong_code (pozostała próba w wiadomości), expired, too_many_attempts (5), not_delivered (połączenie nie zostało zainicjowane), not_found

Kod, jeśli połączenie zostało nawiązane (answered/delivered) można zweryfikować — także gdy osoba rozłączy się po usłyszeniu kodu.

GETstatus

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

Statusy: pending → calling → answered → delivered → verified; nieudane no_answer, busy, failed, expired. final: true jeśli połączenie się zakończyło. Odpytuj co 2-3 sekund lub użyj webhooka.

GETlist

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

GETcaller_ids · trunks

Opcje numeru dzwoniącego i linii (takie same jak w API automatycznych połączeń).

Webhook

webhook_url jeśli podano, przy zmianach statusu (delivered, verified, no_answer, busy, failed, expired) wysyła POST:

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

Nagłówki X-Buluthat-Event, X-Buluthat-Delivery, webhook_secret jeśli podano X-Buluthat-Signature: sha256=<hmac>. Przy odpowiedzi innej niż 2xx ponowna próba po 1 min, 5 min, 15 min, 1 godz., 3 godz., 6 godz.

Klient PHP

Pobrane z panelu 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

Dlaczego zamiast SMS?

• Nie wymaga zgody İYS ani nagłówka SMS, działa także na linii stacjonarnej.
• Nie ma problemu z niedostarczonymi SMS-ami: wiadomo, czy połączenie odebrano i czy kod odczytano.
• Dla osób starszych lub niedowidzących słuchanie kodu jest łatwiejsze niż czytanie tekstu.
• Rozliczanie dotyczy wyłącznie połączeń odebranych, według reguł Twojego pakietu.