---
title: "将 ThunderPhone 与 n8n 配合使用"
description: "安装适用于 n8n 的 ThunderPhone 节点，连接服务器 API 密钥，并构建一个在每次通话结束时运行的工作流。"
---

[n8n](https://n8n.io) 是一款工作流自动化工具。适用于 n8n 的 ThunderPhone 软件包
添加了两个节点：

- **ThunderPhone Trigger** 会在通话结束（**通话完成**）或通话评分运行完成（**通话已评分**）时启动工作流。
- **ThunderPhone** 可发起外呼、将联系人添加到营销活动并启动营销活动、获取包含转录文本和录音的通话，以及列出您的智能体和电话号码。

它是经过验证的社区节点，已列于
[n8n 上的 ThunderPhone](https://n8n.io/integrations/thunderphone/)。

## 安装节点

在 n8n 编辑器中，点击 **+** 打开节点面板，然后搜索
**ThunderPhone**。在其他用户可以添加节点前，实例所有者可能需要先设置已验证节点。

在自托管的 n8n 上，您也可以通过软件包名称安装：打开
**设置 > 社区节点**，然后安装 `n8n-nodes-thunderphone`。安装前，请检查社区节点风险和您的实例策略。

## 创建服务器 API 密钥

<Steps>
  <Step title="打开“密钥”选项卡">
    在 ThunderPhone 中，前往 **组织 → 密钥**，然后点击 **创建密钥**。
  </Step>
  <Step title="为其命名">
    使用能说明密钥存放位置的名称，例如“n8n”。
  </Step>
  <Step title="立即复制">
    完整的 `sk_live_...` 密钥仅显示一次。关闭对话框前请复制它。
  </Step>
</Steps>

只有管理员或所有者可以创建此密钥，ThunderPhone 会将使用该密钥发出的请求视为来自该人员。触发器和营销活动操作需要该人员持续拥有管理员或所有者角色。
[创建服务器 API 密钥](/zh/guides/api-keys)涵盖轮换和撤销。

## 在 n8n 中添加凭据

1. 在 n8n 中，创建类型为 **ThunderPhone API** 的凭据。
2. 将密钥粘贴到 **API 密钥** 中。
3. 保存并运行凭据测试。该测试会通过 `GET /v1/calls?limit=1` 读取您组织中的一条通话记录。

## 构建第一个工作流

此工作流会在每次通话结束时向 Google 表格添加一行。

<Steps>
  <Step title="添加触发器">
    添加 **ThunderPhone Trigger**，选择您的 ThunderPhone API 凭据，并将
    **Event** 设置为 **Call Completed**。
  </Step>
  <Step title="获取通话">
    添加一个 **ThunderPhone** 节点。将 **Resource** 设置为 **Call**，将 **Operation**
    设置为 **Get**，并将 **Call ID** 设置为表达式 `{{ $json.data.call_id }}`。
    输出内容包括[通话记录](/api-reference/calls)，以及 `transcripts`
    和 `recording_url`。后者是一个短时有效链接，当通话没有录音时，其值为 `null`。
  </Step>
  <Step title="追加一行">
    添加一个用于追加行的 Google 表格节点，并映射您希望使用的
    Get Call 输出列（请参阅下表）。
  </Step>
  <Step title="激活工作流">
    保存并激活。触发器会将其生产 URL 注册为您 ThunderPhone 组织中的 webhook
    端点。停用工作流会删除该端点。
  </Step>
  <Step title="测试">
    在构建器中打开一个智能体，点击 **Talk**，然后结束通话。构建器
    测试通话会以 `web.complete` 的形式发送，该事件是 Call Completed
    背后的两个事件之一，因此工作流会运行并显示一行数据。
  </Step>
</Steps>

实用列：

| 列 | 表达式 |
|---|---|
| 通话 ID | `{{ $json.call_id }}` |
| 方向 | `{{ $json.direction }}` |
| 来电号码 | `{{ $json.from_number }}` |
| 去电号码 | `{{ $json.to_number }}` |
| 开始时间 | `{{ $json.start_time }}` |
| 时长（秒） | `{{ $json.duration_seconds }}` |
| 状态 | `{{ $json.status }}` |
| 结束原因 | `{{ $json.end_reason }}` |
| 通话链接 | `https://app.thunderphone.com/dashboard/call-history/{{ $json.call_id }}` |

通话链接会为您组织中的成员在 ThunderPhone 控制台中打开该通话，
其中包含其转写文本和录音，因此表格无需保存这两项内容。

如仍需添加转写文本，请映射
`{{ $json.transcripts.filter(t => typeof t.content === 'string').map(t => t.role + ': ' + t.content).join('\n') }}`。
录音 URL 会过期，因此请保存通话 ID，并在您需要新链接时再次运行 Get Call。
通话转写文本、摘要和录音可能包含个人或健康信息。请仅将其发送到您的组织获准
用于处理此类数据的应用；涉及健康信息时，请在 BAA 框架下处理；并且仅保留您所需的字段。

<Note>
  ThunderPhone 使用 `POST` 将事件发送到触发器的 **Production
  URL**，因此您的 n8n 实例必须可通过 HTTPS 从互联网访问，
  并且工作流必须处于激活状态。触发器会验证每个请求中的
  `X-ThunderPhone-Signature` HMAC，并对任何未签名或无效的请求返回 `401`。
</Note>

触发器会输出完整事件：`type`、`event_id` 和 `data`。有关所有字段，请参阅
[`telephony.complete` / `web.complete`](/zh/webhooks/call-complete) 和
[`call.graded`](/zh/webhooks/events)。事件至少会投递一次，并且同一事件在重试期间的
`event_id` 保持不变，因此请在不得重复执行的步骤之前检查它。

## 安全地发起外呼

**发起外呼**（资源 **外呼通话**，操作 **发起**）
需要：

| 字段 | 含义 |
|---|---|
| 智能体名称或 ID | 已保存的智能体。下拉列表会列出您的智能体。 |
| 电话号码名称或 ID | 主叫号码。下拉列表仅列出已启用外呼的号码。 |
| 被叫号码 | 采用 E.164 格式的目标号码，例如 `+14155552671`。 |
| 变量 | 用于智能体提示词中占位符值的 JSON 对象。 |
| 幂等键 | 来自上游记录或事件的稳定 ID。必填。 |

将 **幂等键** 映射到触发运行的对象 ID，例如 CRM 记录 ID 或触发器的 `event_id`。该节点会发送
`n8n:<node ID>:<your value>`，因此：

- 自动重试或 **重试执行** 会发送相同的键，ThunderPhone 会返回原始通话并附带 `idempotent_replay: true`，而不会再次拨号。
- 由同一记录提供数据的两个 ThunderPhone 节点会发送不同的键。
- 空白值会在发送任何请求之前失败。

避免使用时间戳、随机值以及 n8n 执行或工作流 ID。重试时使用新值会发起第二通真实通话。整个键最多可包含 128 个字符。使用不同的智能体、号码或变量重复使用某个键会因冲突而失败。

**活动。** **添加联系人**（资源 **活动**）会将联系人添加到草稿活动中。它需要活动 ID 和联系人 JSON 数组。每个联系人都需要 `phone_number`；其他键会成为通话变量。当所有联系人均被拒绝时，该节点会失败；仅部分联系人被拒绝时，会设置 `partial_success: true`。**开始**要求您勾选确认框，确认该活动会发起真实通话并消耗 ThunderPhone 额度。请参阅[外呼活动](/zh/guides/outbound-campaigns)。

在工作流开始发起通话之前：

- 如果 ThunderPhone 要求您的组织确认其外呼符合 TCPA 及其他通话法律，管理员必须先在控制台中记录该确认。
- 主叫号码必须已启用外呼。您从自有运营商引入的号码在完成验证后即可使用。ThunderPhone 号码最初仅支持呼入，之后可获批用于外呼：管理员可在电话号码页面提出申请。请参阅
  [获取电话号码](/zh/guides/get-a-phone-number)。
- 您的组织负责确保已获得呼叫每个号码的同意，并遵守适用的通话法律。请参阅
  [外呼法律](/zh/guides/outbound-calling-laws)。

## 示例工作流

- **将 CRM 联系人添加到活动。** 将 CRM 联系人添加到 ThunderPhone 草稿活动中，然后在有人批准列表后启动该活动。
- **将已完成通话写入客户记录。** 在通话完成时，运行获取通话，并将转录文本和录音链接保存到匹配的客户记录中。
- **将低评分通话送审。** 在通话评分完成时，按
  `{{ $json.data.grade.score }}` 进行筛选，并将低评分通话连同通话 ID 和评分详情路由到审核队列。一次通话可能被评分多次，且每次完成评分都会触发该触发器，因此请仅保留每个通话 ID 最新的
  `graded_at`。

通话转录文本、摘要和录音可能包含个人信息或健康信息。仅将其发送到您的组织获准用于处理此类数据的应用；涉及健康信息时，应依据 BAA，并且仅保留您所需的字段。

<Note>
  改为将相同的通话事件发送到您自己的服务器？请参阅
  [Webhook 端点](/zh/webhooks/endpoints)。
  [发起外呼](/zh/guides/place-outbound-calls)介绍了发起外呼所使用的 API。
</Note>