处理呼入电话（API）

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

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

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

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

1. 创建智能体#

智能体将驱动通话的提示词、语音和产品层级整合在一起。您还可以在智能体上设置通话限制，例如 max_call_duration_seconds 和 ring_duration_seconds。智能体还支持使用 intro_clip 和 intro_ring_count，在智能体说话前播放预录开场音频并响铃最多两次。新建智能体还需要设置时区。 有关所有配置字段，请参阅智能体；最低配置要求为：

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 中需要它。

2. 获取电话号码#

如果您只需要一个可拨打的号码，请从 ThunderPhone 的号码池中获取 一个 ThunderPhone 号码：

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} 以查看状态转换。

3. 分配智能体#

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

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 查看它，其状态为 status="in_progress"。通话结束后，记录会更新 end_reason、 duration_seconds、billable_minutes，以及（最终的） 录音 URL 和 AI 评分。

呼入电话会计入您组织的 并发通话限制（默认最多 20 通正在进行的通话，与呼出、网页和测试 通话共享）。达到限制时呼入的通话会在智能体接听前被拒绝并挂断，不会计费，并会记录为失败通话，结束原因是 concurrent_call_limit_reached。如果您 需要更高的限制，请发送电子邮件至 support@thunderphone.com。

5. 检查结果#

获取最近通话列表：

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

获取转录文本：

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

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

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

如果您订阅了 telephony.complete webhook， 您的服务器将收到相同数据的 POST 请求——请参阅 call.complete。

如果您的智能体配置了解析字段，已完成通话的载荷还可包含结构化提取数据。

后续步骤#