Open in
通过 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 端点、工具和提示词行),并在聊天中为机器人编写起始代码。