Vérification vocale (OTP)

Le modèle « on vous appelle, on lit le code » : vous fournissez le numéro, le standard appelle et lit le code de vérification chiffre par chiffre à la personne qui décroche (appuyez sur 1 pour répéter), puis raccroche. Vous pouvez envoyer le code vous-même, ou laisser Buluthat le générer et le renvoyer une seule fois dans la réponse. Le code n'est conservé dans la base de données que sous forme de hash est conservé comme ; status n'apparaît pas dans la réponse.

Point d'accès : https://api.buluthat.com/api/voice_otp.php — Clé d'intégration (bt_…, portée voice_otp / autocall / voicebot / *). Dans le compte voice_otp le module doit être activé.

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

Réponse :

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

code n'est renvoyé que si Buluthat l'a généré ; si vous l'avez envoyé null.

Erreurs (422) : numéro invalide, plus de 3 appels vers le même numéro en 10 minutes (rate_limited), plafond journalier (daily_limit), appel en cours (in_progress), aucune ligne, aucune clé de synthèse vocale, le standard n'a pas pu établir l'appel (la cause figure dans le message).

POSTverify

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

id à la place de phone (+ reference) peut aussi être indiqué ; le dernier enregistrement ouvert pour ce numéro est utilisé.

• Correct : { "ok": true, "verified": true }
• Incorrect : 422 et error: wrong_code (essai restant dans le message), expired, too_many_attempts (5), not_delivered (l'appel n'a pas été lancé), not_found

Le code, si l'appel a été établi (answered/delivered) peut être vérifié — même si la personne raccroche après avoir entendu le code.

GETstatus

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

Statuts : pending → calling → answered → delivered → verified; les échecs no_answer, busy, failed, expired. final: true alors l'appel est terminé. Interrogez toutes les 2-3 secondes ou utilisez un webhook.

GETlist

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

GETcaller_ids · trunks

Options de numéro appelant et de ligne (identiques à l'API d'appels automatiques).

Webhook

webhook_url s'il est fourni, lors des changements d'état (delivered, verified, no_answer, busy, failed, expired) est envoyé en POST :

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

En-têtes X-Buluthat-Event, X-Buluthat-Delivery, webhook_secret s'il est fourni X-Buluthat-Signature: sha256=<hmac>. Nouvelle tentative après 1 min, 5 min, 15 min, 1 h, 3 h, 6 h pour toute réponse hors 2xx.

Client PHP

Téléchargé depuis le panneau 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

Pourquoi plutôt qu'un SMS ?

• n'exige ni consentement İYS ni en-tête SMS, fonctionne aussi sur un numéro fixe.
• Pas de problème de SMS non remis : on sait si l'appel a abouti et si le code a été lu.
• Pour un utilisateur âgé ou malvoyant, écouter le code est plus facile que de le lire.
• La facturation ne porte que sur les appels décrochés, selon les règles de votre forfait.