ThunderPhone v3 已正式上线。全程自助,低至2美分/分钟。查看发布公告

Developer cookbook

通过 Slack 或聊天应用运行通话

使用公开 API 构建您自己的 Slack、Teams 或网页聊天机器人,用于发起通话、实时跟进通话、引导智能体并回答其问题。

您可以通过团队已在使用的聊天应用驱动智能体。一条消息即可发起通话。通话会在会话串中实时展开。在会话串中回复即可引导智能体。当智能体需要您做出决定时,它会在那里询问您并等待您的回答。

ThunderPhone 不会为您托管此机器人。您(或您的编程智能体)需要构建一个小型服务器,将您的聊天应用连接到公共 API。本页面展示所需的组成部分。对于 Slack、Microsoft Teams、Discord 或私有网页聊天页面,它们都相同;示例使用 Slack。

整体工作方式

您在聊天中执行的操作您的机器人调用结果
发送“致电 Comcast 并获取故障预计恢复时间”使用该消息作为 context 调用 POST /v1/call智能体拨打电话。您的机器人为该通话创建一个会话串
查看会话串接收 telephony.turn webhook智能体或对方说出的每一句话都会显示在会话串中
在通话过程中回复会话串POST /v1/calls/{call_id}/whisper智能体会私下收到您的备注并据此行动。对方永远不会听到
回答智能体的问题您的工具端点返回您的答案,或稍后通过 POST /v1/calls/{call_id}/tool-results 发送答案智能体会据此继续通话;在保持模式下,对方同时会听到等待音乐
阅读结果接收 telephony.complete您的机器人会发布摘要和结果

您的机器人只需维护一个映射:哪个聊天会话串属于哪个 call_id。

开始之前

  • API 密钥,存放在您的服务器上,绝不放在浏览器或聊天应用中。 请在 集成 → API 密钥 下创建一个(请参阅 创建服务器 API 密钥)。
  • 用于通话的已启用外呼的号码和智能体。消息会成为每次通话的 context,因此一个通用智能体即可处理所有任务。
  • 可接收 Webhook 的服务器,例如 Railway、Fly.io、Render 或您自己的主机。
  • 指向该服务器并订阅了 telephony.turn 和 telephony.complete 的 Webhook 端点。仅会向列出这些事件的端点发送轮次事件。请参阅 Webhook。 轮次事件需要启用智能体的通话录音,而通话结束时的 summary 需要启用智能体的 生成通话摘要 设置;否则这些字段将保持为空。
  • 您自己的聊天应用。对于 Slack,请在您的工作区中通过 api.slack.com/apps 创建应用。

1. 从消息发起通话

当您的机器人收到消息(私信或 @提及)时, 请立即确认 Slack 的请求(Slack 会重试任何在 3 秒内未确认的请求), 并在后台完成其余操作。检查发送者是否有权发起通话,然后将该消息作为 context 发起通话:

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":   "+18005550100",
    "agent_id":    12,
    "context":     "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
    "idempotency_key": "slack-D012AB3CD-1731000000.000100"
  }'

将返回的 call_id 与 Slack 讨论串(channel 加上消息的 ts)关联保存,并在线程中回复(“正在呼叫…”)。使用频道和消息的 ts 构建 idempotency_key(ts 仅在所属频道内唯一),以便重试的 Slack 事件不会发起第二次通话。如果请求指定的是人员而不是号码,您的机器人会 先查找该号码。ThunderPhone 只会拨打您发送的 to_number。

2. 在线程中跟进通话

每个 telephony.turn Webhook 都会携带 call_id、发言者(role: 智能体为 assistant,另一方为 user)、text 以及该轮次的 position。通过 call_id 查找讨论串,并发布该行内容。

  • **在对 Webhook 执行操作前验证每一个 Webhook。**请参阅 验证 Webhook 签名。
  • 根据信封中的 event_id 去重,并按 position 排序。 投递至少会发生一次,且轮次可能乱序到达。
  • 如果繁忙的通话会使讨论串消息过多,请批量发布消息;每隔几秒发布一次 比每行单独发布一条消息更易阅读。

当收到 telephony.complete 时,发布通话的结束方式(其 status 和 end_reason)、summary 以及所有提取的数据,然后结束该讨论串。字段说明请参阅 通话完成。

3. 从讨论串引导通话

当有人回复进行中通话的讨论串时,将该回复作为私语发送,除非智能体正在等待 问题的答案(步骤 4);在这种情况下,该回复就是答案:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ask whether they can waive the late fee."}'

智能体会私下听到这条内容,并将其融入下一轮对话;另一方绝不会听到私语本身。 私语长度为 1 到 1000 个字符。409 表示通话已不再进行中:请在讨论串中告知通话已结束。

4. 让智能体向您提问

为智能体提供一个工具,例如带有一个 question 参数、可调用您服务器的 ask_owner。将其创建为一个 API 连接,并关联到智能体。 每个工具请求都会在其 X-ThunderPhone-Call-ID 标头中携带通话信息。

有三种方式可以获取答案。

将通话保持最长 10 分钟。将工具设置为保持模式:通过 API 将 spec.wait_mode 设置为 "hold",并将 spec.timeout 设置为最多 600 秒(未设置超时时间时,保持状态持续 20 秒),或者请 Zeus 进行设置(应用的编辑器目前尚未提供这两个字段)。您的端点将问题发布到通话的线程中,并立即返回待处理结果:

{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}

对方会先听到智能体说的一句话,然后听到保持音乐。在电话菜单或语音信箱中,智能体会改用语音更新;全双工智能体则不会保持通话:它会将待处理回复作为结果接收。当线程中收到回复后,请通过 POST /v1/calls/{call_id}/tool-results 发送:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'

音乐会渐弱,智能体随后会根据您的答案继续对话。如果在 timeout 前无人回复,智能体会被告知未收到答案,并向对方提供后续选项。在某通话的问题处于待处理状态期间,其线程中的下一条回复会回答该问题:将其作为工具结果发送,不要同时将其作为耳语发送(耳语只能在工具返回后传达给智能体)。请参阅 长时间等待。

在请求中等待(最长 3 分钟)。 您的端点发布问题后,等待回复并将其返回,例如 {"answer": "Yes, book Tuesday at 10."}。 通过 API 设置工具的 spec.timeout,最长为 180 秒(默认值为 20 秒)。为您的端点设置一个提前几秒的截止时间 (例如 170 秒),这样即使无人回复,它仍会返回智能体可执行的内容,例如 {"answer": null, "note": "No reply yet. Offer to take a message."}。达到其 timeout 的工具会以错误形式传达给智能体,并且您的主机必须保持请求处于打开状态这么长时间。在等待期间,智能体会告知对方正在查询,大约 12 秒后说明仍在处理中,之后大约每 15 秒提供一次简短更新。这里同样可以使用保持模式:将 spec.wait_mode 设为 "hold",对方将听到音乐而非更新。

通过耳语回答。 您的端点发布问题后立即返回, 例如 {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}。 收到回复后,将其作为耳语发送(第 3 步),智能体会立即对此作出回应。对于可能需要超过 10 分钟才能获得的答案,请使用此方式。通话不会被保持:您的提示词应告知 智能体在此期间应如何处理,例如陪对方聊天或提出回电。

无论采用哪种方式,都应在智能体的提示词中说明何时使用该工具,以及在等待期间应向对方说明什么:

When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.

需要提前规划的限制

  • 您的端点必须在工具的 timeout 内响应,最长为 180 秒。处于保持模式的工具可在结果待定期间将通话保持最多 600 秒。
  • 工具等待期间,智能体不会回应另一方。处于保持模式时,对方会听到音乐;否则,会听到简短的语音更新。
  • 耳语消息最多为 1000 个字符。
  • telephony.turn 至少投递一次,且可能乱序。

安全检查清单

  • 将 API 密钥保留在您的服务器上。
  • 验证 ThunderPhone 在 Webhook 和工具请求中的签名,以及 Slack 在 Slack 请求中的签名密钥。这两种 ThunderPhone 签名使用不同的密钥:Webhook 投递使用 Webhook 端点自身的密钥,工具请求使用您组织在 GET /v1/webhook 中的 Webhook 密钥。
  • 决定哪些人可以发起通话:在拨打前检查 Slack 用户 ID。
  • 外呼通话遵循与其他通话相同的规则。请参阅外呼法律。

使用编程智能体构建

让您的编程智能体访问文档 MCP 服务器和本页面,并要求其“为我的 ThunderPhone 智能体创建一个遵循本指南的 Slack 机器人”。ThunderPhone 应用中的智能体 Zeus 可以配置智能体侧的内容(Webhook 端点、工具和提示词行),并在聊天中为机器人编写起始代码。