將 ThunderPhone 與 n8n 一同使用

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

n8n 是一個工作流程自動化工具。適用於 n8n 的 ThunderPhone 套件 新增兩個節點：

• ThunderPhone 觸發器 會在通話結束時（通話已完成）或通話評分執行完成時（通話已評分）啟動工作流程。
• ThunderPhone 可撥打外撥電話、將聯絡人加入並啟動推廣活動、取得包含逐字稿及錄音的通話資料，以及列出你的智能體及電話號碼。

這是已驗證的社群節點，列於 n8n 上的 ThunderPhone。

安裝節點#

在 n8n 編輯器中，按一下 + 開啟節點面板，然後搜尋 ThunderPhone。執行個體擁有人可能需要先設定已驗證節點，其他使用者才可新增節點。

如你使用自行託管的 n8n，亦可按套件名稱安裝：開啟 設定 > 社群節點，然後安裝 n8n-nodes-thunderphone。安裝前請先檢查社群節點風險及你的執行個體政策。

建立伺服器 API 金鑰#

1. 開啟「金鑰」分頁

   在 ThunderPhone 中，前往 組織 → 金鑰，然後按一下 建立金鑰。

2. 命名

   使用可說明金鑰所在位置的名稱，例如「n8n」。

3. 立即複製

   完整的 sk_live_... 密鑰只會顯示一次。關閉對話方塊前請先複製。

只有管理員或擁有人可以建立金鑰，而 ThunderPhone 會將使用該金鑰發出的請求 視為由該人士發出。觸發器及推廣活動操作要求該人士持續擁有管理員或擁有人角色。 建立伺服器 API 金鑰說明如何輪替及撤銷金鑰。

在 n8n 新增憑證#

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

建立第一個工作流程#

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

1. 新增觸發器

   新增 ThunderPhone Trigger，選擇你的 ThunderPhone API 憑證，並將 Event 設為 Call Completed。

2. 取得通話資料

   新增一個 ThunderPhone 節點。將 Resource 設為 Call、Operation 設為 Get，並將 Call ID 設為運算式 {{ $json.data.call_id }}。 輸出內容包括通話記錄、transcripts 及 recording_url；後者為短期有效連結，沒有錄音的通話會顯示為 null。

3. 新增一列

   新增一個可附加列的 Google Sheets 節點，並從 Get Call 輸出對應你需要的欄位 （見下表）。

4. 啟用工作流程

   儲存並啟用。觸發器會將其正式環境 URL 註冊為你 ThunderPhone 組織中的 Webhook 端點。停用工作流程會刪除此端點。

5. 測試

   在建置器中開啟一個智能體，按一下 Talk，然後結束通話。建置器測試通話會以 web.complete 傳送，這是 Call Completed 所涵蓋的兩種事件之一，因此工作流程會執行並新增一列。

實用欄位：

通話連結會為你組織的成員在 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，例如 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 下處理，並只保留所需欄位。