Verificación por voz (OTP)

El modelo "le llamamos y leemos el código": usted entrega el número, la central llama y lee el código de verificación dígito a dígito a quien contesta (se repite al pulsar 1) y cuelga. Puede enviar el código usted mismo o dejar que Buluthat lo genere y lo devuelva una sola vez en la respuesta. El código se guarda en la base de datos únicamente hash se guarda como; status no aparece en la respuesta.

Endpoint: https://api.buluthat.com/api/voice_otp.php — Clave de integración (bt_…, alcance voice_otp / autocall / voicebot / *). En la cuenta voice_otp el módulo debe estar activado.

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

Respuesta:

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

code solo se devuelve cuando lo genera Buluthat; si lo envió usted null.

Errores (422): número no válido, más de 3 llamadas al mismo número en 10 minutos (rate_limited), límite diario (daily_limit), llamada en curso (in_progress), no hay línea, no hay clave de locución, la central no pudo establecer la llamada (el motivo figura en el mensaje).

POSTverify

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

id en lugar de phone (+ reference) también puede indicarse; se usa el último registro abierto para ese número.

• Correcto: { "ok": true, "verified": true }
• Incorrecto: 422 y error: wrong_code (intentos restantes en el mensaje), expired, too_many_attempts (5), not_delivered (la llamada no se realizó), not_found

El código, si se abrió la llamada (answered/delivered) se puede verificar; incluso si la persona cuelga después de oír el código.

GETstatus

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

Estados: pending → calling → answered → delivered → verified; fallidos no_answer, busy, failed, expired. final: true si es, la llamada terminó. Consulte cada 2-3 segundos o use webhook.

GETlist

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

GETcaller_ids · trunks

Opciones de número de origen y línea (igual que en la API de llamadas automáticas).

Webhook

webhook_url si se indica, en los cambios de estado (delivered, verified, no_answer, busy, failed, expired) se envía un POST:

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

Encabezados X-Buluthat-Event, X-Buluthat-Delivery, webhook_secret si se indica X-Buluthat-Signature: sha256=<hmac>. Si la respuesta no es 2xx, se reintenta tras 1 min, 5 min, 15 min, 1 h, 3 h y 6 h.

Cliente PHP

Descargado desde el panel 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

¿Por qué en lugar de SMS?

• No requiere consentimiento de İYS ni encabezado SMS; funciona también en línea fija.
• Sin problemas de SMS no entregados: se sabe si se abrió la llamada y si se leyó el código.
• Para usuarios mayores o con discapacidad visual, escuchar el código es más fácil que leer el texto.
• La tarificación es solo para las llamadas que se abren, según las reglas de su paquete.