Səsli Doğrulama (OTP)

"Sizə zəng edirik, kodu oxuyuruq" modeli: nömrəni verirsiniz, santral zəng edir, cavab verən şəxsə doğrulama kodunu rəqəm-rəqəm oxuyur (1-a basanda təkrar), bağlayır. Kodu siz göndərə bilərsiniz, ya da Buluthat yaradıb cavabda bir dəfə qaytara bilər. Kod verilənlər bazasında yalnız hash olaraq saxlanılır; status cavabında görünmür.

Nöqtə: https://api.buluthat.com/api/voice_otp.php — İnteqrasiya açarı (bt_…, əhatə voice_otp / autocall / voicebot / *). Hesabda voice_otp modulu açıq olmalıdır.

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

Cavab:

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

code yalnız Buluthat yaratdıqda qaytarılır; siz göndərmisinizsə null.

Xətalar (422): yanlış nömrə, eyni nömrəyə 10 dəqiqədə 3-dən çox zəng (rate_limited), gündəlik limit (daily_limit), davam edən zəng (in_progress), xətt yoxdur, səsləndirmə açarı yoxdur, santral zəngi qura bilmədi (mesajda səbəb).

POSTverify

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

id əvəzinə phone (+ reference) də verilə bilər; həmin nömrəyə açılan son qeyd istifadə olunur.

• Düzgün: { "ok": true, "verified": true }
• Yanlış: 422 və error: wrong_code (qalan sınaq mesajda), expired, too_many_attempts (5), not_delivered (zəng açılmadı), not_found

Kod, zəng açılıbsa (answered/delivered) doğrulana bilər — şəxs kodu eşitdikdən sonra telefonu bağlasa da olar.

GETstatus

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

Vəziyyətlər: pending → calling → answered → delivered → verified; uğursuzlar no_answer, busy, failed, expired. final: true isə zəng bitdi. 2-3 saniyədən bir sorğulayın ya da webhook istifadə edin.

GETlist

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

GETcaller_ids · trunks

Zəng edən nömrə və xətt seçimləri (avtomatik zəng API-si ilə eynidir).

Webhook

webhook_url verilibsə vəziyyət dəyişikliklərində (delivered, verified, no_answer, busy, failed, expired) POST göndərilir:

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

Başlıqlar X-Buluthat-Event, X-Buluthat-Delivery, webhook_secret verilibsə X-Buluthat-Signature: sha256=<hmac>. 2xx xaricində cavab olduqda 1 dəq, 5 dəq, 15 dəq, 1 saat, 3 saat, 6 saat sonra yenidən cəhd edilir.

PHP klienti

Paneldən endirilən 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

Niyə SMS əvəzinə?

• İYS icazəsi və SMS başlığı tələb etmir, stasionar xəttdə də işləyir.
• Çatdırılmayan SMS problemi yoxdur: zəng açıldımı, kod oxundumu bəllidir.
• Yaşlı ya da görmə məhdudiyyətli istifadəçi üçün kodu dinləmək yazını oxumaqdan asandır.
• Tarifləndirmə yalnız açılan zənglər üçün, paket qaydalarınıza görə.