> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 撥打外撥電話（API）

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

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

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

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

## 先決條件

<Steps>
  <Step title="準備 VoIP 號碼">
    對外撥號要求你透過
    [VoIP 連線](/api-reference/voip-connections)擁有 `from_number`。
    示範號碼僅限撥入。請參閱
    [自備號碼](/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`。透過
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    儲值，或啟用[自動儲值](/api-reference/billing#update-auto-reload)。
  </Step>
</Steps>

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

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

```bash theme={null}
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
  }'
```

回應：

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

## 值得處理的失敗情境

| 錯誤                                                       | 處理方式                                                                                                      |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `402 Payment Required`                                   | 儲值餘額或啟用自動儲值                                                                                               |
| `403` 對外撥號遭封鎖（示範號碼）                                      | 改用 VoIP 號碼                                                                                                |
| `403` 對外撥號遭封鎖（未驗證的 VoIP）                                 | 執行 [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `404 from_number is not registered to this organization` | 確認 `from_number` 與你擁有的電話號碼相符                                                                              |
| `502 Bad Gateway`                                        | 暫時性的 SIP／LiveKit 故障；可安全重試                                                                                 |

## 控制保留時間

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

```json theme={null}
{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "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>