建立對話與訊息

建立對話

建立一個新的對話。

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

請求方法： POST

請求標頭：

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

請求內容：

「Web Chat ID」請由「AI 助理」詳細頁面最下方取得

{
    "webChat": "String"  // Web Chat ID
}

請求範例：

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」能取得整個對話中的所有訊息，也能用於透過「對話 ID」來知道目前訊息 Webhook 是在哪一個對話內。

{
    "id": "string",                    // 對話唯一識別碼，UUID 格式
    "contact": {
        "id": "string",                // 聯絡人唯一識別碼，UUID 格式
        "name": "string",              // 聯絡人名稱
        "avatar": "string",            // 大頭貼網址
        "createdAt": "string"          // 建立時間戳記，毫秒為單位
    },
    "inbox": {
        "id": "string",                // 收件匣唯一識別碼，UUID 格式
        "name": "string",              // 收件匣名稱
        "channelType": "string"        // 頻道類型，例如："web"
    },
    "title": "string",                 // 對話標題
    "lastMessage": null,               // 最後一則訊息，可能為 null
    "lastMessageCreatedAt": "string",  // 最後一則訊息建立時間戳記
    "unreadMessagesCount": number,     // 未讀訊息數量
    "autoReplyEnabled": boolean,       // 是否啟用自動回覆
    "isAutoReplyNow": boolean,         // 目前是否正在自動回覆
    "lastReadAt": null,                // 最後讀取時間，可能為 null
    "createdAt": "string"              // 對話建立時間戳記
}

---

傳送訊息

建立一則新訊息

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

請求方法： POST

請求標頭：

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

請求內容：

{
    "conversation": "string",   // 對話 ID，必填
    "content": "string",        // 訊息內容，必填
    "attachments": [            // 附件陣列，選填
        // 附件物件列表
    ]
}

請求參數說明：

參數名稱	類型	必填	說明
conversation	string	是	對話的唯一識別碼
content	string	是	要發送的訊息內容
attachments	array	否	附件陣列，預設為空陣列 []

附件物件欄位說明

附件欄位名稱	類型	必填	說明
id	string	是	附件的唯一識別碼
type	string	是	附件的類型
filename	string	是	附件的檔案名稱
file	string	是	附件的URL

請求範例：

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"
        }
    ]
}'

回應格式：

收到回應代表訊息建立成功，回覆的訊息會以 Webhook 的方式提供，請參考 Webhook 章節

{
    "id": "string",                    // 訊息唯一識別碼，UUID 格式
    "conversation": "string",          // 對話唯一識別碼，UUID 格式
    "sender": {
        "id": number,                  // 發送者 ID
        "name": "string",              // 發送者名稱
        "avatar": "string"             // 發送者頭像 URL
    },
    "type": "string",                  // 訊息類型，例如："incoming"
    "content": "string",               // 訊息內容
    "feedback": null,                  // 訊息回饋，可能為 null
    "createdAt": "string",             // 建立時間戳記，毫秒為單位
    "attachments": [],                 // 附件陣列
    "citations": [],                   // 引用來源陣列
    "citationNodes": []                // 引用節點陣列
}

回應範例：

{
    "id": "2491074a-6d23-4289-af45-caa12531420e",
    "conversation": "8e44604a-8278-4c96-96b5-3e5a0548d738",
    "sender": {
        "id": 324816370485542537671391323877394598747,
        "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": []
}

回應欄位說明

欄位名稱	類型	說明
id	string	訊息唯一識別碼 (UUID)
conversation	string	對話唯一識別碼 (UUID)
sender	object	發送者資訊物件
sender.id	number	發送者唯一識別碼
sender.name	string	發送者名稱
sender.avatar	string	發送者頭像網址
type	string	訊息類型 (incoming/outgoing)
content	string	訊息內容
feedback	object	null
createdAt	string	訊息建立時間戳記
attachments	array	附件清單
citations	array	引用來源文件列表
citationNodes	array	引用來源節點列表

訊息類型說明

• incoming: 收到的訊息

• outgoing: 發送的訊息