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

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

- **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 キーを作成する](/ja/guides/api-keys)では、ローテーションと失効について説明しています。

## n8n に認証情報を追加する

1. n8n で **ThunderPhone API** タイプの認証情報を作成します。
2. キーを **API Key** に貼り付けます。
3. 保存して認証情報テストを実行します。このテストでは、`GET /v1/calls?limit=1` を使用して組織内の通話を 1 件読み取ります。

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

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

<Steps>
  <Step title="トリガーを追加">
    **ThunderPhoneトリガー**を追加し、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 を Webhook エンドポイントとして
    ThunderPhone 組織に登録します。ワークフローを無効化すると、そのエンドポイントは
    削除されます。
  </Step>
  <Step title="テスト">
    ビルダーでエージェントを開き、**通話**をクリックして通話を終了します。ビルダーの
    テスト通話は、通話完了の基盤となる2つのイベントの一方である`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 はトリガーの**本番
  URL**に`POST`でイベントを配信するため、n8n インスタンスはインターネットから HTTPS 経由で
  到達可能であり、ワークフローが有効である必要があります。トリガーはすべてのリクエストで
  `X-ThunderPhone-Signature` HMAC を検証し、署名がないものや無効なものには`401`を
  返します。
</Note>

トリガーは完全なイベント（`type`、`event_id`、`data`）を出力します。すべてのフィールドは
[`telephony.complete` / `web.complete`](/ja/webhooks/call-complete)および
[`call.graded`](/ja/webhooks/events)を参照してください。配信は少なくとも1回行われ、
1つのイベントの再試行では`event_id`が同じままです。そのため、繰り返してはならない
ステップの前に確認してください。

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

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

| フィールド | 意味 |
|---|---|
| エージェント名または ID | 保存済みのエージェント。ドロップダウンにはエージェントの一覧が表示されます。 |
| 電話番号名または ID | 発信元番号。ドロップダウンには発信通話が有効な番号のみ表示されます。 |
| 宛先番号 | E.164 形式の宛先番号。例: `+14155552671`。 |
| 変数 | エージェントプロンプト内のプレースホルダーに渡す値の JSON オブジェクト。 |
| 冪等性キー | 上流のレコードまたはイベントから取得する固定 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 クレジットを消費することを確認するチェックボックスが必要です。[発信キャンペーン](/ja/guides/outbound-campaigns)を参照してください。

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

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

## ワークフローの例

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

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

<Note>
  同じ通話イベントを独自のサーバーに送信する場合は、[Webhook エンドポイント](/ja/webhooks/endpoints)を参照してください。
  [発信通話を開始](/ja/guides/place-outbound-calls)では、発信通話を開始の背後にある API を説明しています。
</Note>