---
title: "撥打外撥電話（API）"
description: "從你自己嘅程式碼觸發由 AI 驅動嘅外撥電話——用於問卷調查、跟進或確認流程。"
---

外撥功能讓你將目的地號碼及智能體設定交給 ThunderPhone，由 AI 代你撥打電話。常見使用情境：

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

<Note>
  要致電整份名單？控制台的
  [**推廣活動**](/yue/guides/outbound-campaigns) 功能
  （`/dashboard/campaigns`）可匯入聯絡人的 CSV，並為你處理
  支援時區的撥號時段、並行數量及重試政策。本指南涵蓋單次程式化通話。
</Note>

## 先決條件

<Steps>
  <Step title="自備 VoIP 號碼">
    外撥功能要求你透過
    [VoIP 連線](/api-reference/voip-connections) 擁有 `from_number`。
    ThunderPhone 號碼只支援來電。請參閱
    [自備號碼](/yue/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
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
{ "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](/yue/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":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'
```

## 追蹤通話

同時訂閱
[`telephony.complete` webhook](/yue/webhooks/events)——這是最快得知通話已結束的方法。如你無法接收傳入 webhook，請每隔數秒輪詢 `GET /v1/calls/{call_id}`；通話結束後，記錄會包含 `end_reason`、`duration_seconds` 及錄音 URL。

## 值得處理的失敗情況

| 錯誤 | 解決方法 |
|-------|-----|
| `402 Payment Required` | 為餘額儲值或啟用自動儲值 |
| `403` 已封鎖外撥（ThunderPhone 號碼） | 改為自備 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
{
  "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="/yue/webhooks/call-complete">
    將已完成的外撥通話串流至你的系統。
  </Card>
  <Card title="帳單" icon="credit-card" href="/api-reference/billing">
    自動增值，確保外撥不會因餘額不足而失敗。
  </Card>
  <Card title="測試外撥智能體" icon="flask" href="/yue/guides/test-agents">
    在正式環境前試行你的外撥智能體。
  </Card>
</CardGroup>