> ## 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）

> 从您自己的代码中触发由 AI 驱动的外呼——用于问卷调查、跟进或确认流程。

外呼功能允许您将目标号码和智能体配置交给 ThunderPhone，由 AI 代表您拨打电话。典型用例包括：

* 预约确认
* 调研回访
* 未接来电后的“二次尝试”跟进
* 调度式通知

<Note>
  需要呼叫整个联系人列表？控制台的
  [**营销活动**](/zh/guides/outbound-campaigns) 功能
  （`/dashboard/campaigns`）可接收联系人 CSV，并为您处理
  时区感知的呼叫时段、并发和重试策略。本指南介绍单次程序化呼叫。
</Note>

## 前提条件

<Steps>
  <Step title="准备一个 VoIP 号码">
    外呼要求您通过
    [VoIP 连接](/api-reference/voip-connections)拥有 `from_number`。
    演示号码仅支持呼入。请参阅
    [自带号码](/zh/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/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/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/webhooks/call-complete">
    将已完成的外呼通话流式传输到您的系统。
  </Card>

  <Card title="计费" icon="credit-card" href="/api-reference/billing">
    自动充值，确保外呼不会因余额不足而失败。
  </Card>

  <Card title="测试外呼智能体" icon="flask" href="/zh/guides/test-agents">
    在生产环境前对您的外呼智能体进行试运行。
  </Card>
</CardGroup>