外部カスタマーサービスシステムとの連携（オペレーターへの引き継ぎを含む）

カスタマーサポートシステムやチャットプラットフォームから API で MaiAgent を AI エンジンとして利用するためのエンドツーエンド仕様です。メッセージの送受信、AI が有人対応を必要と判断した際の自社オペレーターへの引き継ぎ、対応終了後の AI への復帰を説明します。

このページは、すでに自社のカスタマーサポートシステムやチャット画面を持ち（自社 Web サイト、LINE、Messenger などのチャネルを自社側に接続している場合）、MaiAgent を AI エンジンとして利用したい連携担当者向けです。訪問者のメッセージを自社システムから MaiAgent に送り、AI の返信を自社システムで受け取ります。AI が有人対応を必要と判断した場合は、自社のオペレーターが引き継ぎ、対応終了後に会話を AI に戻します。

連携には MaiAgent の既存の公開 API と 2 系統の Webhook のみを使用します。個別のカスタマーサポートシステム向けに専用インターフェースを開発する必要はありません。

2 つの連携シナリオ

シナリオ	訪問者が会話する場所	オペレーターが対応する場所	連携方法
シナリオ A：MaiAgent を AI エンジンとして利用します	自社システム（自社 Web サイト、LINE などのチャネルを自社側に接続します）	自社システム	事前設定の後、ステップ 1～ステップ 6に従います
シナリオ B：オペレーターのみが自社システムを利用します	MaiAgent の会話プラットフォーム（Web Chat、LINE 公式アカウントなどを MaiAgent に接続します）	自社システム	事前設定の後、シナリオ Bに従います

どちらのシナリオも、有人対応への引き継ぎイベント、イベント一覧、状態の照会は共通です。以下の連携概要とステップ 1～6 では、シナリオ A を説明します。

連携の全体像

双方の役割

担当	役割
自社システム	チャネル接続、訪問者向け画面、チケットとオペレーター席、会話履歴の保存と表示を担当します。訪問者のメッセージを MaiAgent に送り、Webhook を受信し、有人対応終了時に AI への復帰 API を呼び出します
MaiAgent	AI の返信、会話コンテキストの維持、LLM による有人対応への引き継ぎ判定、有人対応への引き継ぎと AI への復帰イベントの送信を担当します

事前設定

以下はすべて MaiAgent の管理画面で行います。会話プラットフォームごとに一度設定します。

1. Web Chat 会話プラットフォームを作成し、認証情報を取得します

API 連携には Web Chat タイプの会話プラットフォームを使用します。次の情報が必要です。

• API キー：取得方法はクイックスタートを参照してください。

• Web Chat ID：カスタマーサポート会話 → 会話プラットフォーム → 対象の API プラットフォームを編集 → 連携とログイン → Webhook 設定の最下部にあるAPI 情報カードで確認できます。読み取り専用で、コピーできます。ユーザーマニュアルの会話プラットフォームの基本設定を参照してください。

2. Outgoing Webhook を設定します（AI の返信を受信します）

カスタマーサポート会話 → 会話プラットフォーム → 対象のプラットフォームを編集 → Webhook 設定 → Webhook を追加を選択します。タイプは Outgoing を選び、エンドポイントに自社の返信受信 URL を入力します。形式は MaiAgent 標準形式を選択します。自社システムで固定の JSON 構造が必要な場合は、カスタムテンプレートを選択します。フィールドと payload は Webhook を参照してください。

3. オペレーターへの引き継ぎを有効にします

同じ会話プラットフォームの有人対応への引き継ぎ設定を開きます。各フィールドの意味と操作画面は、ユーザーマニュアルの有人対応への引き継ぎ設定を参照してください。オペレーターが自社システムで対応する場合は、次の設定を推奨します。

設定	オペレーターが自社システムで対応する場合の推奨設定
オペレーターへの引き継ぎを有効化	有効にします
有人対応への引き継ぎ条件の判定ルール（ロール指示）	まずはデフォルトのルールを使用します。訪問者が明示的に有人対応を求めた場合、AI で対応できない問題、訪問者の感情が悪化した場合、人による確認が必要な請求・アカウント関連操作が対象です。その後、キーワードの追加や確信度が低い場合の引き継ぎなど、業務に合わせて調整します
割り当て設定 → 割り当てモード	引き受け方式を選択します。MaiAgent は管理画面のメンバーに会話を割り当てません。会話は待機キューに残り、自社システムが引き継ぎます
割り当て設定 → 待機タイムアウト	タイムアウトなしにチェックを入れます（引き受け方式のみ選択できます）。AI への復帰 API を呼び出すまで会話は待機キューに残ります。MaiAgent が自動的に AI に戻すことはありません
割り当て設定 → キュー上限	オペレーターの対応能力に合わせて設定します（1～500）。上限に達すると、新たな有人対応への引き継ぎリクエストは発生しません。そのメッセージには AI の返信がなく、handoff.requested も送信されません
対応時間	必要に応じて有効にします。オフラインメッセージを表示の場合、対応時間外は有人対応に引き継ぎません。そのメッセージには AI の返信がなく、handoff.requested も送信されません（オフラインメッセージは Web Chat のフロントエンドにのみ送信されるため、時間外の案内は自社システムで処理してください）。メッセージを受け付けるの場合は、待機キューに入り handoff.requested が送信されますが、待機タイムアウトは開始されません

API で会話プラットフォームを設定する場合、引き受け方式とタイムアウトなしは dispatchMode: "handover" と assignmentQueueTimeout: 0 に対応します。

自動割り当てモードでは、待機タイムアウトを 0 に設定しないでください。 自動割り当て（デフォルト）の待機タイムアウトに指定できる値は 1～3600 秒のみです。画面で 0 を入力すると範囲外の警告が表示され、API で 0 を送信するとデフォルトの 300 秒に変更されます。300 秒以内に MaiAgent のメンバーが引き継がない場合、MaiAgent は handoff.queue_timeout を送信して会話を AI に戻します。訪問者も自社のオペレーターも、この切り替えに気付きません。

引き継ぎ通知メッセージやキュー待機案内などの訪問者向け案内文は、MaiAgent 自身の Web Chat フロントエンドに送信され、Webhook 経由では自社システムに送信されません。handoff.requested を受信した際に、自社システムで「オペレーターにおつなぎしています」などの案内を訪問者に表示してください。

4. 有人対応への引き継ぎ Webhook を有効にします

同じタブのサブタブ通知を開き、Webhook 通知（システム連携）を有効にして、次の情報を入力します。

• Webhook URL：HTTPS のみ使用できます。

• 署名シークレット（任意）（設定を推奨します）：設定すると、各送信に HMAC-SHA256 署名が付与されます。検証方法は送信と署名を参照してください。

Email 通知と通知センターのお知らせは、会話が MaiAgent のメンバーに割り当てられた場合にのみ送信されます。この連携では使用しないため、無効にできます。

この 3 つの通知スイッチは、会話プラットフォームの管理者が管理画面で有効にします。別途申請する必要はありません。操作画面はユーザーマニュアルの有人対応への引き継ぎ通知を参照してください。

ステップ 1：訪問者の ID を対応付けます

自社システムのユーザー ID を指定して ID 同期 API を呼び出し、訪問者の MaiAgent 側の contactId を取得します。

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": "王小明" }'

{ "contactId": "c0ffee00-1111-2222-3333-444455556666" }

同じ sourceId で繰り返し呼び出すと、同じ contactId が返されます（冪等です）。sourceId ↔ contactId の対応を自社のユーザーデータに保存してください。sourceId には推測できない値を使用してください。詳細は連絡先 ID の同期と Token の更新を参照してください。

ステップ 2：会話を作成します

訪問者ごとに 1 つの会話を作成し、長期間継続して使用します。MaiAgent は会話単位でコンテキストを維持します。

curl -X POST 'https://api.maiagent.ai/api/v1/conversations/' \
  -H 'Authorization: Api-Key <自社のAPIキー>' \
  -H 'Content-Type: application/json' \
  -d '{ "webChat": "<Web Chat ID>", "contact": "<contactId>" }'

レスポンスの id（会話 ID）と inbox.id（会話プラットフォーム ID。Webhook の設定時に使用します）を記録してください。レスポンスのフィールドは会話とメッセージの作成を参照してください。

訪問のたびに新しい会話を開始したい場合（チケットのクローズ後など）は、新しい会話を作成します。以前の会話履歴は保持されます。

ステップ 3：訪問者のメッセージを送信します

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 で送信されます（ステップ 4）。HTTP レスポンス自体には返信は含まれません。添付ファイルは先にアップロードして添付オブジェクトを取得し、attachments に指定してください。Presigned ファイルアップロード方式を参照してください。

ステップ 4：AI の返信を受信します

AI の返信が作成されると、MaiAgent は設定した Outgoing Webhook にリクエストを送信します。標準形式では、エンドポイントは次のようなデータを受信します。

{
  "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 を参照してください。

payload 内で自社のユーザー ID やダウンロード可能な添付ファイル URL を直接取得するには、カスタムテンプレートで contact.source_id と attachment.file.url を出力します。例は Webhook › カスタムテンプレートを参照してください。

ステップ 5：AI が有人対応への引き継ぎを判断します

訪問者のメッセージを受信するたびに、MaiAgent はまず判定モデルで有人対応が必要かを判断します。必要と判断した場合は、次のように処理します。

1. 会話の状態が queued になり、auto_reply_enabled が false になります。このメッセージには AI の返信がありません。以降のメッセージにも AI は返信しません。

2. MaiAgent は自社の有人対応への引き継ぎ Webhook URL に handoff.requested イベントを送信します。

イベント payload

フィールド一覧と JSON の例は、API ドキュメントの有人対応への引き継ぎ Webhook イベントの「イベント形式」を参照してください。このフローの連携では、次の点を把握してください。

• 4 種類のイベントはすべて同じフィールドを持ちます。event に応じて処理を分岐してください（下記のイベント一覧を参照してください）。

• conversation.id と contact.id は、ステップ 1、2 で記録した会話と訪問者に対応します。

• イベントの id で重複を排除し、occurred_at で順序を判断します。payload には識別情報のみが含まれ、会話の内容は含まれません。

• assignee はイベント発生時に割り当てられている MaiAgent のメンバーです。handoff.requested および自社のオペレーターが引き継ぐ場合は常に null です。

• フィールド名とネスト構造はステップ 4 のメッセージ Webhook と同じなので、同じ受信エンドポイントで両系統の送信を処理できます。

送信と署名

POST、Content-Type: application/json で送信し、タイムアウトは 10 秒です。2xx 以外のレスポンスまたは接続失敗の場合、60 秒ごとに最大 3 回再試行します。署名シークレットが設定されている場合、リクエストに X-MaiAgent-Signature-256: sha256=<hex> が付与されます。値は、シークレットを用いて元のリクエスト本文に対して計算した HMAC-SHA256 です。検証コードとそのまま起動できる受信エンドポイントの例は、API ドキュメントの有人対応への引き継ぎ Webhook イベントの「署名検証」と最小受信エンドポイントの例を参照してください。

自社システムで handoff.requested を受信した後の処理

• 自社システムでチケットを作成し、オペレーターを割り当て、訪問者に引き継ぎ案内を表示します。

• 以降、訪問者のメッセージは自社システム内でオペレーターが処理します。MaiAgent への送信を停止しても構いません。MaiAgent に完全な履歴を保持したい場合は、引き続き POST /messages/ を呼び出せます。メッセージは会話に保存され、Incoming Webhook が発生しますが、AI に戻るまで AI の返信は生成されません。

• オペレーターの返信は、自社システムから直接訪問者に送信します。MaiAgent を経由する必要はありません。

ステップ 6：有人対応終了後に AI に戻します

チケットの対応が終了したら、AI への復帰 API を呼び出します。

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 が再び返信します。レスポンスは更新後の会話オブジェクトです。

API キーを所有するメンバーには、対象の会話プラットフォームの会話アクセス権限が必要です。事前設定に従って引き受け方式を選択し、タイムアウトなしにチェックを入れていない場合、待機タイムアウトの満了時に MaiAgent は自動的に AI に戻し、handoff.queue_timeout を送信します。この動作が自社のフローに合っているか確認してください。対応時間外にメッセージを受け付けるで待機キューに入った会話は、待機タイムアウトが開始されません。必ず自社システムから return-to-ai を呼び出して終了する必要があります。

シナリオ B：訪問者は MaiAgent の会話プラットフォーム、オペレーターは自社システムを利用します

訪問者は MaiAgent の会話プラットフォームで Agent と会話し、有人対応への引き継ぎ後のみ、オペレーターが自社のカスタマーサポートシステムから返信します。訪問者のメッセージは最初から MaiAgent に入るため、自社システムでステップ 1～3 を実施する必要はありません。代わりに、メッセージ Webhook で有人対応中のメッセージを自社システムに取り込み、API でオペレーターの返信を会話に書き戻して、双方向に同期します。

事前設定は訪問者が利用する会話プラットフォームで行います。オペレーターへの引き継ぎの有効化（引き受け方式＋タイムアウトなし）と有人対応への引き継ぎ Webhook の有効化はシナリオ A と同じです。メッセージ Webhookには Incoming（訪問者のメッセージ）と Outgoing（Agent またはオペレーターの返信）の両方向を追加します。オペレーターの返信の書き戻しと AI への復帰には API キーが必要です。取得方法はクイックスタートを参照してください。

連携フロー

1. 有人対応への引き継ぎ開始を検知します：handoff.requested を受信したら、自社システムで conversation.id を使ってチケットまたはセッションを作成し、contact.id を記録します。イベントに会話本文は含まれません。引き継ぎ前の会話内容が必要な場合は、conversation.id を使って API ドキュメントのメッセージ一覧の取得を呼び出します。その後 handoff.assigned を受信した場合は、会話が MaiAgent 管理画面のメンバーに割り当てられたことを示します。assignee.id がそのメンバーです。

2. 訪問者のメッセージとオペレーターの返信を受信します：各メッセージ Webhook の payload には、会話の現在の状態が含まれます。conversation.auto_reply_enabled が false のメッセージのみを処理すると、Agent が自動返信している間のトラフィックを除外できます。sender.type で訪問者（contact）、オペレーター（user）、Agent（chatbot）を区別します。フィールド定義は Webhook › フィールドの説明を参照してください。

3. オペレーターの返信を会話に書き戻します：API キーを使って POST /api/v1/messages/outgoing/ を呼び出し、conversation と content を指定します。MaiAgent は訪問者が利用する会話プラットフォームにメッセージを送信します。送信者は API キーを所有するメンバーであり、そのメンバーには対象プラットフォームの会話アクセス権限が必要です。フィールドは API ドキュメントの能動的なメッセージの送信を参照してください。

4. 有人対応への引き継ぎを終了します：対応終了後に return-to-ai を呼び出すと（呼び出し方法はステップ 6と同じです）、Agent が再び引き継ぎます。自社が API を呼び出した場合でも、メンバーが管理画面で「AI Agent に戻す」をクリックした場合でも、handoff.returned_to_ai を受信します。このイベントに基づいて自社システムのセッションを閉じてください。

推奨の引き受け方式＋タイムアウトなしの設定では、有人対応への引き継ぎ後も会話は待機キューに残り、conversation.progress_status は waiting_for_human になります。MaiAgent 管理画面のメンバーに会話が割り当てられた場合のみ、human_serving に変わります。有人対応中かどうかは auto_reply_enabled で判断してください。progress_status が human_serving かどうかだけを確認すると、訪問者のメッセージを取りこぼします。

呼び出し例

（1）有人対応への引き継ぎ中に受信するメッセージ Webhook（MaiAgent 標準形式、抜粋）：auto_reply_enabled が false の場合は有人対応中です。sender.type が contact の場合は訪問者のメッセージです。

{
  "id": "9d2f7a10-...",
  "type": "incoming",
  "content": "注文の配送先住所を変更したいです",
  "created_at": "2026-09-09T02:30:00+00:00",
  "conversation": {
    "id": "6c2b7c1e-...",
    "title": "...",
    "type": "individual",
    "status": "queued",
    "progress_status": "waiting_for_human",
    "auto_reply_enabled": false,
    "assignee": null
  },
  "inbox": { "id": "0f9a3d42-...", "name": "公式サイトのカスタマーサポート", "channel_type": "web" },
  "contact": { "id": "a4c1f6b3-...", "name": "王小明", "email": null, "phone_number": null },
  "sender": { "id": "a4c1f6b3-...", "name": "王小明", "type": "contact" },
  "attachments": [],
  "metadata": {}
}

（2）オペレーターの返信を会話に書き戻します：conversation と content のみを指定すれば、API キーを所有するメンバーとして、訪問者が利用する会話プラットフォームにメッセージが送信されます。

curl -X POST "https://api.maiagent.ai/api/v1/messages/outgoing/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": "6c2b7c1e-...",
    "content": "こんにちは。ご住所を東京都新宿区…に更新しました。"
  }'

（3）3 つのステップをまとめた例です（Python、requests）：

import requests

API = "https://api.maiagent.ai/api/v1"
HEADERS = {"Authorization": "Api-Key YOUR_API_KEY"}


def on_message_webhook(payload: dict) -> None:
    conv = payload["conversation"]
    if conv["auto_reply_enabled"]:
        return  # Agent が自動返信している間のトラフィックはサポートシステムに送りません
    if payload["sender"]["type"] == "contact":
        push_to_agent_console(conv["id"], payload["content"])  # 訪問者のメッセージ→自社のオペレーター画面


def reply(conversation_id: str, text: str) -> None:
    requests.post(f"{API}/messages/outgoing/", headers=HEADERS,
                  json={"conversation": conversation_id, "content": text}, timeout=10).raise_for_status()


def finish(conversation_id: str) -> None:
    requests.patch(f"{API}/conversations/{conversation_id}/return-to-ai/", headers=HEADERS, timeout=10).raise_for_status()

注意事項

• API で書き戻したオペレーターの返信は、Outgoing メッセージ Webhook でも一度送信されます（sender.type は user です）。自社システムで重複表示しないよう、メッセージの id で重複を排除してください。

• 別のメンバーに転送すると、handoff.assigned が再度送信され、assignee.id は新しい担当者になります。conversation.id で既存のセッションを更新し、チケットを重複作成しないでください。

• メッセージ Webhook と有人対応への引き継ぎ Webhook では検証方法が異なります。連携前のよくある質問 › 認証を参照してください。

イベント一覧

event	発生するタイミング	自社システムにとっての意味
handoff.requested	AI が有人対応を必要と判断し、会話が待機キューに入り、AI の返信が停止します	自社のオペレーターが引き継ぎます
handoff.assigned	会話が MaiAgent 管理画面のオペレーターメンバーに割り当てられます（管理画面での引き受け、転送、自動割り当てが対象です。転送時は再度送信されます）	すべてのオペレーターが自社システムで対応する場合、このイベントは受信しません
handoff.returned_to_ai	自社が return-to-ai を呼び出すか、メンバーが管理画面で「AI Agent に戻す」をクリックします	AI の返信が再開され、チケットをクローズできます
handoff.queue_timeout	待機タイムアウトが満了し、MaiAgent が自動的に会話を AI に戻します	AI の返信が再開しています。オペレーターがまだ対応中の場合は、アラートが必要な異常です

各イベントには GET /api/v1/conversations/{id}/events/ に対応する event_type（transfer_triggered／human_assigned／returned_to_ai／queue_timeout）があり、照合に使用できます。

各イベントは別々のバックグラウンドタスクで送信されるため、到着順序は保証されません。また、再試行で重複する場合もあります。イベントの id で重複を排除し、occurred_at で順序を判断してください。handoff.assigned は、引き継ぎがすでに開始されたことを暗黙に示すものとして扱ってください。

API で現在の状態を照会します

Webhook に加えて、現在誰が会話を処理しているかをいつでも照会できます。

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 <キー> を指定します。ID 同期 API にキーは不要で、webChatId で識別します。

• MaiAgent から自社に送信する場合：メッセージ Webhook には、設定した固定ヘッダー X-Webhook-Secret が付与されます。有人対応への引き継ぎ Webhook には、元の request body に対して計算した HMAC-SHA256 署名 X-MaiAgent-Signature-256: sha256=<hex> が付与されます。

タイムアウト、再試行、レート制限

方向	タイムアウト	リトライ
お客様からの POST /messages/ 呼び出し	同期で 201 を返します。クライアントのタイムアウトは 10 秒を推奨します	4xx の場合はまずリクエストを修正します。5xx またはタイムアウトの場合は結果が不明なため、すぐに再送せず、先に記録を照合してください
メッセージ Webhook（MaiAgent → お客様）	30 秒	リトライしません。まずメッセージを永続化してから 2xx を返し、メッセージの id で重複を排除してください
有人対応への引き継ぎ Webhook（MaiAgent → お客様）	10 秒	失敗時は 60 秒ごとに最大 3 回リトライします。イベントの id で重複を排除してください

POST /messages/ は冪等性を保証しません。サーバーでメッセージが作成されていても、通信中にレスポンスが失われる場合があります。まず会話履歴と自社の送信記録を照合して結果を確認してください。確認できないまま再送すると、重複メッセージが追加され、AI の返信が再度実行される可能性があります。

API キーごとに 1 分あたりのリクエスト上限（RPM）を設定できます。デフォルトでは制限されません。本番稼働前に想定トラフィックを連携窓口に伝え、設定を依頼してください。

送信元 IP の許可リスト

MaiAgent が Webhook を送信する際の送信元 IP は固定されています。受信側で許可リストが必要な場合は、本番環境とテスト環境の最新リストを連携窓口にお問い合わせください。MaiAgent は、お客様の受信側ドメインへの送信を制限しません。

会話セッションの対応付け

キーは連絡先の sourceId です（チャネル間での ID 重複を避けるため、{プラットフォーム}:{お客様のユーザー ID} を推奨します）。同じ sourceId で ID 同期 API を繰り返し呼び出すと、同じ contactId が返されます。作成された会話には有効期間の制限がありません。同じ会話 ID を長期間使用してコンテキストを維持することも、案件終了後に同じ連絡先の新しい会話を作成して最初から始めることもできます。

有人対応への引き継ぎの判定ロジック

判定モデルが会話の直近 N 件のメッセージを基に判断します。デフォルトのルールは、訪問者が明示的に有人対応を希望した場合、AI の対応範囲を超える質問、訪問者の感情が悪化している場合、人による確認が必要な請求・会計操作です。ルールはロール指示で自然言語により調整でき、キーワードや信頼度が低い場合の引き継ぎなどの条件を追加できます。対応時間を設定し、対応時間外に引き継ぐかどうかを決めることもできます。判定結果は handoff.requested イベントになります。

複数パートの返信とメッセージ形式

AI の返信ごとに 1 件のメッセージ Webhook を送信します（1 リクエストにつき 1 メッセージ）。バッチ送信はしません。1 件の返信に複数の添付ファイルを含めることはできます。お客様のシステムで配列形式が必要な場合は、カスタムテンプレートで要素が 1 つの配列を出力してください。標準ではテキスト（Markdown）と添付ファイル（画像／動画／音声／ファイル）をサポートします。ボタン、カード、クイック返信などのチャネル固有の形式は標準の範囲外です。キックオフ時にご要望を提示し、別途評価してください。

添付ファイルの URL と有効期間

AI の返信の添付ファイルは、カスタムテンプレートで attachment.file.url を出力します。この署名付き URL の有効期間は 1 時間です。受信後すぐにファイルを取得し、別の保存先に保存してください。訪問者がアップロードする添付ファイルは、お客様のシステムで先にダウンロード可能な URL を取得し、メッセージ送信時に attachments[] に指定してください。

エラーと使用量の確認

メッセージ Webhook の各送信のリクエスト、レスポンス、ステータスコードは、MaiAgent 管理画面の Agent ページにある Webhook タブで確認できます。会話の状態と有人対応への引き継ぎイベントは、会話 API とイベント記録 API で照会・照合できます。AI の使用量は管理画面の使用量統計で確認できます。有人対応への引き継ぎ Webhook の送信が失敗すると、MaiAgent の監視アラートが発生します。

連携チェックリスト

• 管理画面：Outgoing Webhook が設定され、AI の返信を受信できます

• 管理画面：有人対応への引き継ぎが有効です。外部の有人サポートの割り当てモードは 引き受け方式で、タイムアウトなしが選択されています

• 管理画面：有人対応への引き継ぎ Webhook が有効で、HTTPS エンドポイントに到達でき、署名検証に成功します

• お客様のシステム：sourceId ↔ contactId ↔ conversationId の対応付けが永続化されています

• お客様のシステム：handoff.requested → 案件作成と引き継ぎ案内、handoff.returned_to_ai → 案件終了、handoff.queue_timeout → アラートまたは案件終了に対応しています

• お客様のシステム：有人対応の終了時に return-to-ai を呼び出します

• 両方の Webhook エンドポイントで冪等性を確保しています。引き継ぎイベントとメッセージ送信は、それぞれの id を使用します

• シナリオ B：メッセージ Webhook に Incoming と Outgoing の両方向が追加され、auto_reply_enabled で有人対応が必要かどうかを判定します

• ネットワークで送信元 IP の許可リストが必要な場合は、MaiAgent の送信元 IP を連携窓口にお問い合わせください

関連ページ

• 有人対応への引き継ぎ Webhook イベント（API ドキュメント）：イベントの完全な仕様、署名検証、そのまま起動できる受信側のサンプル

• 有人サポートへの引き継ぎ設定（ユーザーマニュアル）：引き継ぎ条件、対応時間、割り当て設定などの管理画面の項目の操作方法

• Webhook：メッセージ送信形式、カスタムテンプレート、API による Webhook の管理

• 会話とメッセージの作成：会話の作成とメッセージ送信の手順、各項目から API ドキュメントへのリンク

• 連絡先の ID 同期とトークン更新：setup-contact-credentials の完全な仕様

• Presigned ファイルアップロード方式：添付ファイルのアップロード