---
title: "处理呼入电话（API）"
description: "端到端流程：配置智能体，将其分配给电话号码，接听来电，并查看通话转录文本。"
---
想要手动构建您的第一个智能体？控制台会通过引导式向导带您完成完全相同的
流程——构建智能体、添加号码、模拟、审核。请从
[控制台快速入门](/zh/quickstart-dashboard)开始。
通过您的终端完成标准的“让 AI 接听电话”流程。
您将：
1. 使用提示词和语音创建智能体。
2. 配置（或接入）一个电话号码，并将该智能体指定为其
呼入处理程序。
3. 拨打该号码。查看通话日志、转录文本和录音。
API 调用总数：四次。总耗时：不到五分钟。
## 1. 创建智能体
智能体将驱动通话的提示词、语音和产品层级整合在一起。您还可以在智能体上设置通话限制，例如 `max_call_duration_seconds`
和 `ring_duration_seconds`。智能体还支持使用 `intro_clip`
和 `intro_ring_count`，在智能体说话前播放预录开场音频并响铃最多两次。新建智能体还需要设置时区。
有关所有配置字段，请参阅[智能体](/api-reference/agents)；最低配置要求为：
```bash
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 中需要它。
对于成本最低的简单问答，请选择 `spark`；当速度
最重要时，请选择 `bolt`。当您的提示词需要更深入的推理，并且可以接受模型
思考时约半秒的填充语时，请升级到 `storm-base-with-ack`。请参阅
[产品层级](/api-reference/agents#product-tiers-at-a-glance)。
## 2. 获取电话号码
如果您只需要一个可拨打的号码，请从 ThunderPhone 的号码池中获取
一个 ThunderPhone 号码：
```bash
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`。ThunderPhone
号码初始状态为 `status="provisioning"`，并会在几秒内变为 `active`——如果您
需要关注此过程，可轮询
[`GET /v1/phone-numbers/{id}`](/api-reference/phone-numbers#retrieve-a-phone-number)
以查看状态转换。
ThunderPhone 号码初始仅支持呼入。组织管理员可在“电话号码”页面申请
外呼功能。ThunderPhone 会人工审核每项申请；审核通过后，号码即可拨打电话并运行
营销活动。客户的 VoIP 号码不受影响。
## 3. 分配智能体
将步骤 1 中的智能体关联到该号码的呼入方向：
```bash
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`。在此之前，API 会以 `400` 拒绝该分配。
如果您通过配置 webhook 而非固定的 `inbound_agent_id` 路由呼入电话，该 webhook 现在还可以随 `agent_id` 和 `variables` 一并返回每通电话的 `timezone`。
## 4. 接听来电
使用您的电话拨打该号码。智能体会接听，根据您的提示词进行自我介绍，
然后开始对话。
在通话进行期间，您可以通过
[`GET /v1/calls`](/api-reference/calls#list-calls) 查看它，其状态为
`status="in_progress"`。通话结束后，记录会更新 `end_reason`、
`duration_seconds`、`billable_minutes`，以及（最终的）
录音 URL 和 AI 评分。
呼入电话会计入您组织的
[并发通话限制](/api-reference/introduction#call-limits)（默认最多 20
通正在进行的通话，与呼出、网页和测试
通话共享）。达到限制时呼入的通话会在智能体接听前被拒绝并挂断，不会计费，并会记录为失败通话，结束原因是 `concurrent_call_limit_reached`。如果您
需要更高的限制，请发送电子邮件至 support@thunderphone.com。
## 5. 检查结果
获取最近通话列表：
```bash
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
获取转录文本：
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
以及录音 URL（短时有效，已签名）：
```bash
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)。
如果您的智能体配置了解析字段，已完成通话的载荷还可包含结构化提取数据。
---
## 后续步骤
根据电话号码或 webhook 中的自定义逻辑，为每位来电者选择不同的智能体。
让智能体在通话过程中调用您的 API。
直接路由来电者，或在接通前筛选目标方。
将每通已完成的通话流式传输至您的 CRM／分析管道。
自动为每通通话评分，并将标记的通话路由至审核。