---
title: "通过 Slack 或聊天应用运行通话"
description: "使用公开 API 构建您自己的 Slack、Teams 或网页聊天机器人，用于发起通话、实时跟进通话、引导智能体并回答其问题。"
---

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

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

## 整体工作方式

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

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

## 开始之前

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

<Tip>
  请使用您为自己的工作区创建的 Slack 应用，并通过 Slack 的 Events API 接收消息，而不是读取频道历史记录。Slack 对分发到 Marketplace 外其他工作区的应用施加了严格的读取限制；您为自己的工作区构建的应用不受这些限制，并且事件会在发生时直接送达您，无需任何读取操作。典型的机器人权限范围包括：`chat:write`、`app_mentions:read`、`im:history`（私信）、`channels:history` 和 `groups:history`（机器人所在的公共和私有频道中的会话串回复）。订阅机器人事件
  `app_mention`、`message.im`、`message.channels` 和 `message.groups`，并在 App Home 下开启 Messages 选项卡，以便用户可以向机器人发送私信。
</Tip>

## 1. 从消息发起通话

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

```bash
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 签名](/zh/guides/verify-webhook-signatures)。
- **根据信封中的 `event_id` 去重，并按 `position` 排序。**
  投递至少会发生一次，且轮次可能乱序到达。
- 如果繁忙的通话会使讨论串消息过多，请**批量发布消息**；每隔几秒发布一次
  比每行单独发布一条消息更易阅读。

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

## 3. 从讨论串引导通话

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

```bash
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 连接](/zh/guides/build-tool-integration)，并关联到智能体。
每个工具请求都会在其 `X-ThunderPhone-Call-ID` 标头中携带通话信息。

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

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

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

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

```bash
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` 前无人回复，智能体会被告知未收到答案，并向对方提供后续选项。在某通话的问题处于待处理状态期间，其线程中的下一条回复会回答该问题：将其作为工具结果发送，不要同时将其作为耳语发送（耳语只能在工具返回后传达给智能体）。请参阅
[长时间等待](/zh/tools/overview)。

**在请求中等待（最长 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 分钟才能获得的答案，请使用此方式。通话不会被保持：您的提示词应告知
智能体在此期间应如何处理，例如陪对方聊天或提出回电。

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

```text
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`](/api-reference/organizations#legacy-single-url-webhook) 中的 Webhook 密钥。
- 决定哪些人可以发起通话：在拨打前检查 Slack 用户 ID。
- 外呼通话遵循与其他通话相同的规则。请参阅[外呼法律](/zh/guides/outbound-calling-laws)。

## 使用编程智能体构建

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