Open in
撥出電話(API)
透過你的程式碼觸發由 AI 驅動的撥出電話——適用於問卷調查、跟進或確認流程。
外撥通話讓你將目標電話號碼及智能體設定交予 ThunderPhone,由 AI 代你撥出電話。常見使用情境:
- 預約確認
- 問卷回訪
- 未接來電後的「再次嘗試」跟進
- 調度式通知
先決條件
- 選擇已啟用撥出功能的號碼
- 建立智能體
適用於撥出電話的提示詞通常會先由智能體 說明身分及目的——「你好,這是 Acme 致電確認你明日下午 3 時的預約……」將
outbound_speak_order設為agent_first(預設值)。 - 維持正數餘額
當餘額 ≤
$0.00時,撥出電話會返回402 Payment Required。你可在控制台的 組織 → 帳單設定儲值或啟用自動加值。你的sk_live_金鑰可透過GET /v1/billing查詢餘額,但 無法儲值或更改自動加值設定。
使用已儲存的智能體撥打電話
最簡單的方法——以 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": "+14155552671",
"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": "+14155552671",
"config": {
"prompt": "You are confirming Jane Doe appointment for 3pm tomorrow…",
"voice": "john",
"product": "spark"
}
}'控制最後一次靜默確認後的處理方式
你亦可在已儲存智能體所使用的內聯 config 中傳入相同的靜默最終操作設定:
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"config": {
"silence_final_action": "hang_up"
}
}使用 silence_final_action 選擇最後一次靜默確認後的處理方式。你亦可傳入 silence_final_message;如最終操作為轉接,則可傳入 silence_transfer_destination。
在內聯 config 中加入詞彙清單
內聯撥出電話可包含與已儲存智能體相同的 words 清單。
當你希望通話遵循自訂發音或聽辨規則,而無需先儲存智能體時,請使用此設定。
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"config": {
"prompt": "[REDACTED_LITERAL]",
"voice": "john",
"product": "spark",
"words": []
}
}追蹤通話
回應包含 queued_at 時間,表示 ThunderPhone 的外撥容量正在使用中:有可用容量時,系統會在 10 分鐘內撥出電話;如沒有可用容量,通話會以
end_reason outbound_queue_timeout 結束。你毋須重試。請參閱排隊中的通話。
同時,訂閱
telephony.complete Webhook——
這是得知通話已結束的最快方法。你亦可訂閱
call.status_changed,以取得撥號、已接聽、語音留言及保留狀態變更等即時進度更新。
如果你無法接收傳入 Webhook,請每隔數秒輪詢一次 GET /v1/calls/{call_id};
通話結束後,記錄將包含 end_reason、duration_seconds 及錄音 URL。
如果你的智能體設定為在通話後擷取結構化資料,該資料會在最終處理完成後另行傳送。
將每通通話變數傳遞至已儲存智能體
已儲存智能體可在提示文字中使用 {{name}} 或 {{name|there}} 等預留位置。使用 agent_id 撥打外撥電話時,請傳遞包含該通話數值的
variables:
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"agent_id": 12,
"variables": {
"name": "Jordan"
}
}使用以預留位置名稱為鍵的字串數值。這些變數適用於已儲存智能體;本指南的內嵌 config 範例不會使用它們。
值得處理的失敗情況
| 錯誤 | 修正方法 |
|---|---|
402 Payment Required | 為餘額增值或啟用自動增值 |
400 並附帶 code: destination_not_allowed | ThunderPhone 不會致電該號碼:無效號碼、緊急服務號碼、增值服務號碼、短碼、受制裁國家/地區,或你的機構已封鎖作外撥用途的美國州份。使用 ThunderPhone 號碼時,一般美國及加拿大號碼均可撥打,部分國際目的地亦可撥打,並按目的地費率收費。reason 會說明原因;請參閱已封鎖目的地 |
ThunderPhone 號碼的 409 並附帶 retryable: false | 按照 code 指示處理:在「電話號碼」頁面申請外撥功能、等待審核完成,或使用另一個合資格號碼 |
429 並附帶 code: platform_outbound_daily_limit_reached | 機構已用盡今天從 ThunderPhone 號碼撥出的通話額度。等待 resets_at(00:00 UTC)、在「電話號碼」頁面申請提高限額,或透過你自己的 VoIP 連線號碼撥打 |
429 並附帶 code: concurrent_call_limit_reached | 機構正在進行的通話數目已達到其並發通話限額(預設為 20,計入來電、外撥、網頁及測試通話)。在 Retry-After 標頭指定的秒數後,或在通話結束後重試;如需提高限額,請電郵至 support@thunderphone.com |
429 並附帶 code: outbound_queue_full | 機構已有 50 個排隊中的通話等待處理。在 Retry-After 標頭指定的秒數後重試 |
429 並附帶 code: same_number_too_soon | 你在不足 10 秒前已撥打相同的 to_number。在 Retry-After 標頭指定的秒數後重試 |
客戶 VoIP 號碼的 409 並附帶 retryable: false | 修正 code 所指的狀態;如驗證失敗,執行 POST /v1/phone-numbers/{id}/verify-voip |
409 冪等性衝突 | 僅可將該金鑰用於原來經正規化的請求,或傳送新金鑰 |
404 from_number is not registered to this organization | 確認 from_number 與機構內的有效電話號碼相符。已在佈建中、佈建失敗、正在釋出或已釋出的號碼亦會傳回此回應 |
僅包含 detail 欄位的 500 | 未設定外撥中繼。請聯絡支援團隊;這並非你可修正的號碼狀態問題 |
502 Bad Gateway | 暫時性的 SIP/LiveKit 故障;可安全重試 |
請參閱外撥通話參考資料,
了解完整且穩定的合資格代碼清單,以及兩種 409 回應格式。
如果有效號碼在請求已接受後、通話撥出前變為不合資格,
最終檢查會傳回不可重試的 409 payload。
控制等候時間
由於被叫方回應緩慢(IVR 選單、等候佇列)而歷時過長的外撥通話,可在通話中設定 max_hold_seconds 限制,或在已儲存的智能體中設定:
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"max_hold_seconds": 120
}如果在過去 N 秒內未收到任何真人語音,智能體會掛線。預設值為 900 秒(15 分鐘)。
如你同時在已儲存的智能體及外撥通話請求中設定 max_hold_seconds,該次通話將採用每次通話的設定值。