有人対応引き継ぎ Webhook イベント

有人対応への引き継ぎのアサインが完了すると、MaiAgent は Webhook で handoff.created イベントを指定のシステムエンドポイントにプッシュします。本ページではイベント形式、署名検証、リトライ動作について説明します

カスタマーサポートポータル（受信トレイ）で「有人対応への引き継ぎ」のアサインが完了すると、MaiAgent は HTTPS POST で handoff.created イベントを設定したエンドポイントにプッシュします。これにより、ポーリング不要でディスパッチ、アラート、CRM システムが自動的に引き継げます。

有効化の方法

お客様の管理者または連携担当者が管理画面でセルフサービスで設定でき、エンジニアの支援は不要です：

管理画面 → 設定 → 受信トレイ → 受信トレイを選択 → 「有人対応への引き継ぎ」タブ → 「通知」タブ
「Webhook 通知（システム連携）」スイッチをオンにし、受信側の URL を入力します（https:// で始まる URL のみ受け付けます）
（任意ですが推奨）署名シークレットを入力し、送信元検証を有効にします（下記「署名検証」を参照）

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

イベント形式

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

{
  "event": "handoff.created",
  "conversationId": "6c2b7c1e-...",
  "inboxId": "0f9a3d42-...",
  "organizationId": "b1d20c77-...",
  "assigneeId": "3e8f5a90-...",
  "contactId": "a4c1f6b3-...",
  "conversationUrl": "https://admin.maiagent.ai/..."
}

フィールド

型

説明

event

string

常に handoff.created

conversationId

string (uuid)

会話の識別子

inboxId

string (uuid)

受信トレイの識別子

organizationId

string (uuid)

組織の識別子

assigneeId

string (uuid) | null

アサインされた担当者のメンバー識別子

contactId

string (uuid) | null

顧客（連絡先）の識別子

conversationUrl

string (uri)

管理画面の会話ページへのリンク

Payload には識別情報と管理画面へのリンクのみが含まれ、会話のテキスト内容は含まれません。会話内容が必要な場合は、識別子を使って会話とメッセージの API を呼び出して取得してください。

署名検証（有効化を推奨）

管理画面で署名シークレットを設定すると、プッシュのたびに次のヘッダーが付与されます：

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

値は、シークレットを鍵として リクエストボディの生バイト列 に対して計算した HMAC-SHA256 の 16 進ダイジェストです。検証には必ず受信した生バイト列をそのまま使用し、パースしてから再シリアライズしないでください（フィールドの順序や空白の違いでダイジェストが一致しなくなります）。

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)

シークレットは write-only です。保存後は表示されず、管理画面には「設定済み」とのみ表示されます。フィールドを空のまま保存すると既存のシークレットが維持されます。変更する場合は新しい値を直接入力し、削除する場合は「シークレットをクリア」操作を使用してください。シークレットが未設定の場合、プッシュに署名ヘッダーは付与されません。

レスポンスとリトライ

受信側は 10 秒以内に 2xx ステータスコードで応答してください。レスポンスの内容は問いません。
タイムアウト、接続失敗、または 2xx 以外のレスポンスの場合、システムは自動的にリトライします（最大 3 回、間隔 60 秒）。リトライで送信される内容は元のプッシュと完全に同一のため、受信側で冪等に処理してください（例：conversationId で重複排除）。
Webhook のプッシュが失敗しても、有人対応への引き継ぎのメインフローには影響せず、通知センターと Email 通知にも影響しません。

前へステータスコード

次へAI アシスタント

最終更新 5 日前

役に立ちましたか？