For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhook

Webhook コールバック連携:会話プラットフォーム上の訪問者のメッセージと Agent・有人サポートの返信を自社システムへリアルタイムに送信し、カスタマーサポートシステム連携、リアルタイム通知、会話履歴のアーカイブ、社内ワークフローの自動化に活用できます。

設定ガイド:このページでは、会話プラットフォームの設定手順の一部を説明します。テキストサポートの導入から運用開始までの流れは、テキストサポート:ゼロから運用開始までをご覧ください。

用途

Webhook は会話プラットフォームで設定します。開発者が API エンドポイント(URL)を指定すると、その会話プラットフォームでメッセージが作成されるたびに、MaiAgent がその URL へメッセージの内容を送信します。会話の記録、ユーザーへの転送など、自社システムとの連携やさまざまな用途に活用できます。

各会話プラットフォームには複数の Webhook を設定でき、それぞれで送信するメッセージの方向を指定できます。

タイプ
送信のタイミング

Outgoing

Agent または有人サポートの返信が作成されたときです

Incoming

訪問者のメッセージが作成されたときです

Receive

外部のカスタマーサポートプラットフォームから MaiAgent へメッセージを送信します(現在は Genesys Cloud に対応しています)

送信ごとの内容、レスポンス、ステータスコードが記録されるため、確認やトラブルシューティングに利用できます。以下の送信履歴の確認をご覧ください。

送信内容のフィールド、カスタムテンプレートの書き方、API による Webhook 管理については、技術マニュアルの Webhook を担当エンジニアにご案内ください。自社のカスタマーサポートシステムで有人対応に切り替えた会話を引き継ぐ場合は、サードパーティ製カスタマーサポートシステム連携(有人対応への切り替えを含む)をご覧ください。

Webhook の追加

1. Webhook 設定を開く

カスタマーサポートの会話 → 会話プラットフォームに進み、設定するプラットフォームの編集をクリックして、Webhook 設定を開きます。

  • API プラットフォーム:左側メニューの「連携とログイン」グループにあります。

  • LINE、Slack、Microsoft Teams などのメッセージングプラットフォーム:上部のタブバーにあります。

  • Web・内部プラットフォームにはこの設定はありません。Webhook 設定に対応するプラットフォームについては、プラットフォーム対応表をご覧ください。

2. Webhook の各フィールドを入力する

Webhook を追加をクリックし、以下のフィールドを入力して保存します。

フィールド
説明

名前

識別しやすい任意の名前を指定します

タイプ

Outgoing、Incoming、Receive から選びます。各タイプについては上記の説明をご覧ください。Receive を選ぶとフィールドが異なります。以下の Receive タイプのフィールドをご覧ください

有効状態

無効にすると送信を停止しますが、設定は保持されます

Webhook URL

自社システムがデータを受信する URL です

HTTP Method

POST(デフォルト)、PUT、PATCH を使用します

Headers

自社システムが要求する API キーなど、送信のたびに付与するカスタムヘッダーです

Secret Token

任意の署名用シークレットです。設定すると、送信のたびに HMAC 署名とタイムスタンプのヘッダーが付与されます。受信側は同じ Secret Token を使い、リクエストが MaiAgent から送信され、内容が改ざんされていないことを確認できます。以下の Secret Token による送信元の検証をご覧ください。保存後は値が表示されません。編集時に空欄のままにすると既存の値が保持され、新しい値を入力した場合のみ更新されます。Payload 形式が Genesys Cloud の場合、このフィールドは表示されません

Payload 形式

MaiAgent Standard(標準形式)、Genesys Cloud、または Jinja2 で記述するカスタムテンプレートを選びます(利用可能な変数はフォームに表示されます)。Genesys Cloud を選ぶと、Webhook URL と Headers は下部の Genesys Cloud 連携セクションから自動生成され、Secret Token も表示されなくなります

Secret Token による送信元の検証

利用例:「Acme ショッピング」では、公式サイトのサポート窓口に届く訪問者のメッセージを自社の顧客管理システムに同期したいと考えています。エンジニアは、MaiAgent が実際に送信したデータだけを受け付けるようにしたいと考えています。サポート責任者は API プラットフォームの Webhook 設定で Incoming Webhook を追加し、Webhook URL に顧客管理システムの受信 URL、Secret Token にエンジニアと取り決めたシークレットを入力して、確認をクリックして保存します。以後、訪問者の各メッセージの送信に署名が付与され、エンジニアのプログラムは検証に失敗したデータを拒否します。

  1. Webhook フォームの Secret Token フィールドにシークレットを入力し、確認をクリックします。Outgoing、Incoming、Receive の3タイプすべてにこのフィールドがあります。

  2. 同じシークレットを受信側の担当エンジニアに渡します。署名ヘッダーの名前と検証手順については、技術マニュアルの署名とタイムスタンプの検証をご覧ください。

  3. シークレットを変更するには、Webhook 一覧の編集アイコンをクリックし、Secret Token に新しい値を入力して保存します。編集時、このフィールドは常に空欄で、現在のシークレットは表示されません。空欄のまま保存すると既存のシークレットが保持されます。

Webhook 編集ダイアログの Secret Token フィールドとその下の説明
Webhook の編集時、Secret Token フィールドは空欄です。下の説明には、設定すると HMAC 署名とタイムスタンプのヘッダーが付与されることと、空欄のままにすると既存の Secret Token が保持されることが記載されています

管理画面には Secret Token を消去するオプションはなく、新しい値への変更のみ可能です。変更時は受信側も同時に更新してください。更新しないと、新たな送信の署名が一致しなくなります。

Receive タイプのフィールド

Receive は逆方向の連携です。外部のカスタマーサポートプラットフォームから MaiAgent へメッセージを送信するため、自社の URL を入力する代わりに、MaiAgent が外部プラットフォーム用の受信 URL を提供します。

フィールド
説明

Payload のデフォルト形式

外部プラットフォームから送信される形式です。現在は Genesys Cloud(Genesys Cloud Open Messaging API 形式に準拠)に対応しています

Secret Token

署名検証に使用するシークレットです。外部プラットフォームの設定と一致させてください。編集時に空欄のままにすると既存の値が保持され、新しい値を入力した場合のみ更新されます

受信 URL

保存後に表示されます。この URL をコピーし、外部プラットフォームの outbound webhook URL に設定します

Genesys Cloud 連携

Payload 形式に Genesys Cloud を選んだ Outgoing/Incoming Webhook では、フォーム下部に「Genesys Cloud 連携」セクションが表示されます。一度入力すると、この会話プラットフォーム内のすべての Genesys Cloud Webhook に適用されます。

フィールド
説明

リージョン

Genesys Cloud 組織が属するリージョンです

OAuth Client ID/OAuth Client Secret

Genesys Cloud の OAuth Client Credentials です。conversation:message:create 権限が必要です。MaiAgent がこれを使って自動的にトークンを取得するため、Headers を手動で入力する必要はありません

Integration ID

Genesys Cloud Admin → Message → Platforms にある Open Messaging Integration ID です

入力後、接続テストをクリックして認証情報が有効か確認し、保存します。その後、Genesys Cloud から認証情報が無効と報告された場合、Webhook 一覧の上部に警告と影響を受ける件数が表示されます。連携設定を変更をクリックし、Client Secret を再入力して保存してください。連携を削除すると、設定済みの Genesys Cloud Webhook からメッセージを送信できなくなります。連携手順の詳細は、技術マニュアルのサードパーティ製カスタマーサポートシステム連携をご覧ください。

3. 送信を確認する

会話プラットフォームでメッセージを1件送信し、送信履歴でステータスコードが 2xx であることを確認します。

送信履歴の確認

AI 機能 → AI アシスタントに進み、この会話プラットフォームに接続している Agent を選択して、Webhook タブに切り替えます。一覧には、各送信の会話 ID、メッセージ ID、URL、ステータスコード、作成日時が表示されます。操作列の表示アイコンをクリックすると、リクエストのプレビュー、リクエスト JSON、レスポンス内容を確認できます。

Agent の Webhook タブには送信履歴のみが表示され、その Agent に紐づくすべての会話プラットフォームの Webhook 結果が集約されます。Webhook の追加・変更・無効化は、各会話プラットフォームの設定ページにある Webhook 設定で行ってください(Webhook の追加を参照)。同じ Agent が複数のプラットフォームに接続されている場合は、一覧の会話 ID でどのプラットフォームの会話かを確認してください。

活用例

カスタマーサポートシステム連携

Agent がユーザーの質問に回答した後、Webhook で返信内容を企業のカスタマーサポートシステムに同期します。担当者は会話履歴の確認、フォローアップ、有人対応への引き継ぎを行えます。

リアルタイム通知

Agent の返信や特定のイベント(異常など)を Slack、Line Notify、Email などのコミュニケーションツールに送信し、担当者に迅速な対応を促します。

データ分析と記録のアーカイブ

すべての AI 会話データをデータウェアハウス、クラウドデータベース、Google Sheets に自動送信し、利用行動の分析、品質評価、対話履歴のアーカイブに活用できます。

社内ワークフローの自動化

ユーザーが Agent を通じて問題の報告、リソースの申請、異常の報告を行うと、Webhook がそのデータを社内フォームシステムやタスク管理ツール(Jira、Notion など)に自動連携し、その後の追跡に利用できます。

有人対応への切り替え通知との違い

このページの Webhook はメッセージ単位で送信します。会話が有人対応に切り替わったとき、AI に戻されたとき、待ち行列でタイムアウトしたときに外部システムへ通知するには、有人対応への切り替え設定の Webhook 通知(システム連携)を使用してください。両者の設定は独立しています。

最終更新

役に立ちましたか?