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 憑證，並將 事件設為 通話完成。
- 取得通話
新增 ThunderPhone 節點。將 資源設為 通話、操作 設為 取得，並將 通話 ID 設為運算式
{{ $json.data.call_id }}。 輸出內容包含通話紀錄、transcripts與recording_url；後者是短效連結，若通話沒有錄音則為null。 - 附加一列
新增一個會附加一列資料的 Google 試算表節點，並從「取得通話」輸出中 對應你需要的欄位（請見下表）。
- 啟用工作流程
儲存並啟用。觸發條件會將其正式環境 URL 註冊為你的 ThunderPhone 組織中的 Webhook 端點。停用工作流程會刪除該端點。
- 測試
在建構工具中開啟一個智慧體，點選 交談，然後結束通話。建構工具 測試通話會以
web.complete傳送，這是「通話完成」背後的兩個事件之一， 因此工作流程會執行並新增一列資料。
實用欄位：
| 欄位 | 運算式 |
|---|---|
| 通話 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 規範下處理，並且只保留
你需要的欄位。
觸發條件會輸出完整事件：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 下處理，並且只保留你需要的欄位。