建立對話與訊息

以 API 建立對話、送出訊息，再由 Webhook 接收 Agent 回覆的串接流程；欄位定義見 API 文件。

以 API 串接對話分兩步：先建立對話取得對話 ID，再對這個對話送出訊息；Agent 的回覆會以 Webhook 推送給您。本頁說明流程與注意事項，每個欄位的型別與必填規則以 API 文件為準。

建立對話

建立一個新的對話。

端點： https://api.maiagent.ai/api/v1/conversations/

請求方法： POST

請求標頭：

Authorization: Api-Key <您的API金鑰>
Content-Type: application/json

請求內容：

必填 webChat（Web Chat ID：在後台客服對話 → 對話平台 → 編輯該 Agent 的 API 平台 → 串接與登入 → Webhook 設定最下方的 API 資訊卡複製，見使用者手冊對話平台基本設定；也可用 GET /api/v1/web-chats/ 取得）。要讓對話歸屬某位訪客時，另帶 contact（聯絡人 ID，須屬於同一個對話平台，取得方式見聯絡人身分同步與 Token 更新）；不帶 contact 時，對話的聯絡人是 API 金鑰所屬的使用者，用同一把金鑰建立的對話都會歸在這位聯絡人底下。欄位定義見 API 文件建立新的對話。

請求範例：

import requests

response = requests.post(
    url='https://api.maiagent.ai/api/v1/conversations/',
    headers={
        'Authorization': 'Api-Key <您的API金鑰>'
    },
    json={
        'webChat': '您的 Web Chat ID'
    }
)

回應內容：

串接訊息時，記下回應中的 id（對話 ID）即可：取得對話中的所有訊息、辨識訊息 Webhook 屬於哪一個對話，都用這個 ID。設定 Webhook 需要的對話平台 ID 在 inbox.id。回應欄位見 API 文件建立新的對話。

傳送訊息

建立一則新訊息

端點： https://api.maiagent.ai/api/v1/messages/

請求方法： POST

請求標頭：

Authorization: Api-Key 您的API金鑰
Content-Type: application/json

請求內容：

必填 conversation（對話 ID）；訊息文字放在 content，附件放在 attachments（預設為空陣列）。欄位定義見 API 文件發送訊息 (建立)。

附件物件要先建立再帶入，建立方式見 Presigned 檔案上傳模式：建立訊息附件；把建立附件時回應的物件（type、filename、file）原樣放進 attachments。

請求範例：

Python 範例

import requests

response = requests.post(
    url='https://api.maiagent.ai/api/v1/messages/',
    headers={
        'Authorization': 'Api-Key 您的API金鑰'
    },
    json={
        'conversation': '對話ID',
        'content': '訊息內容',
        'attachments': [
            {
                "id": "附件ID",
                "type": "附件類型",
                "filename": "附件檔案名稱",
                "file": "附件檔案的 URL"
            }
        ]
    }
)

cURL 範例

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": [
        {
            "id": "附件ID",
            "type": "附件類型",
            "filename": "附件檔案名稱",
            "file": "附件檔案的 URL"
        }
    ]
}'

回應格式：

收到回應代表訊息建立成功，回應內容是剛建立的這則訊息，不含 Agent 的回覆；回覆會以 Webhook 推送，見 Webhook。回應欄位見 API 文件發送訊息 (建立)。

回應範例：

{
    "id": "2491074a-6d23-4289-af45-caa12531420e",
    "conversation": "8e44604a-8278-4c96-96b5-3e5a0548d738",
    "sender": {
        "id": "f45d5b80-d44a-416e-885a-d720e2f7cb5b",
        "name": "AI 智能客服",
        "avatar": "https://whizchat-media-prod-django.playma.app/media/users/user/bb5f49ef-31ae-4ccf-bc0e-6fe8c5001721.png"
    },
    "type": "incoming",
    "content": "你好",
    "feedback": null,
    "createdAt": "1732495353000",
    "attachments": [],
    "citations": [],
    "citationNodes": []
}

訊息類型說明

incoming: 收到的訊息
outgoing: 發送的訊息

訊息內容中的圖片

content 是純文字，平台原樣儲存、不解析其中的網址。要在對話中呈現圖片有兩種方式：

方式

適用

說明

attachments

使用者上傳圖片給 Agent 辨識、以檔案形式保存

平台負責儲存與到期管理，是支援的正式做法；建立方式見 Presigned 檔案上傳模式

Markdown 圖片語法 ![說明](https://…)

Agent 回覆或工具結果要「顯示」一張外部圖片

Web Chat 與 MaiGPT 以 Markdown 渲染訊息，瀏覽器會直接向該網址抓圖，網址（含查詢字串）原樣保留

使用 Markdown 圖片時要注意：

圖片由使用者的瀏覽器載入，網址必須可從公網不經認證存取；平台不會代為下載或轉存。
帶簽章且會到期的網址（例如 Azure SAS、S3 presigned）寫進訊息後不會更新，到期後舊訊息裡的圖片就無法顯示。需要長期可看時，請提供不會過期的網址，或由您的系統提供固定網址再轉導。
請用 Markdown 語法，不要依賴 HTML 標籤；HTML 的處理方式依前端渲染器而定，不在契約內。
回應中引用節點的 imageUrl 是知識庫段落的圖片，與訊息內容的圖片無關。
自訂 API 工具回傳圖片網址時的兩段式流程，見 API 工具工程指南：回應怎麼回給模型。

訊息回饋

訊息回應中的 feedback 是唯讀欄位：沒有回饋時為 null，有回饋時是物件 {"id": "…", "type": "like", "suggestion": "…", "updatedAt": "…"}。建立訊息的請求不接受 feedback，要對一則 AI 回覆按讚或倒讚，用獨立的端點：

POST /api/v1/messages/{messagePk}/feedback/
Authorization: Api-Key <您的API金鑰>
Content-Type: application/json

{"type": "dislike", "suggestion": "答案沒有提到退貨期限"}

type 必填，只接受 like 或 dislike；suggestion 選填，可為空字串。
修改用 PATCH /api/v1/messages/{messagePk}/feedback/{id}/，取消用 DELETE，{id} 是回饋物件的 id。
回饋會出現在 AgentOps 的對話記錄中，欄位見 API 文件建立訊息回饋。

刪除對話

DELETE /api/v1/conversations/{id}/ 刪除一般對話，成功回 204。這是軟刪除：對話從列表與查詢中消失、無法再延續，平台保留資料供稽核。需要同時清掉對話附件的檔案時，請另外呼叫對話附件管理 API。見 API 文件刪除對話。

引用節點的頁碼欄位

Agent 回覆的 citationNodes[] 每筆帶一個 chatbotTextNode（被引用的段落），其中的頁碼欄位：

欄位

意思

pageStart、pageEnd

這個段落在來源文件中的起訖頁，從 1 起算；段落沒有跨頁時兩者相同

pageNumber

等於 pageStart，為相容舊串接而保留

只有解析器能對應到真實頁面的文件（主要是 PDF，以及以 PDF 方式解析的 Office 文件）才有頁碼；.txt、.md、CSV／Excel、HTML、爬蟲匯入的網頁、音訊逐字稿等沒有分頁的來源，這三個欄位都是 null（欄位仍會出現，不是省略）。顯示引用時請先判斷 null 再組「第 N 頁」的文字或帶 #page=N 的檔案連結。知識庫檢索 API 回傳的段落使用相同的欄位與規則。

上一頁API 共通規範

下一頁對話與訊息回覆（串流/同步）

最後更新於 1 天前

這有幫助嗎？