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

> 端到端流程：配置智能体，将其分配给电话号码，接听来电并查看转录文本。

<Note>
  首次手动构建智能体？控制台通过引导式向导带您完成完全相同的
  流程——构建智能体、添加号码、模拟、查看结果。请从
  [控制台快速入门](/zh/quickstart-dashboard)开始。
</Note>

从您的终端完成标准的“让 AI 接听电话”流程。
您将：

1. 使用提示词和语音创建智能体。
2. 配置（或自带）电话号码，并将该智能体指定为其
   呼入处理程序。
3. 拨打该号码。查看通话日志、转录文本和录音。

API 调用总数：四次。总耗时：不到五分钟。

## 1. 创建智能体

智能体整合了将驱动通话的提示词、语音和产品层级。
有关所有配置字段，请参阅[智能体](/api-reference/agents)；最小配置如下：

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'
```

保存返回的 `id`——您将在第 2 步中用到它。

<Tip>
  对于简单问答且希望成本最低的场景，选择 `spark`；速度最重要时，选择 `bolt`。
  当您的提示词需要更深入的推理，并且可以容忍模型思考时有半秒的填充语时，
  升级到 `storm-base-with-ack`。请参阅
  [产品层级](/api-reference/agents#product-tiers-at-a-glance)。
</Tip>

## 2. 获取电话号码

如果您只需要一个可供拨打的号码，请从 ThunderPhone 的号码池中配置一个演示号码：

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'
```

响应包含一个 `id` 和采用 E.164 格式的 `number`。演示号码
初始状态为 `status="provisioning"`，并会在几秒内变为 `active`——如果您需要关注此过程，
可轮询
[`GET /v1/phone-numbers/{id}`](/api-reference/phone-numbers#retrieve-a-phone-number)
以查看状态变化。

<Note>
  在生产环境中，请跳过演示号码，并通过
  [VoIP 自带号码](/zh/guides/bring-your-own-numbers)。
  演示号码仅支持呼入，且通话量受限。
</Note>

## 3. 分配智能体

将第 1 步中的智能体关联到该号码的呼入方向：

```bash theme={null}
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'
```

至此完成——该号码已启用。您还可以在同一个 PATCH 中设置 `outbound_agent_id`，
让该号码也能用于呼出。

## 4. 接听通话

使用您的手机拨打该号码。智能体会接听电话、根据您的提示词进行自我介绍，
然后对话开始。

通话进行期间，它会显示在
[`GET /v1/calls`](/api-reference/calls#list-calls)中，状态为
`status="in_progress"`。通话结束后，记录会更新
`end_reason`、`duration_seconds`、`billable_minutes`，以及（最终）
录音 URL 和 AI 评分。

## 5. 检查结果

获取最近通话列表：

```bash theme={null}
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

获取转录文本：

```bash theme={null}
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

以及录音 URL（短时有效，已签名）：

```bash theme={null}
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

如果您订阅了
[`telephony.complete` webhook](/zh/webhooks/events)，
您的服务器将通过 POST 收到相同的数据——请参阅
[call.complete](/zh/webhooks/call-complete)。

***

## 后续步骤

<CardGroup cols={2}>
  <Card title="动态单通话配置" icon="bolt" href="/zh/guides/dynamic-call-config">
    根据电话号码或 webhook 中的自定义逻辑，为每位来电者选择不同的智能体。
  </Card>

  <Card title="添加工具集成" icon="screwdriver-wrench" href="/zh/guides/build-tool-integration">
    让智能体在对话过程中调用您的 API。
  </Card>

  <Card title="接收 call.complete webhook" icon="bolt" href="/zh/webhooks/call-complete">
    将每个已完成的通话流式传输至您的 CRM／分析管道。
  </Card>

  <Card title="AI 评分和问题报告" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    自动为每次通话评分，并将标记的通话路由至审核。
  </Card>
</CardGroup>