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

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

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

<Note>
  要撥打一整份名單嗎？控制台的
  [**行銷活動**](/zh-Hant/guides/outbound-campaigns) 功能
  （`/dashboard/campaigns`）可匯入聯絡人的 CSV，並為你處理
  依時區設定的撥打時段、並行數量和重試政策。本指南涵蓋單次以程式方式發起的通話。
</Note>

## 先決條件

<Steps>
  <Step title="選擇已啟用撥出功能的號碼">
    透過你擁有的
    [VoIP 連線](/api-reference/voip-connections)使用號碼，或從「電話號碼」
    頁面申請使用你的 ThunderPhone 號碼撥出電話。ThunderPhone 號碼起初僅能接聽來電。ThunderPhone 會人工審核每項
    申請；核准後，這些號碼即可在核准的每日上限內撥打電話（於 UTC 00:00 重設）並執行行銷活動，你也可以申請提高上限。客戶的 VoIP 號碼沒有每日上限，因此我們建議
    用於撥出電話。請參閱
    [自備號碼](/zh-Hant/guides/bring-your-own-numbers)。
  </Step>
  <Step title="建立智慧體">
    適合撥出電話的提示詞通常會先讓智慧體
    說明自己的身分與目的——「你好，這裡是 Acme，致電確認你明天下午 3 點的預約……」將
    `outbound_speak_order` 設為 `agent_first`（預設值）。
  </Step>
  <Step title="維持正餘額">
    若餘額 ≤
    `$0.00`，撥出電話會傳回 `402 Payment Required`。請在控制台的
    **組織 → 帳務設定**中儲值或啟用自動儲值。你的 `sk_live_`
    金鑰可透過
    [`GET /v1/billing`](/api-reference/billing#get-billing-account) 查詢餘額，但
    無法儲值或變更自動儲值設定。
  </Step>
</Steps>

## 使用已儲存的智慧體撥打電話

最簡單的方式——透過 ID 參照智慧體：

```bash
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
  }'
```

回應：

```json
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  `status: "initiated"` 僅表示請求已被接受——通話
  **尚未接通**。請輪詢
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  以取得即時狀態（`in_progress` → `completed` / `failed`）。
</Warning>

## 使用內嵌設定撥打電話

若你想使用不值得儲存為智慧體的一次性提示，
請改為傳遞 `config`。其結構與
[`call.incoming` webhook](/zh-Hant/webhooks/call-incoming) 的
回應結構描述相符：

```bash
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](/zh-Hant/webhooks/events)——
這是得知通話已結束最快的方式。若你無法接收傳入的
webhook，請每隔幾秒輪詢一次 `GET /v1/calls/{call_id}`；通話結束後，
紀錄會包含 `end_reason`、`duration_seconds` 和錄音
URL。

若你的智慧體設定為在通話後擷取結構化資料，
該資料會在最終處理完成後另行傳送。

### 將每通通話變數傳遞給已儲存的智慧體

已儲存的智慧體可在提示文字中使用 `{{name}}` 或 `{{name|there}}` 等
預留位置。使用 `agent_id` 撥打撥出電話時，請傳遞包含該通話值的
`variables`：

```json
{
  "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` 會說明原因；請參閱[已封鎖的目的地](/api-reference/outbound-calls#blocked-destinations) |
| 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` | 組織同時進行中的通話數量已達其[同時通話限制](/api-reference/introduction#call-limits)（預設為 20，包含來電、外撥、網頁及測試通話）。在 `Retry-After` 標頭指定的秒數後，或在通話結束後重試；寄信至 support@thunderphone.com 申請提高限制 |
| `429` 搭配 `code: same_number_too_soon` | 你在不到 10 秒前撥打過同一個 `to_number`。在 `Retry-After` 標頭指定的秒數後重試 |
| 客戶 VoIP 號碼的 `409` 搭配 `retryable: false` | 更正 `code` 指定的狀態；若驗證失敗，請執行 [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `409` 冪等性衝突 | 僅能使用原始的正規化請求重複使用該金鑰，或傳送新的金鑰 |
| `404 from_number is not registered to this organization` | 確認 `from_number` 與組織中的有效電話號碼相符。已處於佈建中、失敗、釋放中或已釋放狀態的號碼，也會傳回此回應 |
| 僅含 `detail` 欄位的 `500` | 未設定外撥中繼。請聯絡支援團隊；這不是你可自行修正的號碼狀態問題 |
| `502 Bad Gateway` | 暫時性的 SIP／LiveKit 失敗；可安全重試 |

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

## 控制等待時間

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

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

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

---

## 後續步驟

<CardGroup cols={2}>
  <Card title="撥出通話參考資料" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    所有請求欄位與錯誤代碼。
  </Card>
  <Card title="接收 call.complete" icon="bolt" href="/zh-Hant/webhooks/call-complete">
    將已完成的撥出通話串流至你的系統。
  </Card>
  <Card title="帳務" icon="credit-card" href="/api-reference/billing">
    啟用自動儲值，避免撥出通話因餘額不足而失敗。
  </Card>
  <Card title="測試撥出智慧體" icon="flask" href="/zh-Hant/guides/test-agents">
    在正式環境前，先試跑你的撥出智慧體。
  </Card>
</CardGroup>