ThunderPhone を n8n で使用する

n8n 用の ThunderPhone ノードをインストールし、サーバー API キーを接続して、通話が終了するたびに実行されるワークフローを構築します。

n8n はワークフロー自動化ツールです。n8n 向けの ThunderPhone パッケージには、次の 2 つのノードが追加されます。

• ThunderPhone Trigger は、通話が終了したとき（通話完了）、または通話評価の実行が完了したとき（通話の評価完了）にワークフローを開始します。
• 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 Key に貼り付けます。
3. 保存して認証情報テストを実行します。このテストでは、GET /v1/calls?limit=1 を使用して組織内の通話を 1 件読み取ります。

最初のワークフローを作成#

このワークフローでは、通話が終了するたびに Google スプレッドシートへ行を追加します。

1. トリガーを追加

   ThunderPhoneトリガーを追加し、ThunderPhone API 認証情報を選択して、 イベントを通話完了に設定します。

2. 通話を取得

   ThunderPhoneノードを追加します。リソースを通話、操作 を取得に設定し、通話 IDには式{{ $json.data.call_id }}を指定します。 出力には通話レコードに加え、transcriptsと recording_urlが含まれます。後者は短期間のみ有効なリンクで、通話に 録音がない場合はnullです。

3. 行を追加

   行を追加する Google スプレッドシートノードを追加し、取得した通話の出力から 必要な列をマッピングします（以下の表を参照）。

4. ワークフローを有効化

   保存して有効化します。トリガーは本番 URL を Webhook エンドポイントとして ThunderPhone 組織に登録します。ワークフローを無効化すると、そのエンドポイントは 削除されます。

5. テスト

   ビルダーでエージェントを開き、通話をクリックして通話を終了します。ビルダーの テスト通話は、通話完了の基盤となる2つのイベントの一方であるweb.completeとして 配信されるため、ワークフローが実行されて行が追加されます。

便利な列:

通話リンクを開くと、組織のメンバーは 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を参照してください。配信は少なくとも1回行われ、 1つのイベントの再試行ではevent_idが同じままです。そのため、繰り返してはならない ステップの前に確認してください。

発信通話を安全に開始する#

発信通話を開始（リソース 発信通話、操作 開始）では、次を指定します。

冪等性キーには、CRM レコード ID やトリガーの event_id など、実行を発生させた要因の ID をマッピングします。ノードは n8n:<node ID>:<your value> を送信するため、次のようになります。

• 自動再試行または 実行を再試行では同じキーが送信され、ThunderPhone は再度発信する代わりに idempotent_replay: true を含む元の通話を返します。
• 同じレコードを入力として受け取る 2 つの ThunderPhone ノードは、それぞれ異なるキーを送信します。
• 空の値の場合、リクエスト送信前に失敗します。

タイムスタンプ、ランダム値、n8n の実行 ID やワークフロー ID は使用しないでください。再試行時に新しい値を使用すると、2 回目の実際の通話が開始されます。キー全体は最大 128 文字です。異なるエージェント、番号、または変数でキーを再利用すると、競合エラーになります。

キャンペーン。 連絡先を追加（リソース キャンペーン）では、下書きキャンペーンに連絡先を追加します。キャンペーン ID と連絡先の JSON 配列を指定します。各連絡先には phone_number が必要で、その他のキーは通話変数になります。すべての連絡先が拒否された場合はノードが失敗し、一部のみ拒否された場合は partial_success: true が設定されます。開始には、キャンペーンが実際の通話を開始し、ThunderPhone クレジットを消費することを確認するチェックボックスが必要です。発信キャンペーンを参照してください。

ワークフローで通話を開始する前に、次を確認してください。

• ThunderPhone から、組織の発信通話が TCPA およびその他の通話関連法規に準拠していることの確認を求められた場合は、管理者が先にダッシュボードでその確認を記録する必要があります。
• 発信元番号で発信通話が有効になっている必要があります。自社の通信事業者から持ち込んだ番号は、確認後に利用できます。ThunderPhone の番号は当初は着信専用であり、発信用に承認できます。管理者が電話番号ページから申請してください。電話番号を取得を参照してください。
• 組織には、各番号へ発信するための同意を取得し、適用される通話関連法規に従う責任があります。発信通話に関する法規を参照してください。

ワークフローの例#

• CRM の連絡先をキャンペーンに追加。 CRM の連絡先を下書きの ThunderPhone キャンペーンに追加し、担当者がリストを承認したらキャンペーンを開始します。
• 完了した通話を顧客レコードに保存。 通話完了時に、通話を取得を実行し、文字起こしと録音リンクを該当する顧客レコードに保存します。
• 低評価をレビューへ送信。 通話評価時に、{{ $json.data.grade.score }} でフィルタリングし、低スコアの通話を通話 ID と評価詳細とともにレビューキューへルーティングします。通話は複数回評価される場合があり、完了した各評価実行でトリガーが発火するため、各通話 ID では最新の graded_at のみを保持してください。

通話の文字起こし、要約、録音には、個人情報または健康情報が含まれる場合があります。組織がそのデータに使用を許可されているアプリにのみ送信し、健康情報が含まれる場合は BAA に基づいて取り扱い、必要なフィールドのみを保持してください。