Webhook

需要 開發者提供一個 API 端點，用於接收和處理傳入的 webhook 請求。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

響應格式

成功響應

請回傳 200，讓 MaiAgent 知道 Webhook 成功，否則將啟動 MaiAgent Retry Webhook 的機制

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