> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/ja/preparation/message-webhook.md).

# メッセージ Webhook

チャットプラットフォームで顧客メッセージを受信するたび、または返信を送信するたびに、MaiAgent はそのメッセージを指定した URL にプッシュできます。このページでは、Incoming と Outgoing の違い、管理画面と API での設定方法、プッシュされる内容、送信元の検証（HMAC 署名）、一時的な失敗時の自動再送について説明します

チャットプラットフォーム（Inbox）にメッセージ Webhook を設定すると、すべてのメッセージが MaiAgent からお客様のシステムへ能動的にプッシュされるため、ポーリングは不要です。主な用途は、自社システムでの「新着メッセージあり」の表示、顧客からの問い合わせの CRM への同期、AI の返信のデータウェアハウスへの記録です。

1 つのチャットプラットフォームには複数のメッセージ Webhook を設定でき、それぞれ個別にタイプ、URL、フォーマットを選択して、互いに独立してプッシュされます。

{% hint style="info" %}
**有人対応への引き継ぎ**時にだけ通知を受け取りたい場合は、[有人対応引き継ぎ Webhook イベント](https://docs.maiagent.ai/api/ja/preparation/handoff-webhook.md)を使用してください。こちらは有人対応への引き継ぎフローの状態が変わったときにだけプッシュされ、メッセージごとにはプッシュされません。両者は独立した設定のため、同時に有効にして同じ受信側で処理できます。
{% endhint %}

{% hint style="info" %}
会話返信（completions）API で新規作成した会話では、返信はその Agent の API チャットプラットフォームに設定された `Outgoing` Webhook にプッシュされます。`200`、`202`、ストリーミングのいずれにも適用されます。他のプラットフォームの会話を継続する場合は、そのプラットフォームの設定に従ってプッシュされます。プッシュされた返信を自分の質問と対応付ける方法、`202` のポーリングと併用する場合の重複排除の方法、プッシュされないケース、完全なサンプルについては、技術マニュアルの [Webhook で返信を受け取る](https://docs.maiagent.ai/tech/api-integration/dui-hua-yu-xun-xi-hui-fu-chuan-liu-tong-bu#webhook-reply)を参照してください。
{% endhint %}

## タイプ：Incoming と Outgoing <a href="#directions" id="directions"></a>

| タイプ        | プッシュされるタイミング                                         | payload の `type` |
| ---------- | ---------------------------------------------------- | ---------------- |
| `Incoming` | チャットプラットフォームが顧客（コンタクト）からメッセージを受信するたび                 | `incoming`       |
| `Outgoing` | 顧客のいるチャットプラットフォームへ返信を送信するたび（AI の自動返信と有人オペレーターの返信を含む） | `outgoing`       |

* 管理画面の `Incoming` オプションの説明文は「外部リクエストを受信」ですが、実際の動作は**顧客メッセージを設定した URL にプッシュする**ものです。
* 同じメニューにある `Receive` は用途が逆で、外部プラットフォームからメッセージを MaiAgent に送り込むためのものであり、このページで扱うプッシュの対象外です。`Receive` 経由で送り込まれたメッセージは、同じチャットプラットフォームの `Incoming`／`Outgoing` のプッシュを発生させません。これにより、メッセージが 2 つのシステム間を行き来して循環するのを防ぎます。
* 顧客メッセージと返信の両方を知りたい場合は、`Incoming` と `Outgoing` をそれぞれ 1 つずつ設定してください。同じ URL を指定しても構わず、payload の `type` で区別できます。

## 設定方法 <a href="#setup" id="setup"></a>

### 管理画面での設定 <a href="#setup-admin" id="setup-admin"></a>

1. 管理画面 → <mark style="color:blue;">カスタマーサポート</mark> → <mark style="color:blue;">チャットプラットフォーム</mark> → チャットプラットフォームを選択 → <mark style="color:blue;">Webhook 設定</mark> → <mark style="color:blue;">Webhook を追加</mark>
2. <mark style="color:blue;">名前</mark>を入力し、<mark style="color:blue;">タイプ</mark>で <mark style="color:blue;">Incoming</mark> または <mark style="color:blue;">Outgoing</mark> を選択して、<mark style="color:blue;">Webhook URL</mark> を入力し、<mark style="color:blue;">HTTP メソッド</mark>を選択します（デフォルトは `POST`）。
3. （推奨）<mark style="color:blue;">ヘッダー</mark>に検証用のヘッダーを 1 組追加します。例：`Authorization: Bearer <ご自身で生成したランダムな文字列>`。受信側はこれを使ってリクエストが MaiAgent から届いたことを確認します（[プッシュ元の検証](#verify-source)を参照）。
4. <mark style="color:blue;">Payload フォーマット</mark>で <mark style="color:blue;">MaiAgent Standard</mark> を選択します（[プッシュ内容](#payload)を参照）。フィールドをカスタマイズしたい場合は<mark style="color:blue;">カスタムテンプレート</mark>を選択します。
5. <mark style="color:blue;">有効状態</mark>がオンになっていることを確認して保存します。有効状態をオフにするとプッシュは一時停止し、設定は保持されます。

WhatsApp のチャットプラットフォームの設定ページには、現在 <mark style="color:blue;">Webhook 設定</mark>タブがありません。代わりに下記の API で設定してください。

### API での設定 <a href="#setup-api" id="setup-api"></a>

メッセージ Webhook はチャットプラットフォーム（Inbox）の配下に属します。

| 操作    | メソッドとパス                                                           |
| ----- | ----------------------------------------------------------------- |
| 一覧取得  | `GET /api/v1/inboxes/{inbox_id}/webhooks/`                        |
| 追加    | `POST /api/v1/inboxes/{inbox_id}/webhooks/`                       |
| 1 件取得 | `GET /api/v1/inboxes/{inbox_id}/webhooks/{id}/`                   |
| 更新    | `PATCH /api/v1/inboxes/{inbox_id}/webhooks/{id}/`（変更したいフィールドのみ送信） |
| 削除    | `DELETE /api/v1/inboxes/{inbox_id}/webhooks/{id}/`                |

API キーの所有者は、そのチャットプラットフォームを管理できる権限が必要です。詳細は [API 認証 → API キーの権限範囲](https://docs.maiagent.ai/api/ja/preparation/authentication.md#api-key-permissions)を参照してください。

| フィールド            | 必須              | 説明                                                                                                            |
| ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------- |
| `name`           | はい              | 識別しやすくするための名前                                                                                                 |
| `direction`      | はい              | `incoming` または `outgoing`                                                                                     |
| `url`            | はい              | プッシュを受け取る URL。インターネットから接続できる必要があります（`https://` を推奨）。内部ネットワークやローカルアドレスを指す URL への送信は拒否されます                      |
| `method`         | いいえ             | `POST`（デフォルト）、`PUT`、`PATCH`                                                                                   |
| `headers`        | いいえ             | プッシュのたびに付与されるカスタムヘッダー。JSON オブジェクトで指定します。例：`{"Authorization": "Bearer ..."}`                                   |
| `templatePreset` | いいえ             | `maiagent_standard`（デフォルト）、`custom`、または Genesys Cloud 連携用の `genesys_cloud`                                    |
| `customTemplate` | `custom` の場合は必須 | Jinja2 テンプレート。レンダリング結果は JSON である必要があります。保存時に一度試行レンダリングされ、形式が誤っていると 400 を返します                                  |
| `secretToken`    | いいえ             | 署名用のシークレット。設定すると、プッシュのたびに HMAC-SHA256 署名とタイムスタンプのヘッダーが付きます（[プッシュ元の検証](#verify-source)を参照）。書き込み専用で、取得時には返されません |
| `isEnabled`      | いいえ             | 有効にするかどうか。デフォルトは `true`                                                                                       |

```bash
curl -X POST "https://api.maiagent.ai/api/v1/inboxes/YOUR_INBOX_ID/webhooks/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "新着メッセージ通知",
    "direction": "incoming",
    "url": "https://example.com/webhooks/maiagent-message",
    "secretToken": "YOUR_RANDOM_SECRET"
  }'
```

成功すると `201` と、その設定（`secretToken` は含まれません）が返ります。返信も受け取りたい場合は、`"direction": "outgoing"` でもう 1 件追加してください。

## プッシュ内容 <a href="#payload" id="payload"></a>

メッセージは 1 件ごとに 1 つの HTTP リクエストとしてプッシュされます。

* ヘッダー：`Content-Type: application/json`、設定したカスタムヘッダー、`X-MaiAgent-Delivery-Attempt`（何回目の試行か。初回は `1`）、および `secretToken` を設定している場合は `X-MaiAgent-Timestamp` と `X-MaiAgent-Signature-256`。カスタムヘッダーがこの 3 つのヘッダーと同名（大文字小文字を区別しない）の場合、送信前に削除されます。
* 本文：<mark style="color:blue;">Payload フォーマット</mark>に従って生成された JSON。

### MaiAgent Standard フォーマット <a href="#standard-format" id="standard-format"></a>

フィールドは常に snake\_case です（API レスポンスの camelCase とは異なります）。以下は `Outgoing`（AI の返信）のプッシュ内容です。

```json
{
  "id": "a0c49ae2-013c-4310-b00f-b4554bc9cd83",
  "type": "outgoing",
  "content": "こんにちは。ご注文に関するお問い合わせを受け付けました。注文番号をお知らせください。",
  "created_at": "2026-10-03T04:59:01.512340+00:00",
  "conversation": {
    "id": "e6b27044-4990-4129-ad8e-ac7649984e7d",
    "title": "注文住所の変更",
    "type": "individual",
    "status": "open",
    "progress_status": "ai_processing",
    "auto_reply_enabled": true,
    "assignee": null
  },
  "inbox": { "id": "6571672b-2fae-4200-a4d0-cf12e86216c3", "name": "公式サイトサポート", "channel_type": "web" },
  "contact": { "id": "350691e0-66a5-48ea-855c-d8bb90a7e24a", "name": "王小明", "email": null, "phone_number": null },
  "sender": { "id": "8a214fc3-75ad-43ba-93f6-567e9df97b76", "name": "サポートアシスタント", "type": "chatbot" },
  "attachments": [],
  "metadata": {}
}
```

| フィールド          | 説明                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | メッセージ ID。重複排除に使用できるほか、[メッセージ API](https://docs.maiagent.ai/api/ja/api-reference/dui-hua-he-xun-xi.md)での照会にも使えます                             |
| `type`         | `incoming`（顧客メッセージ）または `outgoing`（返信）。方向の判定にはこのフィールドを使用してください                                                                               |
| `content`      | メッセージのテキスト                                                                                                                                  |
| `created_at`   | メッセージの作成日時（ISO 8601、UTC）                                                                                                                    |
| `conversation` | 所属する会話。`progress_status` が `human_serving` の場合は、現在有人オペレーターが対応中であることを示します。`assignee` は割り当てられたオペレーター `{ "id", "name" }` で、未割り当ての場合は `null` です |
| `inbox`        | チャットプラットフォーム `{ "id", "name", "channel_type" }`。`channel_type` は `web`、`line`、`messenger` など                                                |
| `contact`      | 顧客（コンタクト）。`email` と `phone_number` はデータがない場合 `null` になります                                                                                   |
| `sender`       | 発信者。`type` は `contact`（顧客）、`chatbot`（Agent）、`user`（組織メンバー。有人オペレーターなど。API キーで顧客の代わりに送信したメッセージも `user` になります）のいずれか                            |
| `attachments`  | 添付ファイルの配列。各要素は `id`、`type`（`image`／`video`／`audio`／`sticker`／`other`）、`filename`、`source_url` を含みます                                         |
| `metadata`     | メッセージの付加情報。内容はチャットプラットフォームによって異なります                                                                                                         |

### カスタムテンプレート <a href="#custom-template" id="custom-template"></a>

<mark style="color:blue;">カスタムテンプレート</mark>（API では `templatePreset: "custom"`）は、Jinja2 構文で必要な JSON を組み立てます。使用できる変数は、`message`（`id`、`type`、`content`、`created_at`、`metadata`）、`conversation`、`inbox`、`contact`、`sender`、`sender_type`（`contact`／`chatbot`／`user`）、`attachments`、`now` です。引用符や改行で JSON が壊れないよう、文字列は `tojson` フィルターで出力してください。

```
{
  "text": {{ message.content | tojson }},
  "direction": "{{ message.type }}",
  "conversation_id": "{{ conversation.id }}",
  "customer": {{ (contact.name if contact else none) | tojson }}
}
```

プッシュ時にテンプレートのレンダリングに失敗した場合、そのメッセージは送信されません。

## プッシュ元の検証 <a href="#verify-source" id="verify-source"></a>

`secretToken`（API のフィールド、または管理画面の Webhook フォームの <mark style="color:blue;">Secret Token</mark>。Payload フォーマットが Genesys Cloud の場合、管理画面にはこのフィールドは表示されません）を設定すると、プッシュのたびに以下のヘッダーが付きます。

| ヘッダー                       | 内容                                                                              |
| -------------------------- | ------------------------------------------------------------------------------- |
| `X-MaiAgent-Timestamp`     | 送信時点の Unix 時間（秒）                                                                |
| `X-MaiAgent-Signature-256` | `sha256=` に、`HMAC-SHA256(secretToken, "{timestamp}." + 生の body)` の 16 進数値を続けたもの |

受信側の検証手順：

1. 受信した**生の body のバイト列**で署名を計算します。いったん JSON としてパースして再シリアライズしないでください（バイト列が変わり、署名が一致しなくなります）。
2. 定数時間比較（例：Python の `hmac.compare_digest`）で `X-MaiAgent-Signature-256` と照合します。
3. `X-MaiAgent-Timestamp` が受信側の現在時刻と許容範囲（例：5 分）を超えて離れている場合は、リプレイ攻撃を避けるためにリクエストを拒否します。各試行（再送を含む）では、送信時点でタイムスタンプと署名が再計算されます。

詳細は、技術マニュアルの[署名とタイムスタンプの検証](https://docs.maiagent.ai/tech/serve/webhook#webhook-signature)を参照してください。

* 署名を使用しない場合は、`headers` に独自の検証用ヘッダー（例：`Authorization: Bearer <ランダムな文字列>`）を設定することもできます。`headers` の値は Webhook 設定の照会時にそのまま返されるため、そのチャットプラットフォームの設定を閲覧できる組織メンバーなら誰でも確認できます。`secretToken` は書き込み専用で、返されません。
* `secretToken` を設定した場合、既存の受信側との互換性のために、従来の `X-Webhook-Secret` ヘッダー（値は `secretToken` の平文）も引き続き送信されます。新規に連携する場合は、署名の検証を使用してください。
* 検証用のシークレットには十分な長さのランダムな値を使用し、HTTPS で受信してください。

## レスポンスとリトライ <a href="#response-and-retry" id="response-and-retry"></a>

* メッセージが書き込まれた後にバックグラウンドでプッシュされ、通常は数秒以内に届きます。メッセージごとに個別に送信されるため、**到着順序は保証されません**。`created_at` で並べ替え、`id` で重複を排除してください。
* 受信側は **30 秒**以内に 2xx を返してください。タイムアウト、接続失敗、2xx 以外のレスポンスはすべて失敗として扱われます。
* **一時的な失敗は自動的に再送されます**：タイムアウト、接続失敗、`5xx`、`429` の場合、約 1 分後、5 分後、15 分後に 1 回ずつ再送され、再送は最大 3 回です（初回を含めて合計 4 回の試行）。それ以外の `4xx`、セキュリティ保護により宛先がブロックされた場合、カスタムテンプレートのレンダリング失敗は再送されません。再送される body は初回とまったく同じで、`X-MaiAgent-Delivery-Attempt` は順に `2`、`3`、`4` になります。間隔は固定で、レスポンスの `Retry-After` は参照されません。再送前に Webhook が無効化または削除された場合、またはメッセージが削除された場合は、それ以上再送されません。詳細は、技術マニュアルの[自動再送](https://docs.maiagent.ai/tech/serve/webhook#retry)を参照してください。
* 再送があるため、プッシュは「少なくとも 1 回は届く」方式です。受信側が実際には処理済みでも、レスポンスがタイムアウトしたり `5xx` を返したりすると、同じメッセージをもう一度受け取ることになるため、メッセージの `id` で重複を排除してください。内容を保存してから 2xx を返し、時間のかかる処理はバックグラウンドに回すことをおすすめします。今後も処理できないと確定している場合にのみ `4xx` を返し、一時的に処理できない場合（例：下流サービスの障害）は `5xx` または `429` を返してください。
* 3 回の再送がすべて失敗すると、それ以上の再送は行われず、メッセージ Webhook は**配信を保証しません**。[新着メッセージの検知](https://docs.maiagent.ai/api/ja/preparation/detect-new-messages.md#polling)のポーリング方式を使えば、低頻度の確認で**顧客メッセージ**（Incoming）を補完できます。ただし、AI やオペレーターの返信（Outgoing）は顧客メッセージの後に生成されることが多く、ポーリングのサンプルでは再度取得できるとは限らないため、プッシュに失敗した返信の補完には頼れません。プッシュに失敗したメッセージを見つけるには、下記の送信履歴を確認してください。`statusCode` が 2xx ではない、または空（タイムアウト、接続失敗）のものが失敗したプッシュで、`requestBody` が当時プッシュされた内容です（MaiAgent Standard フォーマットにはメッセージの `id` と `conversation.id` が含まれます）。そのうえで、その会話のメッセージ一覧の最初のページを読み込んで補完します。
* 各試行（再送を含む）の URL、内容、レスポンスのステータスコードは、それぞれ 1 件ずつ送信履歴として残り、`GET /api/v1/chatbots/{chatbot_id}/webhook-records/` で照会できます（その Agent の編集権限が必要です。`chatbot_id` はチャットプラットフォームに紐づく Agent です）。なお、この API のレスポンスも camelCase に変換されますが、実際にプッシュされる内容は snake\_case です。
* プッシュの失敗は、メッセージ自体の送受信や AI の返信には影響しません。

## 受信側の最小サンプル <a href="#receiver-example" id="receiver-example"></a>

以下は、そのまま起動できる Python（Flask）の受信側です。署名とタイムスタンプの検証、メッセージ `id` による重複排除（再送時には同じメッセージを再度受け取ります）、`type` による振り分けを行い、2xx を返してから処理します。`MESSAGE_WEBHOOK_SECRET` は設定した `secretToken` に置き換えてください。カスタムヘッダーによる検証に切り替える場合は、対応するヘッダーを読み取るようにしてください。

{% code title="receiver.py" %}

```python
import hashlib
import hmac
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["MESSAGE_WEBHOOK_SECRET"]
TOLERANCE_SECONDS = 300
processed_ids: set[str] = set()  # 本番環境ではデータベースまたは Redis を使用し、保存期間を設定してください


def is_valid_signature(timestamp: str, signature: str, body: bytes) -> bool:
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    expected = "sha256=" + hmac.new(SECRET.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)


@app.post("/webhooks/maiagent-message")
def message_webhook():
    if not is_valid_signature(
        request.headers.get("X-MaiAgent-Timestamp", ""),
        request.headers.get("X-MaiAgent-Signature-256", ""),
        request.get_data(),
    ):
        abort(401)

    message = request.get_json(force=True)
    if message["id"] in processed_ids:
        return "", 204
    processed_ids.add(message["id"])

    conversation_id = message["conversation"]["id"]
    if message["type"] == "incoming":
        notify_new_message(conversation_id, message["content"])  # 例：「新着メッセージあり」を表示する
    elif message["type"] == "outgoing":
        archive_reply(conversation_id, message["content"])

    return "", 204  # 30 秒以内に 2xx を返してください。タイムアウトや 5xx は再送の原因になるため、時間のかかる処理はバックグラウンドに回してください


def notify_new_message(conversation_id, content):
    ...


def archive_reply(conversation_id, content):
    ...
```

{% endcode %}

```bash
MESSAGE_WEBHOOK_SECRET=あなたのシークレット flask --app receiver run --port 8080
```

ローカルでテストするには、次のコマンドで正しい署名付きのプッシュを模擬できます。

```bash
BODY='{"id":"acadbd9c-0000-0000-0000-000000000001","type":"incoming","content":"注文の住所を変更したいです","created_at":"2026-10-03T04:58:55.262828+00:00","conversation":{"id":"e6b27044-0000-0000-0000-000000000002","title":"注文住所の変更","type":"individual","status":"open","progress_status":"ai_processing","auto_reply_enabled":true,"assignee":null},"inbox":{"id":"6571672b-0000-0000-0000-000000000003","name":"公式サイトサポート","channel_type":"web"},"contact":{"id":"350691e0-0000-0000-0000-000000000004","name":"王小明","email":null,"phone_number":null},"sender":{"id":"350691e0-0000-0000-0000-000000000004","name":"王小明","type":"contact"},"attachments":[],"metadata":{}}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "あなたのシークレット" | sed 's/^.* //')
curl -X POST http://localhost:8080/webhooks/maiagent-message \
  -H "Content-Type: application/json" \
  -H "X-MaiAgent-Timestamp: $TS" \
  -H "X-MaiAgent-Signature-256: sha256=$SIG" \
  --data-raw "$BODY"
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/api/ja/preparation/message-webhook.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
