Webhook

対話プラットフォームの Webhook：訪問者のメッセージと AI／有人対応の返信をリアルタイムでシステムに送信します。MaiAgent 標準形式、Genesys Cloud、カスタム Jinja2 テンプレートに対応しています

Webhook は**対話プラットフォーム（Inbox）**で設定します。そのプラットフォームの会話で新しいメッセージが作成されるたびに、MaiAgent が指定されたエンドポイントに HTTP リクエストでメッセージを送信します。1 つの対話プラットフォームに複数の Webhook を設定し、それぞれ送信するメッセージの方向と形式を指定できます。

設定場所：カスタマーサポートの会話 → 対話プラットフォーム → プラットフォームを編集 → Webhook 設定 → Webhook を追加。API プラットフォームの Webhook 設定 は左側の「連携とログイン」グループにあります。LINE などのメッセージングプラットフォームでは上部のタブバーにあります。Web および内部プラットフォームにはこのタブはありません。管理画面の操作については、ユーザーマニュアルの Webhook を参照してください。

会話とメッセージの作成 API でメッセージを送信した際のレスポンスは、メッセージが作成されたことのみを示します。Agent の返信は非同期で生成され、Outgoing Webhook で送信されます。これが API 連携で返信を取得する標準的な方法です。

動作の仕組み

有人オペレーターが管理画面で返信した場合も、その返信は Outgoing メッセージとして Outgoing Webhook に送信されます。payload の sender.type で AI と有人オペレーターを区別できます。

Webhook の種類

種類	発火タイミング	主な用途
Outgoing	Agent または有人オペレーターの返信が作成されたとき	AI の返信を取得し、自社のフロントエンドやメッセージングアプリに転送します
Incoming	訪問者のメッセージが作成されたとき（API、Web Chat、LINE などすべてのチャネルを含みます）	会話履歴をサポートシステムやデータウェアハウスに同期し、監査に利用します
Receive	外部プラットフォームから MaiAgent が呼び出されたとき	外部サポートプラットフォームから返されるメッセージを受信します（現在は Genesys Cloud Open Messaging に対応しています）

このページでは Outgoing と Incoming を説明します。

設定フィールド

フィールド	説明
名前	識別用の任意の名前です
種類	Outgoing／Incoming／Receive
Webhook URL	送信されたメッセージを受信する URL です
HTTP Method	POST（デフォルト）／PUT／PATCH
Headers	各リクエストに付加するカスタムヘッダーです（お客様のシステムの API キーなど）
Payload 形式	MaiAgent 標準形式／Genesys Cloud／カスタムテンプレート（Jinja2）
有効状態	無効にすると送信を停止しますが、設定は保持されます
secretToken（API フィールド）	設定すると各リクエストに X-Webhook-Secret: <token> ヘッダーが付加されます。管理画面のフォームで Secret Token が表示されるのは Receive のみです。Outgoing／Incoming で認証値を送信するには、API で設定するか、Headers にカスタムヘッダーを追加してください

送信時に署名は付加されません。X-Webhook-Secret とカスタムヘッダーは設定した値のまま送信される固定文字列であり、リクエストの内容から算出する HMAC ではありません。HTTPS エンドポイントのみを使用し、受信側でこの値を照合してください。

MaiAgent 標準形式

Content-Type: application/json で、内容は次のとおりです（Outgoing と Incoming は同じ構造で、type によって方向を区別します）：

{
  "id": "2491074a-6d23-4289-af45-caa12531420e",
  "type": "outgoing",
  "content": "こんにちは。どのようなご用件でしょうか？",
  "created_at": "2026-09-09T10:15:30.123456+00:00",
  "conversation": {
    "id": "8e44604a-8278-4c96-96b5-3e5a0548d738",
    "title": "返品手続きについての問い合わせ",
    "type": "individual",
    "status": "open",
    "progress_status": "ai_processing",
    "auto_reply_enabled": true,
    "assignee": null
  },
  "inbox": {
    "id": "1f9c1c1e-4d1a-4b1e-9d0e-7b2f4a5c6d7e",
    "name": "公式サイトのサポート",
    "channel_type": "web"
  },
  "contact": {
    "id": "c0ffee00-1111-2222-3333-444455556666",
    "name": "山田太郎",
    "email": null,
    "phone_number": null
  },
  "sender": {
    "id": "5c1d3e2a-0000-4b1e-9d0e-7b2f4a5c6d7e",
    "name": "AI サポート",
    "type": "chatbot"
  },
  "attachments": [
    {
      "id": "a1b2c3d4-0000-4b1e-9d0e-7b2f4a5c6d7e",
      "type": "image",
      "filename": "photo.jpg",
      "source_url": "https://example.com/photo.jpg"
    }
  ],
  "metadata": {}
}

フィールドの説明

フィールド	型	説明
id	string	メッセージ ID（UUID）です
type	string	incoming（訪問者のメッセージ）／outgoing（AI または有人対応の返信）
content	string	メッセージのテキストです
created_at	string	ISO 8601 形式の時刻です
conversation.id	string	会話 ID です
conversation.title	string	会話のタイトルです
conversation.type	string	individual／group
conversation.status	string	open／queued（有人対応待ち）／resolved
conversation.progress_status	string	現在の対応状態です：ai_processing／waiting_for_human／human_serving／resolved／open
conversation.auto_reply_enabled	boolean	false は AI の自動返信が停止していることを示します（有人対応への引き継ぎ中）
conversation.assignee	object | null	引き継ぐサポートメンバー { id, name } です。未割り当ての場合は null です
inbox.id / inbox.name	string	対話プラットフォームの ID と名前です
inbox.channel_type	string	web／line／messenger／instagram／telegram／teams／email／whatsapp／slack／team_plus／line_works／viber
contact	object | null	訪問者（連絡先）{ id, name, email, phone_number } です
sender.type	string	chatbot（Agent）／user（有人オペレーター）／contact（訪問者）
attachments[]	array	添付ファイル { id, type, filename, source_url } です。type は image／video／audio／sticker／other です
metadata	object	メッセージの追加データです

attachments[].source_url は添付ファイルの取得元 URL（外部プラットフォームから渡された元のリンク）です。MaiAgent が保存したファイル（API でアップロードしたファイルや AI が生成したファイルなど）では、このフィールドが空の場合があります。ダウンロード可能な URL が必要な場合は、カスタムテンプレートで attachment.file.url を取得するか（下のサンプルを参照してください）、メッセージ ID を指定してメッセージ API を呼び出し、添付ファイルを取得してください。

カスタムテンプレート（Jinja2）

システムが特定の JSON 構造を要求する場合は、カスタムテンプレートを選択し、Jinja2 構文で payload を記述します。テンプレートのレンダリング結果は有効な JSON である必要があります。保存時にテストデータで一度検証されます。

利用可能な変数

変数	内容
message	id、type、content、created_at（datetime）、metadata
conversation	id、title、type、status、progress_status、auto_reply_enabled、assignee（None の場合があります。値がある場合は assignee.id、assignee.user.name）
inbox	id、name、channel_type
contact	id、name、email、phone_number、source_id（ユーザー情報同期 API で渡した sourceId）です。None の場合があります
sender	id、name です。sender_type は chatbot／user／contact です
attachments	添付ファイルのリストです。各項目は id、type、filename、source_url、file（file.url はダウンロード可能な URL）を持ちます
now	レンダリング時の時刻（datetime）です

文字列は必ず | tojson フィルターを通して出力し、引用符と改行を正しくエスケープしてください。

サンプル：自社システムのユーザー ID とダウンロード可能な添付ファイル URL を返します

{
  "external_user_id": {{ (contact.source_id if contact else "") | tojson }},
  "conversation_id": "{{ conversation.id }}",
  "direction": "{{ message.type }}",
  "from_human_agent": {{ (sender_type == "user") | tojson }},
  "text": {{ message.content | tojson }},
  "attachments": [{% for a in attachments %}{
    "type": "{{ a.type }}",
    "url": {{ (a.file.url if a.file else a.source_url) | tojson }}
  }{% if not loop.last %},{% endif %}{% endfor %}],
  "sent_at": "{{ message.created_at.isoformat() }}"
}

送信動作

• メッセージごとに、有効な各 Webhook へ 1 回送信します。リクエストのタイムアウトは 30 秒です。

• 2xx レスポンスを成功とみなします。2xx 以外のレスポンスやタイムアウトは失敗として記録され、自動再試行は行われません。確実な配信が必要な場合は、エンドポイント内でデータを永続化してから 2xx を返し、メッセージの id で重複を排除してください。

• エンドポイント URL には SSRF 対策が適用されます。プライベートネットワーク範囲や内部アドレスへの送信は拒否されます。

• 各送信のリクエスト内容、レスポンス、ステータスコードは、Agent ページの Webhook タブで確認でき、トラブルシューティングに利用できます。

API による Webhook の管理

管理画面に加えて、API でも Webhook を作成・管理できます（フィールドは管理画面の設定に対応します）。認証方法はクイックスタートを参照してください。

# 一覧取得 / 作成
GET  https://api.maiagent.ai/api/v1/inboxes/{inboxId}/webhooks/
POST https://api.maiagent.ai/api/v1/inboxes/{inboxId}/webhooks/

# 更新 / 削除
PATCH  https://api.maiagent.ai/api/v1/inboxes/{inboxId}/webhooks/{webhookId}/
DELETE https://api.maiagent.ai/api/v1/inboxes/{inboxId}/webhooks/{webhookId}/

{
  "name": "返信をサポートシステムに同期します",
  "direction": "outgoing",
  "isEnabled": true,
  "url": "https://your-system.example.com/maiagent/reply",
  "method": "POST",
  "headers": { "X-Api-Key": "your-key" },
  "templatePreset": "maiagent_standard",
  "customTemplate": null,
  "secretToken": "shared-secret"
}

inboxId は会話の作成のレスポンスの inbox.id から取得するか、管理画面の対話プラットフォーム設定ページで確認できます。

「有人対応への引き継ぎ Webhook」との違い

このページの Webhook はメッセージ単位で送信します。会話がいつ有人対応に引き継がれ、いつ AI に戻るかをシステムで把握する必要がある場合（自社のサポートシステムで対応を引き継ぐ場合など）は、会話のライフサイクル単位で動作する別の引き継ぎ Webhook を使用してください。外部サポートシステム連携（有人対応への引き継ぎを含む）を参照してください。