ThunderPhone v3 現已上線。自助開通,價格低至每分鐘 2¢。查看公告

Developer cookbook

撥出電話(API)

透過你的程式碼觸發由 AI 驅動的撥出電話——適用於問卷調查、跟進或確認流程。

外撥通話讓你將目標電話號碼及智能體設定交予 ThunderPhone,由 AI 代你撥出電話。常見使用情境:

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

先決條件

  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"
    }
  }'

控制最後一次靜默確認後的處理方式

你亦可在已儲存智能體所使用的內聯 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_allowedThunderPhone 不會致電該號碼:無效號碼、緊急服務號碼、增值服務號碼、短碼、受制裁國家/地區,或你的機構已封鎖作外撥用途的美國州份。使用 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,該次通話將採用每次通話的設定值。


下一步