Webhook

開発者は、受信した Webhook リクエストを受け取り処理するための API エンドポイントを用意する必要があります。MaiAgent は連携側でメッセージが作成された後、AI アシスタントの回答をこの Webhook エンドポイントへ返送します。

Webhook のフロー：

エンドポイント： https://<your-api-domain>/maiagent/webhook （開発者が自身で設計します）

リクエストメソッド： POST

リクエスト形式

{
    "id": "string",
    "conversation": "string",
    "sender": {
        "id": "number",
        "name": "string",
        "avatar": "string"
    },
    "type": "string",
    "content": "string",
    "feedback": "null | object",
    "created_at": "string",
    "attachments": "array",
    "citations": "array"
}

リクエストパラメータの説明

パラメータ	型	必須	説明
id	string	はい	メッセージの一意な識別子（UUID 形式）
conversation	string	はい	会話の識別子
sender	object	はい	送信者の情報
sender.id	string	はい	送信者 ID
sender.name	string	はい	送信者のユーザー ID
sender.avatar	string	はい	送信者のアバター URL
type	string	はい	メッセージの種類（例：outgoing）
content	string	はい	メッセージの内容
feedback	null	object	いいえ
createdAt	string	はい	メッセージ作成のタイムスタンプ（ミリ秒）
attachments	array	はい	添付ファイルの一覧
citations	array	はい	引用ファイルの一覧

Citations オブジェクトのパラメータ

パラメータ	型	必須	説明
id	string	はい	ファイルの一意な識別子
filename	string	はい	ファイル名
file	string	はい	ファイル URL
fileType	string	はい	ファイルの種類（例：jsonl）
size	number	はい	ファイルサイズ（バイト）
status	string	はい	ファイルの状態
document	string	はい	ドキュメントの識別子
createdAt	string	はい	ファイル作成のタイムスタンプ（ミリ秒）

リクエスト例

curl -X POST \\
  -H "Content-Type: application/json" \\
  -d '{
    "id": "msg123",
    "conversation": "conv456",
    "sender": {
        "id": 789,
        "name": "テストユーザー",
        "avatar": "<https://example.com/avatar.jpg>"
    },
    "type": "outgoing",
    "content": "これは webhook のテストメッセージです",
    "feedback": null,
    "created_at": "1728219442000",
    "attachments": [],
    "citations": []
  }' \\
  https://<your-api-domain>/maiagent/webhook

レスポンス形式

成功レスポンス

Webhook が正常に受信されたことを MaiAgent に伝えるため、200 を返してください。返さない場合、MaiAgent の Webhook 再試行（Retry）の仕組みが起動します。

{
    "message": "Webhook 接收成功"
}