---
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-Hant/guides/api-keys)說明輪替和撤銷方式。

## 在 n8n 中新增憑證

1. 在 n8n 中，建立類型為 **ThunderPhone API** 的憑證。
2. 將金鑰貼到 **API 金鑰**。
3. 儲存後執行憑證測試。測試會透過 `GET /v1/calls?limit=1` 讀取你組織中的一筆通話紀錄。

## 建立第一個工作流程

此工作流程會在每次通話結束時，將一列資料新增至 Google 試算表。

<Steps>
  <Step title="新增觸發條件">
    新增 **ThunderPhone Trigger**，選取你的 ThunderPhone API 憑證，並將
    **事件**設為 **通話完成**。
  </Step>
  <Step title="取得通話">
    新增 **ThunderPhone** 節點。將 **資源**設為 **通話**、**操作**
    設為 **取得**，並將 **通話 ID** 設為運算式 `{{ $json.data.call_id }}`。
    輸出內容包含[通話紀錄](/api-reference/calls)、`transcripts` 與
    `recording_url`；後者是短效連結，若通話沒有錄音則為 `null`。
  </Step>
  <Step title="附加一列">
    新增一個會附加一列資料的 Google 試算表節點，並從「取得通話」輸出中
    對應你需要的欄位（請見下表）。
  </Step>
  <Step title="啟用工作流程">
    儲存並啟用。觸發條件會將其正式環境 URL 註冊為你的 ThunderPhone 組織中的
    Webhook 端點。停用工作流程會刪除該端點。
  </Step>
  <Step title="測試">
    在建構工具中開啟一個智慧體，點選 **交談**，然後結束通話。建構工具
    測試通話會以 `web.complete` 傳送，這是「通話完成」背後的兩個事件之一，
    因此工作流程會執行並新增一列資料。
  </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，並在需要新連結時再次執行「取得通話」。
通話逐字稿、摘要與錄音可能包含個人或健康資訊。請僅將其傳送至你的組織獲准
用於處理該資料的應用程式；若涉及健康資訊，請在 BAA 規範下處理，並且只保留
你需要的欄位。

<Note>
  ThunderPhone 會使用 `POST` 將事件傳送至觸發條件的 **正式環境
  URL**，因此你的 n8n 執行個體必須可透過網際網路以 HTTPS 存取，
  且工作流程必須處於啟用狀態。觸發條件會驗證每個請求中的
  `X-ThunderPhone-Signature` HMAC，並對任何未簽署或無效的請求回應 `401`。
</Note>

觸發條件會輸出完整事件：`type`、`event_id` 和 `data`。請參閱
[`telephony.complete` / `web.complete`](/zh-Hant/webhooks/call-complete) 與
[`call.graded`](/zh-Hant/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-Hant/guides/outbound-campaigns)。

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

- 如果 ThunderPhone 要求你的組織確認其撥出通話遵循 TCPA 與其他通話相關法律，管理員必須先在控制台中記錄該確認。
- 發話號碼必須已啟用撥出通話。你從自有電信業者帶入的號碼，驗證後即可符合資格。ThunderPhone 號碼一開始僅限撥入，並可獲核准用於撥出：管理員可從「電話號碼」頁面提出申請。請參閱
  [取得電話號碼](/zh-Hant/guides/get-a-phone-number)。
- 你的組織有責任取得撥打每個號碼所需的同意，並遵守適用的通話相關法律。請參閱
  [撥出通話法律](/zh-Hant/guides/outbound-calling-laws)。

## 範例工作流程

- **將 CRM 聯絡人加入行銷活動。** 將 CRM 聯絡人新增至 ThunderPhone 草稿行銷活動，然後在有人核准清單後啟動行銷活動。
- **將已完成通話寫入客戶紀錄。** 在通話完成時執行取得通話，並將文字稿與錄音連結儲存至相符的客戶紀錄。
- **低分通話送交審查。** 在通話評分完成時，依據
  `{{ $json.data.grade.score }}` 篩選，並將低分通話連同通話 ID 與評分詳細資料導向審查佇列。一次通話可能會被評分多次，而每次完成評分執行時都會觸發此觸發程序，因此每個通話 ID 僅保留最新的
  `graded_at`。

通話文字稿、摘要與錄音可能包含個人或健康資訊。僅將這些資料傳送至你的組織獲准用於處理該資料的應用程式；若涉及健康資訊，應在 BAA 下處理，並且只保留你需要的欄位。

<Note>
  改為將相同的通話事件傳送至你自己的伺服器？請參閱
  [Webhook 端點](/zh-Hant/webhooks/endpoints)。
  [發起撥出通話](/zh-Hant/guides/place-outbound-calls) 說明發起撥出通話背後的 API。
</Note>