View as Markdown
Open in
撥打外撥電話（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 已封鎖外撥（ThunderPhone 號碼） | 改為自備 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 分鐘）。