Verifica vocale (OTP)

Il modello "Vi chiamiamo e leggiamo il codice": Voi fornite il numero, il centralino chiama e legge il codice cifra per cifra a chi risponde (con 1 lo ripete), poi riattacca. Il codice può essere inviato da Voi oppure generato da Buluthat e restituito una sola volta nella risposta. Nel database il codice è conservato solo hash viene conservato come; status non compare nella risposta.

Endpoint: https://api.buluthat.com/api/voice_otp.php — Chiave di integrazione (bt_…, ambito voice_otp / autocall / voicebot / *). Nell'account voice_otp il modulo deve essere attivo.

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

Risposta:

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

code viene restituito solo se generato da Buluthat; se l'avete inviato Voi null.

Errori (422): numero non valido, più di 3 chiamate allo stesso numero in 10 minuti (rate_limited), limite giornaliero (daily_limit), chiamata in corso (in_progress), nessuna linea, nessuna chiave di sintesi vocale, il centralino non ha potuto stabilire la chiamata (il motivo è nel messaggio).

POSTverify

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

id invece di phone (+ reference) può essere indicato anche; viene usato l'ultimo record aperto per quel numero.

• Corretto: { "ok": true, "verified": true }
• Errato: 422 e error: wrong_code (messaggi di prova rimanenti), expired, too_many_attempts (5), not_delivered (chiamata non avviata), not_found

Il codice, se la chiamata è stata avviata (answered/delivered) può essere verificato — anche se la persona riattacca dopo aver sentito il codice.

GETstatus

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

Stati: pending → calling → answered → delivered → verified; quelli non riusciti no_answer, busy, failed, expired. final: true la chiamata è terminata. Interroghi ogni 2-3 secondi oppure usi il webhook.

GETlist

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

GETcaller_ids · trunks

Opzioni di numero chiamante e linea (identiche all'API di chiamata automatica).

Webhook

webhook_url se indicato, per le variazioni di stato (delivered, verified, no_answer, busy, failed, expired) viene inviato un POST:

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

Intestazioni X-Buluthat-Event, X-Buluthat-Delivery, webhook_secret se indicato X-Buluthat-Signature: sha256=<hmac>. In caso di risposta diversa da 2xx si riprova dopo 1 min, 5 min, 15 min, 1 h, 3 h, 6 h.

Client PHP

Scaricato dal pannello 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

Perché al posto di un SMS?

• Non richiede consenso İYS né intestazione SMS, funziona anche su linea fissa.
• Nessun problema di SMS non recapitati: si sa se la chiamata è stata risposta e se il codice è stato letto.
• Per un utente anziano o ipovedente ascoltare il codice è più facile che leggerlo.
• La tariffazione riguarda solo le chiamate risposte, secondo le regole del Suo pacchetto.