撥打外撥電話（API）

從你自己的程式碼觸發由人工智慧驅動的外撥電話——適用於問卷調查、後續追蹤或確認流程。

撥出電話可讓你將目標電話號碼和智慧體 設定交給 ThunderPhone，由人工智慧代你撥打電話。常見使用情境：

• 預約確認
• 問卷回撥
• 未接來電後的「第二次」追蹤
• 派遣式通知

先決條件#

1. 選擇已啟用撥出功能的號碼

   透過你擁有的 VoIP 連線使用號碼，或從「電話號碼」 頁面申請使用你的 ThunderPhone 號碼撥出電話。ThunderPhone 號碼起初僅能接聽來電。ThunderPhone 會人工審核每項 申請；核准後，這些號碼即可在核准的每日上限內撥打電話（於 UTC 00:00 重設）並執行行銷活動，你也可以申請提高上限。客戶的 VoIP 號碼沒有每日上限，因此我們建議 用於撥出電話。請參閱 自備號碼。

2. 建立智慧體

   適合撥出電話的提示詞通常會先讓智慧體 說明自己的身分與目的——「你好，這裡是 Acme，致電確認你明天下午 3 點的預約……」將 outbound_speak_order 設為 agent_first（預設值）。

3. 維持正餘額

   若餘額 ≤ $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"
    }
  }'

追蹤通話#

同時訂閱 telephony.complete webhook—— 這是得知通話已結束最快的方式。若你無法接收傳入的 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 範例不使用它們。

值得處理的失敗情況#

請參閱撥出通話參考資料， 取得完整且穩定的資格代碼清單，以及兩種 409 回應格式。 若有效號碼在請求已接受後、通話撥出前變得不符合資格， 最終檢查會傳回不可重試的 409 承載資料。

控制等待時間#

若因受話方回應緩慢而導致撥出通話時間過長 （IVR 選單、佇列），可使用 max_hold_seconds 設定上限：

{
  "from_number": "+15551234567",
  "to_number":   "+14155552671",
  "agent_id":    12,
  "max_hold_seconds": 120
}

若過去 N 秒內未收到任何真人語音，智慧體會掛斷通話。預設為 900 秒（15 分鐘）。

後續步驟#