# Webhook

需要 `開發者`提供一個 API 端點，用於接收和處理傳入的 webhook 請求。MaiAgent 在串接方建立訊息後，會將 AI 助理的回覆回傳給此 Webhook 端點

**Webhook 流程：**

```mermaid
sequenceDiagram
    participant C as 開發者
    participant M as MaiAgent
    
    C->>M: 呼叫 MaiAgent 建立訊息 API
    M->>C: 回傳收到(不包含訊息回覆結果)
    Note right of M: AI助理
    M->>C: Webhook 呼叫開發者提供的 API 通知回覆結果(JSON 格式)
```

**端點：** `https://<your-api-domain>/maiagent/webhook` (由開發者自行設計)

**請求方法：** `POST`

### 請求格式

```json
{
    "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](http://sender.id/)     | string | 是      | 發送者 ID            |
| [sender.name](http://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 | 是  | 檔案創建時間戳（毫秒）    |

### 請求範例

```bash
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 的機制

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


---

# Agent Instructions: 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:

```
GET https://docs.maiagent.ai/tech/api-integration/webhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.