撥打外撥電話（API）
從你自己的程式碼觸發由人工智慧驅動的外撥電話——適用於問卷調查、後續追蹤或確認流程。
對外撥號可讓你將目標號碼和智慧體設定交給 ThunderPhone，由人工智慧代表你撥打電話。常見使用情境：
- 預約確認
- 問卷回撥
- 未接來電後的「第二次」追蹤
- 調度式通知
先決條件
- 準備 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 分鐘）。