---
title: "將 ThunderPhone 與 n8n 一同使用"
description: "安裝適用於 n8n 的 ThunderPhone 節點、連接伺服器 API 金鑰，並建立一個在每次通話結束時執行的工作流程。"
---

[n8n](https://n8n.io) 是一個工作流程自動化工具。適用於 n8n 的 ThunderPhone 套件
新增兩個節點：

- **ThunderPhone 觸發器** 會在通話結束時（**通話已完成**）或通話評分執行完成時（**通話已評分**）啟動工作流程。
- **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 金鑰](/yue/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 Sheets 節點，並從 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`](/yue/webhooks/call-complete) 及
[`call.graded`](/yue/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
點數。請參閱[外撥活動](/yue/guides/outbound-campaigns)。

工作流程開始撥打電話前：

- 如 ThunderPhone 要求你的機構確認其外撥電話
  符合 TCPA 及其他通話法規，管理員必須先在控制台記錄
  該確認。
- 撥出號碼必須已啟用外撥功能。你從自有電訊供應商攜入的號碼
  在完成驗證後即可使用。ThunderPhone 號碼初始只支援
  來電，並可獲批准用於外撥：管理員可在電話號碼頁面提出申請。請參閱
  [取得電話號碼](/yue/guides/get-a-phone-number)。
- 你的機構有責任確保已取得撥打每個號碼的同意，
  並遵守適用的通話法規。請參閱
  [外撥通話法規](/yue/guides/outbound-calling-laws)。

## 工作流程範例

- **將 CRM 聯絡人加入活動。** 將 CRM 聯絡人新增至 ThunderPhone
  草稿活動，然後在有人批准名單後啟動活動。
- **將已完成通話寫入客戶記錄。** 在通話完成時，執行取得通話，
  並將逐字稿及錄音連結儲存至相符的客戶記錄。
- **將低分通話送交審核。** 在通話評分時，篩選
  `{{ $json.data.grade.score }}`，並將低分通話連同通話 ID 及評分詳情
  路由至審核佇列。一通電話可被評分多於一次，
  而每次完成評分執行均會觸發觸發器，因此請只保留每個通話 ID 最新的
  `graded_at`。

通話逐字稿、摘要及錄音可能包含個人或健康
資訊。只應將其傳送至你的機構獲准使用該等資料的應用程式；如涉及健康資訊，
應在 BAA 下處理，並只保留所需欄位。

<Note>
  改為將相同通話事件傳送至你自己的伺服器？請參閱
  [Webhook 端點](/yue/webhooks/endpoints)。
  [撥打外撥電話](/yue/guides/place-outbound-calls)涵蓋支援
  撥打外撥電話的 API。
</Note>