> 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/tech/ja/api-integration/customer-service-system-integration.md). # サードパーティのカスタマーサポートシステム連携（有人対応への転送を含む） カスタマーサポートシステムやチャットプラットフォームが API 経由で MaiAgent を AI エンジンとして組み込む方法：メッセージの送受信、AI が有人対応への転送を判定した際の有人オペレーターへの引き継ぎ、対応終了後の AI への復帰までのエンドツーエンド仕様 {% hint style="warning" %} **公開状況：本番環境へのリリース待ちです。** 本ページでは、4 種類のイベントと `id`／`occurred_at` を含むネストされたペイロードを使用する新しい有人転送仕様を説明しています。この仕様は本番環境にはまだリリースされていません。MaiAgent チームに対象環境の更新完了を確認するまで、本仕様による本番連携を開始しないでください。以下は連携の計画とテスト用の情報です。 {% endhint %} 本ページは「すでに自社のカスタマーサポートシステムやチャットフロントエンド（自社サイト、LINE、Messenger などのチャネルを自社側で保持）を持っており、MaiAgent を**AI エンジン**として使いたい」連携先向けです：訪問者のメッセージはあなたのシステムから MaiAgent に送信され、AI の返信はあなたのシステムに返送されます。AI が有人対応が必要と判定した場合は**あなたの有人オペレーター**が引き継ぎ、対応終了後に会話を再度 AI へ引き渡します。 この連携では MaiAgent 既存の公開 API と 2 種類の Webhook のみを使用し、特定のカスタマーサポートシステム専用のインターフェースを開発する必要はありません。 ## 連携全体像 ```mermaid sequenceDiagram participant V as 訪問者 participant S as あなたのカスタマーサポートシステム participant M as MaiAgent participant H as あなたの有人オペレーター V->>S: 発言（Web / LINE / …） S->>M: ① 身元同期（sourceId → contactId） S->>M: ② 会話を作成（初回のみ） S->>M: ③ メッセージ送信 POST /messages/ M-->>S: 201（AI の返信は非同期） M-)S: ④ Outgoing Webhook：AI の返信 S->>V: AI の返信を表示 Note over M: AI が有人対応が必要と判定 M-)S: ⑤ handoff.requested S->>H: 案件を作成し、オペレーターを割り当て H->>V: 有人対応を継続（あなたのシステム内で） S->>M: ⑥ PATCH /conversations/{id}/return-to-ai/ M-)S: handoff.returned_to_ai Note over M: 以降のメッセージは AI の返信に戻る ``` ### 双方の役割分担 | 誰が | 何を担当するか | | ------------ | ------------------------------------------------------------------------------------------------------------- | | **あなたのシステム** | チャネルの接続、訪問者向けインターフェース、案件と有人オペレーターの座席管理、会話履歴の保存と表示。訪問者のメッセージを MaiAgent に送信し、Webhook を受信し、有人対応終了時に AI への復帰を呼び出す | | **MaiAgent** | AI の返信、会話コンテキストの維持、LLM による有人対応への転送要否の判定、有人転送および AI への復帰イベントの配信 | ## 事前設定 以下はすべて MaiAgent 管理画面で行い、対話プラットフォームごとに 1 回設定すれば済みます。 ### 1. Web Chat 対話プラットフォームを作成し、認証情報を取得する API 連携には **Web Chat** タイプの対話プラットフォームを使用します。必要なもの： * **API キー**：取得方法は[クイックスタート](/tech/ja/api-integration/quickstart.md)を参照してください。 * **Web Chat ID**：AI アシスタント詳細ページの最下部にあります。 ### 2. Outgoing Webhook を設定する（AI の返信を受信） 設定 → 対話プラットフォーム → 該当プラットフォーム → Webhook → Webhook を追加で、タイプは **Outgoing** を選択し、エンドポイントにあなたの返信受信用 URL を入力します。フォーマットは **MaiAgent 標準フォーマット** を選択し、あなたのシステムが固定の JSON 構造を要求する場合は **カスタムテンプレート** を選択してください。フィールドと payload は [Webhook](/tech/ja/api-integration/webhook.md) を参照してください。 ### 3. 有人オペレーターへの転送を有効にする 同じ対話プラットフォームの → 有人転送設定 タブ： | 設定項目 | 推奨値 | | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 有人転送を有効にする | オン | | 判定モデル、ロール指示、参照メッセージ数 | 有人対応への転送要否を判定する LLM とルールです。デフォルトルール：訪問者が明確に有人対応を要求した場合、AI の処理能力を超える問題、訪問者の感情が良くない場合、人による確認が必要な会計操作が関わる場合。ロール指示であなたの業務に合わせて調整できます（例：キーワードの追加、確信度が低い場合は転送する、など） | | 待機タイムアウト時間 | **重要な設定です。** 有人転送後、会話はキューに入ります。この秒数を超えても MaiAgent 側のメンバーが引き継がない場合、MaiAgent は自動的に会話を AI に戻します。有人オペレーターがあなたのシステム側にいる場合、MaiAgent はその引き継ぎ動作を検知できないため、**0（タイムアウトなし、AI への復帰は自分で呼び出す）** に設定するか、有人対応全体をカバーできる十分な時間に設定してください | | キュー上限 | 同時に有人転送状態にある会話数の上限（1〜500）。上限に達すると、新しい有人転送リクエストはトリガーされません：そのメッセージには AI の返信が付かず、`handoff.requested` も送信されません。あなたのオペレーターの対応可能人数に合わせて設定してください | | 対応時間 | 有効にすると、対応時間外は AI が有人転送を行いません：オフライン時のメッセージを表示 の場合、そのメッセージには AI 返信が付かず、`handoff.requested` も送信されません（オフラインメッセージも Web Chat フロントエンドにのみ配信されるため、対応時間外の案内はあなたのシステム側で処理してください）。メッセージを受け付ける の場合はキューに入り `handoff.requested` が送信されます（このパスでは待機タイムアウトは起動しません） | {% hint style="warning" %} 転送通知メッセージ、キュー待機案内 などの「訪問者向けの案内文言」は MaiAgent 自社の Web Chat フロントエンドに配信されるものであり、**Webhook 経由であなたのシステムに送信されることはありません**。`handoff.requested` を受信したタイミングで、あなたのシステム側から訪問者に「有人オペレーターへおつなぎしています」といった案内を表示してください。 {% endhint %} ### 4. 有人転送 Webhook を有効にする 同じタブ → サブタブ 通知 → Webhook 通知（システム連携） をオンにし、以下を入力します： * Webhook URL：HTTPS のみ対応。 * 署名シークレット（推奨）：設定すると、配信ごとに HMAC-SHA256 署名が付与されます。検証方法は[手順五](#step-handoff)を参照してください。 メール通知 と 通知センターのお知らせ は会話が MaiAgent メンバーに割り当てられた場合にのみ送信されるもので、本連携とは無関係のためオフにして構いません。 {% hint style="info" %} 有人転送通知（Webhook を含む）はあなたの組織向けに MaiAgent 側で有効化する必要があります。通知タブにこの項目が表示されない場合は、担当窓口までご連絡ください。 {% endhint %} ## 手順一：訪問者の身元を紐付ける あなたのシステム内のユーザー ID を使って身元同期 API を呼び出し、その訪問者の MaiAgent 上の `contactId` を取得します： ```bash curl -X POST \ 'https://api.maiagent.ai/api/v1/web-chats/{webChatId}/setup-contact-credentials/' \ -H 'Content-Type: application/json' \ -d '{ "sourceId": "your-user-id", "name": "田中太郎" }' ``` ```json { "contactId": "c0ffee00-1111-2222-3333-444455556666" } ``` 同じ `sourceId` で繰り返し呼び出しても同じ `contactId` が返されます（冪等）。`sourceId ↔ contactId` の対応関係はあなたのユーザーデータに保存してください。`sourceId` には推測不可能な値を使用してください。詳細は[コンタクト身元同期と Token 更新](/tech/ja/authorization-integration/contact-credentials-sync.md)を参照してください。 ## 手順二：会話を作成する 訪問者ごとに 1 つの会話を作成し、**長期的に使い回します**。MaiAgent は会話単位でコンテキストを維持します： ```bash curl -X POST 'https://api.maiagent.ai/api/v1/conversations/' \ -H 'Authorization: Api-Key <あなたの API キー>' \ -H 'Content-Type: application/json' \ -d '{ "webChat": "", "contact": "" }' ``` レスポンス内の `id`（会話 ID）と `inbox.id`（対話プラットフォーム ID、Webhook 設定時に使用）を記録してください。レスポンスフィールドの詳細は[会話とメッセージの作成](/tech/ja/api-integration/dui-hua-yu-xun-xi.md)を参照してください。 来訪のたびに新しい会話を開始したい場合（例えば案件のクローズ後など）は、新しい会話を作成してください。過去の会話履歴はそのまま保持されます。 ## 手順三：訪問者のメッセージを送信する ```bash curl -X POST 'https://api.maiagent.ai/api/v1/messages/' \ -H 'Authorization: Api-Key <あなたの API キー>' \ -H 'Content-Type: application/json' \ -d '{ "conversation": "<会話 ID>", "content": "注文の進捗を確認したいです", "attachments": [] }' ``` レスポンス `201` はメッセージが作成されたことのみを示し、**AI の返信は数秒以内に Outgoing Webhook で配信されます**（手順四）。この HTTP レスポンス自体には返信内容は含まれません。添付ファイルは先にアップロードして添付ファイルオブジェクトを取得してから `attachments` に含めてください。詳細は[署名付きファイルアップロード方式](/tech/ja/api-integration/api_knowledge.md)を参照してください。 ## 手順四：AI の返信を受信する AI の返信が作成されると、MaiAgent はあなたが設定した Outgoing Webhook にリクエストを送信します。標準フォーマットの例では、あなたのエンドポイントは次のような内容を受信します： ```json { "id": "2491074a-6d23-4289-af45-caa12531420e", "type": "outgoing", "content": "ご注文 #12345 は現在配送中で、明日到着予定です。", "created_at": "2026-09-09T10:15:30.123456+00:00", "conversation": { "id": "8e44604a-8278-4c96-96b5-3e5a0548d738", "status": "open", "progress_status": "ai_processing", "auto_reply_enabled": true, "assignee": null }, "contact": { "id": "c0ffee00-1111-2222-3333-444455556666", "name": "田中太郎" }, "sender": { "id": "…", "name": "AI カスタマーサポート", "type": "chatbot" }, "attachments": [] } ``` あなたのシステムは `contact.id` で該当ユーザーを特定し、`conversation.id` で会話を特定した上で、`content` と添付ファイルをあなたのチャネル形式に変換して訪問者に送信します。2xx を返してください。フィールドの完全な一覧、カスタムテンプレート、配信の挙動については[Webhook](/tech/ja/api-integration/webhook.md)を参照してください。 {% hint style="info" %} payload 内で自社のユーザー ID やダウンロード可能な添付ファイル URL を直接取得したい場合は、**カスタムテンプレート**を使用して `contact.source_id` と `attachment.file.url` を出力してください。例は[Webhook › カスタムテンプレート](/tech/ja/api-integration/webhook.md#custom-template)を参照してください。 {% endhint %} ## 手順五：AI が有人転送を判定する 訪問者からメッセージが届くたびに、MaiAgent はまず判定モデルで有人対応が必要かどうかを判断します。「必要」と判定された場合： 1. 会話のステータスが `queued` になり、`auto_reply_enabled` が `false` になります。**このメッセージには AI の返信が付かず**、以降のメッセージも AI が返信しなくなります。 2. MaiAgent はあなたの有人転送 Webhook URL に `handoff.requested` イベントを送信します。 ### イベント payload ```json { "event": "handoff.requested", "id": "7d1e2f3a-4b5c-4d6e-8f90-1a2b3c4d5e6f", "occurred_at": "2026-09-09T10:15:30.123456+00:00", "conversation": { "id": "8e44604a-8278-4c96-96b5-3e5a0548d738", "url": "https://admin.maiagent.ai/conversations/index?conversationId=8e44604a-…" }, "inbox": { "id": "1f9c1c1e-4d1a-4b1e-9d0e-7b2f4a5c6d7e" }, "organization": { "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" }, "contact": { "id": "c0ffee00-1111-2222-3333-444455556666" }, "assignee": null } ``` | フィールド | 説明 | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `event` | イベント名。詳細は下記の[イベント一覧](#events)を参照 | | `id` | イベントの識別子。再送時も同一の内容が送られるため、これを使って重複排除してください | | `occurred_at` | イベント発生時刻（ISO 8601）。到着順序は保証されないため、これで並べ替えてください | | `conversation.id` / `contact.id` | 手順一・二で記録した会話と訪問者に対応します。`conversation.url` は MaiAgent 管理画面上の該当会話へのリンクです | | `inbox.id` / `organization.id` | 対話プラットフォームと組織の ID | | `assignee` | **イベント発生時点**で割り当てられていた MaiAgent メンバー `{ "id" }`（イベント発生時のスナップショットであり、その後の変化には影響されません）。`handoff.requested` およびあなたのオペレーターが引き継いだ場合は常に `null` | フィールド命名とネスト構造は手順四のメッセージ Webhook と同じです（snake\_case、関連オブジェクトは `{ "id" }` の形でネスト）。同じ受信エンドポイントで両方の配信をまとめて処理できます。payload には識別情報のみが含まれ、会話内容は含まれません。4 種類のイベントはすべて同じフィールド構成のため、`event` によって処理を分岐してください。完全な仕様とすぐに使える受信エンドポイントのサンプルは API ドキュメントの[有人転送 Webhook イベント](https://docs.maiagent.ai/api/preparation/handoff-webhook)を参照してください。 ### 配信と署名 * `POST`、`Content-Type: application/json`、タイムアウトは 10 秒。2xx 以外またはコネクション失敗の場合は**60 秒ごとに最大 3 回まで再試行**されます。 * 署名シークレットを設定している場合、リクエストには `X-MaiAgent-Signature-256: sha256=` ヘッダーが付与されます。値はシークレットで\*\*元のリクエスト本文（バイト列）\*\*を対象に計算した HMAC-SHA256 です。受信した生の body を使って検証し、一度パースしてから再シリアライズしないでください： ```python import hashlib import hmac def verify_maiagent_signature(secret: str, raw_body: bytes, header_value: str) -> bool: expected = 'sha256=' + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, header_value) ``` ### `handoff.requested` を受信した後 * あなたのシステムで案件を作成し、有人オペレーターを割り当て、訪問者に転送中である旨を表示してください。 * 以降の訪問者からのメッセージは、あなたのシステム内でオペレーターが処理します。**MaiAgent に送信し続ける必要はありません**。それでも MaiAgent 側に完全な履歴を残したい場合は、引き続き `POST /messages/` を呼び出すことができます。メッセージは会話に保存され Incoming Webhook がトリガーされますが、AI への復帰前は AI の返信は生成されません。 * 有人オペレーターの返信はあなたのシステムから直接訪問者に送信され、MaiAgent を経由する必要はありません。 ## 手順六：有人対応終了、AI への復帰 案件終了時に、AI への復帰を呼び出します： ```bash curl -X PATCH 'https://api.maiagent.ai/api/v1/conversations/{conversationId}/return-to-ai/' \ -H 'Authorization: Api-Key <あなたの API キー>' ``` 会話は `open` に戻り、`auto_reply_enabled` は `true` に戻ります。MaiAgent は `handoff.returned_to_ai` を送信し、以降の訪問者メッセージは再び AI が返信します。レスポンスは更新後の会話オブジェクトです。 {% hint style="warning" %} API キーの所属メンバーには、該当対話プラットフォームの会話へのアクセス権限が必要です。待機タイムアウト時間 が 0 でない場合、タイムアウト到達時に MaiAgent は自動的に AI へ復帰し `handoff.queue_timeout` を送信します。これがあなたの業務フローに適合しているか確認するか、事前設定を 0 に変更してください。対応時間外にメッセージを受け付ける設定でキューに入った会話は**待機タイムアウトが起動しない**ため、必ずあなたのシステムから `return-to-ai` を呼び出して終了させてください。 {% endhint %} ## イベント一覧 | `event` | トリガーされるタイミング | あなたのシステムにとっての意味 | | ------------------------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | `handoff.requested` | AI が有人対応が必要と判定し、会話がキューに入り、AI が返信を停止する | あなたの有人オペレーターが引き継ぐ | | `handoff.assigned` | 会話が MaiAgent 管理画面上のオペレーターメンバーに割り当てられた（メンバーが管理画面で引き継いだ、転送した、または自動割り当てされた場合。転送時にはさらに 1 件送信される） | 有人対応がすべてあなたのシステム側にある場合は、このイベントを受信することはありません | | `handoff.returned_to_ai` | あなたが `return-to-ai` を呼び出した、またはメンバーが管理画面で「AI エージェントに戻す」を押した | AI の返信が再開されるため、クローズできます | | `handoff.queue_timeout` | 待機タイムアウト時間が経過し、MaiAgent が自動的に会話を AI に戻した | AI の返信はすでに再開されています。あなたのオペレーターがまだ対応中の場合は、アラートが必要な異常です | 各イベントは `GET /api/v1/conversations/{id}/events/` で対応する `event_type`（`transfer_triggered`／`human_assigned`／`returned_to_ai`／`queue_timeout`）として確認でき、突合に利用できます。 {% hint style="info" %} 各イベントはそれぞれ個別のバックグラウンドタスクとして送信されるため、**到着順序は保証されず**、再試行により重複する場合もあります。イベント `id` で重複排除し、`occurred_at` で並べ替え、`handoff.assigned` はすでにトリガー済みとみなしてください。 {% endhint %} ### API で現在の状態を確認する Webhook 以外にも、いつでも会話が現在誰によって処理されているかを確認できます： ```bash GET https://api.maiagent.ai/api/v1/conversations/{conversationId}/ ``` `status`（`open`／`queued`／`resolved`）、`autoReplyEnabled`、`progressStatus`（`ai_processing`／`waiting_for_human`／`human_serving`）で状態を十分に復元できます。`GET /api/v1/conversations/{conversationId}/events/` は有人転送に関連するイベント履歴（`transfer_triggered`、`queued`、`human_assigned`、`returned_to_ai`、`queue_timeout` など）を一覧表示し、突合や補償処理に利用できます。 ## 連携前のよくある質問 カスタマーサポートシステムベンダーがキックオフ時によく尋ねる質問とその回答をここにまとめました。そのまま双方の連携ドキュメントの付録として利用できます。 ### 環境とパス | 環境 | Base URL | | --- | ------------------------------------- | | テスト | `https://api-dev.maiagent.ai/api/v1/` | | 本番 | `https://api.maiagent.ai/api/v1/` | この連携で使用するパスは固定です：`POST /web-chats/{webChatId}/setup-contact-credentials/`、`POST /conversations/`、`POST /messages/`、`PATCH /conversations/{id}/return-to-ai/`。突合には `GET /conversations/{id}/` と `GET /conversations/{id}/events/` を使用します。テスト環境の組織、API キー、Web Chat はあなたの担当窓口が作成した上で提供します。 ### 認証 * **あなたが MaiAgent を呼び出す場合**：ヘッダー `Authorization: Api-Key <キー>` を使用します。身元同期 API はキー不要で、`webChatId` によって識別されます。 * **MaiAgent があなたに配信する場合**：メッセージ Webhook にはあなたが設定した固定ヘッダー `X-Webhook-Secret` が付与されます。有人転送 Webhook には元のリクエスト本文に対して計算された HMAC-SHA256 署名 `X-MaiAgent-Signature-256: sha256=` が付与されます。 ### タイムアウト、再試行、流量上限 | 方向 | タイムアウト | 再試行 | | ----------------------------- | ------------------------------------ | --------------------------------------------------------------------------- | | あなたが `POST /messages/` を呼び出す | 同期的に 201 を返す。クライアント側のタイムアウトは 10 秒を推奨 | 4xx はまずリクエストを修正してください。5xx やタイムアウトは結果が不確定であることを意味するため、まず突合を行い、そのまま再送しないでください | | メッセージ Webhook（MaiAgent → あなた） | 30 秒 | **再試行なし**。先に永続化してから 2xx を返してください。メッセージ `id` で重複排除してください | | 有人転送 Webhook（MaiAgent → あなた） | 10 秒 | 失敗時は 60 秒ごとに最大 3 回まで再試行。イベント `id` で重複排除してください | `POST /messages/` は冪等性を保証しません：サーバー側でメッセージが作成済みでも、レスポンスが通信途中で失われる場合があります。まず会話履歴と自社の送信記録で結果を確認してください。確認できない場合、そのまま再送すると重複メッセージが追加され、AI の返信が再度トリガーされる可能性があります。 API キーごとに毎分のリクエスト上限（RPM）を設定できます。デフォルトでは制限なしです。本番稼働前に想定トラフィックをお知らせいただければ、担当窓口が設定します。 ### 送信元 IP ホワイトリスト MaiAgent が Webhook を配信する際の送信元 IP は固定です。あなたの受信エンドポイントでホワイトリストが必要な場合は、担当窓口に本番・テスト両環境の最新リストをご依頼ください。MaiAgent からあなたの受信エンドポイントのドメインへの送信には制限はありません。 ### 会話セッションの対応関係 キーはコンタクトの `sourceId` です（チャネルをまたいだ ID 衝突を避けるため `{プラットフォーム}:{あなたのユーザー ID}` の形式を推奨します）。同じ `sourceId` で身元同期 API を繰り返し呼び出しても同じ `contactId` が返されます。会話には**有効期限の制限がなく**、同じ会話 ID を長期的に使い回してコンテキストを維持することも、案件クローズ後に同じコンタクトで新しい会話を作成して仕切り直すことも可能です。 ### 有人転送の判定ロジック 判定モデルが会話の直近 N 件のメッセージに基づいて判断します。デフォルトルール：訪問者が明確に有人対応を要求した場合、AI の処理能力を超える問題、訪問者の感情が良くない場合、人による確認が必要な会計操作が関わる場合。ルールはロール指示で自然言語により調整でき、キーワードの追加や確信度が低い場合の転送などの条件を加えられます。また対応時間を設定して、対応時間外に転送するかどうかを決めることもできます。判定結果は `handoff.requested` イベントとして送信されます。 ### 複数回答とメッセージ形式 AI の返信ごとに 1 件のメッセージ Webhook が配信され（1 件につき 1 通知）、バッチ処理は行われません。1 件の返信に複数の添付ファイルを含めることは可能です。あなたのシステムが配列形式を要求する場合は、カスタムテンプレートで単一要素の配列を出力してください。標準ではテキスト（Markdown）と添付ファイル（画像／動画／音声／ファイル）に対応しています。ボタン、カード、クイックリプライなどチャネル固有の表示形式は標準の対応範囲外のため、キックオフ時に要件を提示の上、別途評価します。 ### 添付ファイルの URL と有効期限 AI の返信の添付ファイルはカスタムテンプレートで `attachment.file.url` として出力されます。これは署名付き URL で**有効期限は 1 時間**のため、受信後は直ちにファイルを取得して保存してください。訪問者がアップロードした添付ファイルは、あなたのシステム側で先にダウンロード可能な URL を取得し、メッセージ送信時に `attachments[]` に含めてください。 ### エラーと利用量の確認 メッセージ Webhook の配信ごとのリクエスト、レスポンス、ステータスコードは MaiAgent 管理画面の AI アシスタントページの Webhook タブで確認できます。会話の状態や有人転送イベントは会話 API とイベント履歴 API で突合できます。AI の利用量は管理画面の利用状況統計で確認できます。有人転送 Webhook の配信失敗は MaiAgent の監視アラートに記録されます。 ## 連携チェックリスト * [ ] 管理画面：Outgoing Webhook が設定され、AI の返信を受信できる * [ ] 管理画面：有人転送が有効化され、待機タイムアウト時間 が業務フローに合わせて設定されている（外部の有人オペレーターの場合は 0 を推奨） * [ ] 管理画面：有人転送 Webhook が有効化され、HTTPS エンドポイントに到達可能で、署名検証が通過している * [ ] あなたのシステム：`sourceId ↔ contactId ↔ conversationId` の対応関係が実装されている * [ ] あなたのシステム：`handoff.requested` → 案件作成と転送案内、`handoff.returned_to_ai` → クローズ、`handoff.queue_timeout` → アラートまたはクローズ * [ ] あなたのシステム：有人対応終了時に `return-to-ai` を呼び出す * [ ] 両方の Webhook エンドポイントが冪等になっている：有人転送イベントとメッセージ配信をそれぞれの `id` で重複排除 * [ ] ネットワークで送信元 IP ホワイトリストが必要な場合は、担当窓口に MaiAgent の送信元 IP をご依頼ください ## 関連ページ * [有人転送 Webhook イベント](https://docs.maiagent.ai/api/preparation/handoff-webhook)（API ドキュメント）：イベントの完全な仕様、署名検証、すぐに使える受信エンドポイントのサンプル、および訪問者が MaiAgent チャネル、有人オペレーターがあなたのシステムにいる場合の引き継ぎ方法 * [Webhook](/tech/ja/api-integration/webhook.md)：メッセージ配信フォーマット、カスタムテンプレート、API による Webhook 管理 * [会話とメッセージの作成](/tech/ja/api-integration/dui-hua-yu-xun-xi.md)：会話とメッセージ API の完全なフィールド一覧 * [コンタクト身元同期と Token 更新](/tech/ja/authorization-integration/contact-credentials-sync.md)：`setup-contact-credentials` の完全な仕様 * [署名付きファイルアップロード方式](/tech/ja/api-integration/api_knowledge.md)：添付ファイルのアップロード --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.maiagent.ai/tech/ja/api-integration/customer-service-system-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.