send verify status list caller_ids · trunks Webhook PHP 客户端为什么不用短信？

语音验证 (OTP)

“我们打电话给您，把验证码读给您”模式：您提供号码，总机拨打并向接听者逐位读出验证码（按 1 重听），然后挂断。验证码可由您发送，也可由 Buluthat 生成并仅在响应中返回一次。验证码在数据库中仅以 hash 保存为； status 不会出现在响应中。

接口： https://api.buluthat.com/api/voice_otp.php — 集成密钥 (bt_…，权限范围 voice_otp / autocall / voicebot / *）。账户中 voice_otp 模块必须已开启。

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

区域	必填	说明
`phone`	是	被叫号码
`code`	否	您自己的验证码；若为空，则由 Buluthat 生成
`length`	否	要生成的验证码位数（4-8，默认 6）
`reference`	否	您自己的记录； `status`/`list` 用于查找
`caller_id`, `trunk_slug`	否	主叫号码与线路
`repeat`	否	验证码读几遍（1-5，默认 2）
`ttl_minutes`	否	验证码有效期（最长 60，默认 5）
`company_name`	否	开场语音中的公司名称；若为空则使用账户名称
`webhook_url`, `webhook_secret`	否	状态通知

响应：

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

code 仅在由 Buluthat 生成时返回；若由您发送， null.

错误（422）：无效号码、同一号码在 10 分钟内超过 3 次的呼叫（rate_limited），每日上限（daily_limit），进行中的呼叫（in_progress），线路缺失，语音合成密钥缺失，总机无法建立呼叫（消息中会说明原因）。

POSTverify

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

id 代替 phone (+ reference）也可以；将使用拨向该号码的最新记录。

正确： { "ok": true, "verified": true }
错误： 422 和 error: wrong_code （剩余试用额度已计入消息）， expired, too_many_attempts (5), not_delivered （呼叫未发起）， not_found

验证码，若呼叫已接通（answered/delivered）验证——即使对方听完验证码后挂断电话也可以。

GETstatus

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

状态： pending → calling → answered → delivered → verified；失败项 no_answer, busy, failed, expired. final: true 则呼叫已结束。请每 2-3 秒查询一次，或使用 Webhook。

GETlist

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

GETcaller_ids · trunks

主叫号码与线路选项（与自动外呼 API 相同）。

Webhook

webhook_url 若已提供，状态变化时（delivered, verified, no_answer, busy, failed, expired）POST 发送：

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

请求头 X-Buluthat-Event, X-Buluthat-Delivery, webhook_secret 若已提供 X-Buluthat-Signature: sha256=<hmac>。若响应不是 2xx，则在 1 分钟、5 分钟、15 分钟、1 小时、3 小时、6 小时后重试。

PHP 客户端

从面板下载的 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

为什么不用短信？

无需 İYS 许可和短信标题，固话也可使用。
没有短信未送达的问题：通话是否接通、验证码是否读出，一目了然。
对老年人或视障用户来说，听验证码比读文字更容易。
仅对已接通的呼叫计费，按您的套餐规则。

← 语音助手 SMS API