撥打外撥電話（API）

外撥通話讓你將目的地號碼及智能體設定交給 ThunderPhone，由 AI 代表你撥出電話。常見使用案例：

• 預約確認
• 問卷回訪
• 未接來電後的「第二次嘗試」跟進
• 調度類型通知

先決條件

1. 準備一個 VoIP 號碼

   外撥通話要求你透過 VoIP 連線擁有 from_number。 示範號碼只支援來電。請參閱 自備號碼。

2. 建立智能體

   外撥導向的提示詞通常會由智能體先表明身分及致電目的——「你好，這裡是 Acme，致電確認你明天下午 3 時的預約……」將 outbound_speak_order 設為 agent_first（預設值）。

3. 保持正數餘額

   如餘額 ≤ $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 網絡回調的 回應結構一致：

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 網絡回調—— 這是得知通話已結束的最快方式。如你無法接收傳入網絡回調，請每隔數秒輪詢 GET /v1/calls/{call_id}；通話結束後，記錄會包括 end_reason、duration_seconds 及錄音 URL。

值得處理的失敗情況

控制等候時間

如因被叫方回應緩慢（例如 IVR 選單、排隊）而令外撥通話時間過長，可使用 max_hold_seconds 設定上限：

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

如過去 N 秒內未收到真人語音，智能體便會掛線。預設為 900 秒（15 分鐘）。

下一步