Open in
将 ThunderPhone 与 n8n 配合使用
安装适用于 n8n 的 ThunderPhone 节点，连接服务器 API 密钥，并构建一个在每次通话结束时运行的工作流。
n8n 是一款工作流自动化工具。适用于 n8n 的 ThunderPhone 软件包 添加了两个节点：
- ThunderPhone Trigger 会在通话结束（通话完成）或通话评分运行完成（通话已评分）时启动工作流。
- ThunderPhone 可发起外呼、将联系人添加到营销活动并启动营销活动、获取包含转录文本和录音的通话，以及列出您的智能体和电话号码。
它是经过验证的社区节点，已列于 n8n 上的 ThunderPhone。
安装节点
在 n8n 编辑器中，点击 + 打开节点面板，然后搜索 ThunderPhone。在其他用户可以添加节点前，实例所有者可能需要先设置已验证节点。
在自托管的 n8n 上，您也可以通过软件包名称安装：打开
设置 > 社区节点，然后安装 n8n-nodes-thunderphone。安装前，请检查社区节点风险和您的实例策略。
创建服务器 API 密钥
- 打开“密钥”选项卡
在 ThunderPhone 中，前往 组织 → 密钥，然后点击 创建密钥。
- 为其命名
使用能说明密钥存放位置的名称，例如“n8n”。
- 立即复制
完整的
sk_live_...密钥仅显示一次。关闭对话框前请复制它。
只有管理员或所有者可以创建此密钥，ThunderPhone 会将使用该密钥发出的请求视为来自该人员。触发器和营销活动操作需要该人员持续拥有管理员或所有者角色。 创建服务器 API 密钥涵盖轮换和撤销。
在 n8n 中添加凭据
- 在 n8n 中，创建类型为 ThunderPhone API 的凭据。
- 将密钥粘贴到 API 密钥 中。
- 保存并运行凭据测试。该测试会通过
GET /v1/calls?limit=1读取您组织中的一条通话记录。
构建第一个工作流
此工作流会在每次通话结束时向 Google 表格添加一行。
- 添加触发器
添加 ThunderPhone Trigger，选择您的 ThunderPhone API 凭据，并将 Event 设置为 Call Completed。
- 获取通话
添加一个 ThunderPhone 节点。将 Resource 设置为 Call，将 Operation 设置为 Get，并将 Call ID 设置为表达式
{{ $json.data.call_id }}。 输出内容包括通话记录，以及transcripts和recording_url。后者是一个短时有效链接，当通话没有录音时，其值为null。 - 追加一行
添加一个用于追加行的 Google 表格节点，并映射您希望使用的 Get Call 输出列（请参阅下表）。
- 激活工作流
保存并激活。触发器会将其生产 URL 注册为您 ThunderPhone 组织中的 webhook 端点。停用工作流会删除该端点。
- 测试
在构建器中打开一个智能体，点击 Talk，然后结束通话。构建器 测试通话会以
web.complete的形式发送，该事件是 Call Completed 背后的两个事件之一，因此工作流会运行并显示一行数据。
实用列：
| 列 | 表达式 |
|---|---|
| 通话 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 框架下处理；并且仅保留您所需的字段。
触发器会输出完整事件：type、event_id 和 data。有关所有字段，请参阅
telephony.complete / web.complete 和
call.graded。事件至少会投递一次，并且同一事件在重试期间的
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 额度。请参阅外呼活动。
在工作流开始发起通话之前：
- 如果 ThunderPhone 要求您的组织确认其外呼符合 TCPA 及其他通话法律，管理员必须先在控制台中记录该确认。
- 主叫号码必须已启用外呼。您从自有运营商引入的号码在完成验证后即可使用。ThunderPhone 号码最初仅支持呼入，之后可获批用于外呼：管理员可在电话号码页面提出申请。请参阅 获取电话号码。
- 您的组织负责确保已获得呼叫每个号码的同意，并遵守适用的通话法律。请参阅 外呼法律。
示例工作流
- 将 CRM 联系人添加到活动。 将 CRM 联系人添加到 ThunderPhone 草稿活动中，然后在有人批准列表后启动该活动。
- 将已完成通话写入客户记录。 在通话完成时，运行获取通话，并将转录文本和录音链接保存到匹配的客户记录中。
- 将低评分通话送审。 在通话评分完成时，按
{{ $json.data.grade.score }}进行筛选，并将低评分通话连同通话 ID 和评分详情路由到审核队列。一次通话可能被评分多次，且每次完成评分都会触发该触发器，因此请仅保留每个通话 ID 最新的graded_at。
通话转录文本、摘要和录音可能包含个人信息或健康信息。仅将其发送到您的组织获准用于处理此类数据的应用；涉及健康信息时，应依据 BAA，并且仅保留您所需的字段。