> 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/handoff-webhook.md).

# 有人対応への切り替え Webhook イベント

有人対応への引き継ぎのライフサイクル（AI による引き継ぎ判定、担当者の割り当て、AI への復帰、キューのタイムアウト）を Webhook で指定のシステムエンドポイントに配信します。本ページではイベントの種類と形式、署名検証、再試行の動作を説明します。

有人対応への引き継ぎフローの各段階（AI による有人対応の必要性の判定、担当者への割り当て、AI への復帰、キューのタイムアウト）で、MaiAgent は設定したエンドポイントに HTTPS POST でイベントを配信します。これにより、担当者の手配、アラート、CRM、自分のサポートシステムで、ポーリングなしに自動的に対応を引き継げます。イベント名は引き継ぎの状態遷移を表す固定の公開契約です。各イベントには会話イベントログ API（`GET /api/v1/conversations/{id}/events/`）で対応する `event_type` があり（下表を参照）、照合や、同じ情報をポーリングで取得する場合に利用できます。

## 有効にする方法

顧客の管理者または連携担当者が管理画面で設定でき、エンジニアの支援は不要です。

1. 管理画面の「サポート会話」→「会話プラットフォーム」→ 連携する会話プラットフォームを編集 →「有人対応への引き継ぎ設定」→「通知」タブを開きます
2. 「Webhook 通知（システム連携）」を有効にし、受信側の URL を入力します（`https://` で始まる URL のみ使用できます）
3. （任意ですが推奨します）署名シークレットを入力し、送信元の検証を有効にします（下記の「署名検証」を参照）

Webhook、通知センター、Email は独立した 3 つのスイッチで、互いに影響しません。デフォルトでは無効で、受信トレイごとに有効にします。このチャネルは、受信トレイの既存の「メッセージ Webhook」（メッセージの送受信）とは別のものです。

## イベントの種類 <a href="#event-types" id="event-types"></a>

| event                    | イベントログ API の `event_type` | 配信タイミング                                                               | 備考                                                                                                                                                                                                                                                            |
| ------------------------ | ------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `handoff.requested`      | `transfer_triggered`      | AI が有人対応を必要と判断したときです。会話はキューに入り、AI の自動返信が停止します                         | 各引き継ぎフローの最初のイベントです。`assignee` は `null` です。有人サポートが自分のシステムを利用している場合、これが引き継ぎ開始の合図です                                                                                                                                                                              |
| `handoff.assigned`       | `human_assigned`          | 会話が MaiAgent 管理画面のサポート担当者に割り当てられたときです（手動割り当て、自分での担当取得、転送、自動割り当てを含みます） | `assignee` は割り当てられた担当者です。別の担当者への転送時には、異なるイベント `id` で再度配信されます                                                                                                                                                                                                  |
| `handoff.returned_to_ai` | `returned_to_ai`          | 担当者が管理画面で「AI Agent に戻す」を押すか、`return-to-ai` API で会話を AI に戻したときです       | `assignee` は `null` です（会話に担当者はいません）                                                                                                                                                                                                                           |
| `handoff.queue_timeout`  | `queue_timeout`           | 受信トレイに設定された「待機タイムアウト」を超えても担当者が引き継がず、MaiAgent が会話を自動的に AI に戻したときです     | `assignee` は `null` です。有人サポートが自分のシステムを利用している場合、受信は MaiAgent が認識されないまま AI の返信を再開したことを意味します。アラートが必要な異常として扱ってください。または、担当者の手配設定で「引き継ぎ方式」を選び、「タイムアウトなし」を有効にします（API では `dispatchMode: "handover"`、`assignmentQueueTimeout: 0` です。自動割り当てモードでは 0 を送信すると 300 秒に変更されます） |

4 種類のイベントは payload のキー、署名、再試行の動作がすべて同じです。受信側では **`event` フィールドに応じて処理を振り分けてください**。今後イベントの種類が追加される可能性があります。未知の `event` を受信した場合は 2xx を返して無視し、エラーとして扱わないでください。

`handoff.returned_to_ai` と `handoff.queue_timeout` はどちらも「AI が自動返信を再開した」ことを意味します。前者は人（担当者または自分のシステム）による明示的な操作、後者はタイムアウトによる自動処理です。どちらも「会話が完了した」ことは意味しません。担当者が会話を直接「解決済み」にした場合や、担当者が受信トレイの権限を失って会話が再びキューに入った場合は、イベントは配信されません。会話の完了を漏れなく把握するには、会話 API で `status` を確認するか、メッセージ Webhook の `conversation.progress_status` の変化を確認してください。

## イベントの形式

```
POST <設定した URL>
Content-Type: application/json
```

```json
{
  "event": "handoff.assigned",
  "id": "9f0e1d2c-...",
  "occurred_at": "2026-09-09T02:30:00.123456+00:00",
  "conversation": {
    "id": "6c2b7c1e-...",
    "url": "https://admin.maiagent.ai/..."
  },
  "inbox": { "id": "0f9a3d42-..." },
  "organization": { "id": "b1d20c77-..." },
  "contact": { "id": "a4c1f6b3-..." },
  "assignee": { "id": "3e8f5a90-..." }
}
```

| フィールド            | 型                  | 説明                                                                                                                    |
| ---------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| event            | string             | イベント名です（上記の「イベントの種類」を参照）                                                                                              |
| id               | string (uuid)      | イベント識別子です。イベントログ API が返す `id` と同じです。再試行時の内容は完全に同じなので、**この値で重複排除してください**                                               |
| occurred\_at     | string (date-time) | イベント発生時刻（ISO 8601）です。配信の到着順序は保証されないため、**この値で並べ替えてください**                                                               |
| conversation.id  | string (uuid)      | 会話識別子です                                                                                                               |
| conversation.url | string (uri)       | 管理画面の会話ページへのリンクです                                                                                                     |
| inbox.id         | string (uuid)      | 受信トレイ識別子です                                                                                                            |
| organization.id  | string (uuid)      | 組織識別子です                                                                                                               |
| contact          | object \| null     | 顧客（連絡先）の `{ "id" }` です。会話に連絡先がない場合は `null` です                                                                         |
| assignee         | object \| null     | **イベント発生時点**で割り当てられた担当者の `{ "id" }` です。イベントのスナップショットなので、配信の遅延や後の転送で変化しません。`handoff.assigned` のみ値があり、他のイベントは `null` です |

フィールド名とネスト構造は、受信トレイの「メッセージ Webhook」の MaiAgent 標準形式と同じです（snake\_case、関連オブジェクトは `{ "id" }` の形式でネストします）。同じ受信側で両方の Webhook を処理できます。Payload に含まれるのは識別情報、イベント時刻、管理画面へのリンクのみで、**会話のテキスト内容や有人対応への引き継ぎ理由は含まれません**。会話内容が必要な場合は、識別子を使って会話 API とメッセージ API を呼び出してください。

## 署名検証（有効化を推奨します）

管理画面で署名シークレットを設定すると、すべての配信に次のヘッダーが付加されます。

```
X-MaiAgent-Signature-256: sha256=<hex digest>
```

値は、シークレットを使って**元の request body bytes** に対して計算した HMAC-SHA256 の 16 進数ダイジェストです。検証には必ず受信した元の bytes を使用してください。先に解析して再シリアライズすると、フィールドの順序や空白の違いでダイジェストが一致しなくなります。

```python
import hashlib
import hmac


def verify_signature(raw_body: bytes, header_value: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header_value)
```

シークレットは書き込み専用です。保存後は再表示されず、管理画面には「設定済み」とだけ表示されます。フィールドを空欄にして保存すると既存のシークレットが維持されます。変更する場合は新しい値を入力し、削除する場合は「シークレットをクリア」を使用してください。シークレットが未設定の場合、配信には署名ヘッダーが付きません。

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

以下はそのまま起動できる Python（Flask）の受信側サンプルです。元の bytes で署名を検証し、`event` に応じて処理を振り分け、時間のかかる処理を行う前に 2xx を返します。`HANDOFF_WEBHOOK_SECRET` に、管理画面で設定した署名シークレットを指定してください。

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

```python
import hashlib
import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["HANDOFF_WEBHOOK_SECRET"]


def verify_signature(raw_body: bytes, header_value: str | None) -> bool:
    if not header_value:
        return False
    expected = "sha256=" + hmac.new(SECRET.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header_value)


@app.post("/webhooks/handoff")
def handoff_webhook():
    raw = request.get_data()  # 元の bytes を使い、request.json を再シリアライズしないでください
    if not verify_signature(raw, request.headers.get("X-MaiAgent-Signature-256")):
        abort(401)

    event = request.get_json(force=True)
    if already_processed(event["id"]):  # 再試行では同じ内容が届くため、イベント id で重複排除します
        return "", 204

    conversation_id = event["conversation"]["id"]
    if event["event"] == "handoff.requested":
        # AI の返信は停止しています。担当者が自分のシステムを利用する場合、ここでチケットを作成して担当者を手配します
        open_ticket(conversation_id, event["conversation"]["url"])
    elif event["event"] == "handoff.assigned":
        # MaiAgent 管理画面の担当者に割り当てられました。別の担当者に転送すると、assignee が変わったイベントが再び届きます
        assign_ticket(conversation_id, event["assignee"]["id"])
    elif event["event"] == "handoff.returned_to_ai":
        close_ticket(conversation_id)
    elif event["event"] == "handoff.queue_timeout":
        # MaiAgent が AI の返信を自動再開しました。担当者がまだ対応中であれば、アラートが必要な異常です
        close_ticket(conversation_id, reason="queue_timeout")
    # 未知のイベントには 2xx を返して無視し、エラーとして扱いません

    return "", 204  # 10 秒以内に 2xx を返し、時間のかかる処理はバックグラウンドで実行します


def already_processed(event_id):
    ...


def open_ticket(conversation_id, url):
    ...


def assign_ticket(conversation_id, assignee_id):
    ...


def close_ticket(conversation_id, reason=None):
    ...
```

{% endcode %}

```bash
HANDOFF_WEBHOOK_SECRET=your_secret flask --app receiver run --port 8080
```

ローカルテストでは、以下のコマンドで配信をシミュレートできます（署名は同じシークレットで計算します）。

```bash
BODY='{"assignee":{"id":"3e8f5a90-0000-0000-0000-000000000004"},"contact":{"id":"a4c1f6b3-0000-0000-0000-000000000005"},"conversation":{"id":"6c2b7c1e-0000-0000-0000-000000000001","url":"https://admin.maiagent.ai/conversations/index?conversationId=6c2b7c1e-0000-0000-0000-000000000001"},"event":"handoff.assigned","id":"9f0e1d2c-0000-0000-0000-000000000006","inbox":{"id":"0f9a3d42-0000-0000-0000-000000000002"},"occurred_at":"2026-09-09T02:30:00.123456+00:00","organization":{"id":"b1d20c77-0000-0000-0000-000000000003"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "your_secret" | awk '{print $NF}')
curl -X POST http://localhost:8080/webhooks/handoff \
  -H "Content-Type: application/json" \
  -H "X-MaiAgent-Signature-256: sha256=$SIG" \
  -d "$BODY"
```

## 応答と再試行

* 受信側は 10 秒以内に 2xx ステータスコードを返してください。レスポンスの内容は任意です。
* タイムアウト、接続失敗、2xx 以外のレスポンスの場合、システムは 60 秒間隔で最大 3 回自動再試行します。再試行の内容は元の配信と完全に同じで、`id` も同じです。受信側ではイベントの `id` で重複排除してください。各イベントは個別のバックグラウンドタスクで配信されるため、`handoff.requested` とその直後の `handoff.assigned` は順序どおりに届かない場合があります。`occurred_at` で並べ替えてください。
* Webhook の配信失敗は、引き継ぎのメインフローや、通知センターと Email の通知には影響しません。

## 有人対応への引き継ぎ後に外部システムで会話を引き継ぐ <a href="#external-takeover" id="external-takeover"></a>

有人サポート担当者が MaiAgent 管理画面ではなく自分のサポートシステムで返信する場合は、本ページのイベント、会話プラットフォームの「メッセージ Webhook」、メッセージ API を組み合わせて、有人対応中の会話を双方向に同期できます。`handoff.requested` を受信したら自分のシステムでチケットを作成し、メッセージ Webhook で訪問者のメッセージを受信し、`POST /api/v1/messages/outgoing/` で担当者の返信を送信します。対応完了後は `PATCH /api/v1/conversations/{id}/return-to-ai/` を呼び出して AI に戻します。全体のフロー、呼び出し例、注意事項は、技術マニュアルの[外部サポートシステム連携（有人対応への引き継ぎを含む）](https://docs.maiagent.ai/tech/serve/customer-service-system-integration#scenarios)を参照してください。訪問者のチャネルが自分のシステムに接続されている場合はシナリオ A、訪問者が MaiAgent の会話プラットフォームを利用し、有人サポートだけが自分のシステムを利用する場合はシナリオ B を参照してください。

### 連携フロー <a href="#takeover-flow" id="takeover-flow"></a>

技術マニュアルの[シナリオ B › 連携フロー](https://docs.maiagent.ai/tech/serve/customer-service-system-integration#scenario-b-flow)を参照してください。

### 呼び出し例 <a href="#takeover-examples" id="takeover-examples"></a>

技術マニュアルの[シナリオ B › 呼び出し例](https://docs.maiagent.ai/tech/serve/customer-service-system-integration#scenario-b-examples)を参照してください。

### 注意事項 <a href="#takeover-notes" id="takeover-notes"></a>

技術マニュアルの[シナリオ B › 注意事項](https://docs.maiagent.ai/tech/serve/customer-service-system-integration#scenario-b-notes)を参照してください。


---

# 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/handoff-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.
