发起外呼（API）
从您自己的代码中触发由 AI 驱动的外呼——用于问卷调查、跟进或确认流程。
外呼功能允许您将目标号码和智能体配置交给 ThunderPhone，由 AI 代表您拨打电话。典型用例包括：
- 预约确认
- 调研回访
- 未接来电后的“二次尝试”跟进
- 调度式通知
前提条件
- 准备一个 VoIP 号码
- 创建智能体
适用于外呼的提示词通常以智能体介绍自身及呼叫目的开始——“您好，这里是 Acme，我们致电是为了确认您明天下午 3 点的预约……”将
outbound_speak_order设置为agent_first（默认值）。 - 保持正余额
当余额 ≤
$0.00时，外呼将返回402 Payment Required。通过POST /v1/billing/top-up充值，或启用自动充值。
使用已保存的智能体发起呼叫
最简单的方法——通过 ID 引用智能体：
curl -X POST https://api.thunderphone.com/v1/call \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_number": "+15551234567",
"to_number": "+14155550199",
"agent_id": 12
}'响应：
{ "call_id": 987654321, "status": "initiated" }使用内联配置发起呼叫
如果您需要一次性提示词，不值得将其保存为智能体，
请改为传递 config。其结构与
call.incoming webhook 的响应架构一致：
curl -X POST https://api.thunderphone.com/v1/call \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_number": "+15551234567",
"to_number": "+14155550199",
"config": {
"prompt": "You are confirming Jane Doe appointment for 3pm tomorrow…",
"voice": "john",
"product": "spark"
}
}'跟进通话
同时订阅
telephony.complete webhook——
这是获知通话结束的最快方式。如果您无法接收传入的
webhook，请每隔几秒轮询 GET /v1/calls/{call_id}；通话结束后，
记录将包含 end_reason、duration_seconds 和录音 URL。
值得处理的失败情况
| 错误 | 解决方法 |
|---|---|
402 Payment Required | 充值余额或启用自动充值 |
403 外呼被阻止（演示号码） | 改用 VoIP 号码 |
403 外呼被阻止（未经验证的 VoIP） | 运行 POST /v1/phone-numbers/{id}/verify-voip |
404 from_number is not registered to this organization | 确认 from_number 与您拥有的电话号码一致 |
502 Bad Gateway | 临时性 SIP / LiveKit 故障；可安全重试 |
控制保持时间
如果由于被叫方响应缓慢（IVR 菜单、队列）导致外呼通话时间过长，可以使用 max_hold_seconds 进行限制：
{
"from_number": "+15551234567",
"to_number": "+14155550199",
"agent_id": 12,
"max_hold_seconds": 120
}如果在最近 N 秒内未收到真人音频，智能体将挂断。默认值为 900（15 分钟）。