對話與訊息

發送訊息 (串流)

POST /api/v1/chatbots/{chatbotId}/completions/

參數

參數名稱	必填	類型	說明
chatbotId	✅	string

請求內容

請求參數

欄位	類型	必填	說明
conversation	string (uuid)	否	對話的唯一識別碼，如果為空則會建立新對話（可選）
message	object (含 7 個屬性: content, contentPayload, queryMetadata...)	是	要發送的訊息內容
message.content	string	是	訊息的文字內容
message.contentPayload	object	否	訊息的額外內容負載，JSON 格式（可選）
message.queryMetadata	object	否	查詢元數據，JSON 格式（可選）
message.metadata	object	否	訊息的環境元數據，例如時區等資訊，JSON 格式（可選）
message.attachments	array[AttachmentInput]	否	訊息的附件列表（可選）
message.toolIds	array[string]	否	本次訊息指定啟用的工具 ID 列表（可選）
message.sender	string (uuid)	否	發送者的 Contact ID（可選）
isStreaming	boolean	否	是否使用串流模式回應，預設為 false（可選）
waitForAttachments	boolean	否	是否等待附件處理完成後再進入 agent workflow，預設為 true（可選）

請求結構範例

{
  "conversation"?: string (uuid) // 對話的唯一識別碼，如果為空則會建立新對話（可選） (非必填)
  "message":  // 要發送的訊息內容
  {
    "content": string // 訊息的文字內容
    "contentPayload"?: object // 訊息的額外內容負載，JSON 格式（可選） (非必填)
    "queryMetadata"?: object // 查詢元數據，JSON 格式（可選） (非必填)
    "metadata"?: object // 訊息的環境元數據，例如時區等資訊，JSON 格式（可選） (非必填)
    "attachments"?: [ // 訊息的附件列表（可選） (非必填)
      {
        "id": string (uuid) // 附件的唯一識別碼
        "type":  // 附件類型，可選值：image（圖片）、video（影片，開發中，尚未支援）、audio（音訊）、sticker（貼圖，開發中，尚未支援）、other（其他）

* `image` - Image
* `video` - Video
* `audio` - Audio
* `sticker` - Sticker
* `other` - Other
        {
        }
        "filename": string // 附件的檔案名稱
        "file": string (uri) // 附件檔案的 URL 位址
      }
    ]
    "toolIds"?: [ // 本次訊息指定啟用的工具 ID 列表（可選） (非必填)
      string (uuid)
    ]
    "sender"?: string (uuid) // 發送者的 Contact ID（可選） (非必填)
  }
  "isStreaming"?: boolean // 是否使用串流模式回應，預設為 false（可選） (非必填)
  "waitForAttachments"?: boolean // 是否等待附件處理完成後再進入 agent workflow，預設為 true（可選） (非必填)
}

請求範例值

{
  "message": {
    "content": "你好，請介紹一下你自己"
  },
  "is_streaming": true
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "content": "你好，請介紹一下你自己"
    },
    "is_streaming": true
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
200	對話回應內容，若是串流則為事件流
400	請求參數錯誤，可能原因包括：Contact ID 不屬於該組織

---

發送訊息 (建立)

POST /api/v1/messages/

請求內容

請求參數

欄位	類型	必填	說明
conversation	string (uuid)	是
type	string	否
content	string	否
contentPayload	object	否
attachments	array[AttachmentCreateInput]	否
canvas	object	否
canvas.name	string	是
canvas.canvasType	object	是
canvas.title	string	是
canvas.content	string	是
queryMetadata	object	否
metadata	object	否	訊息的元數據，例如時區等環境資訊
broadcast	boolean	否
skipCopilotTrigger	boolean	否
suggestedForId	string (uuid)	否
skillIds	array[string]	否	Per-message selected skill IDs from the WebChat client (camelCase: skillIds).
toolIds	array[string]	否	Per-message selected tool IDs from the WebChat client (camelCase: toolIds).

請求結構範例

{
  "conversation": string (uuid)
  "type"?: string // 非必填
  "content"?: string // 非必填
  "contentPayload"?: object // 非必填
  "attachments"?: [ // 非必填
    {
      "type"?:  // 非必填
      {
      }
      "filename": string
      "file": string (uri)
      "conversation"?: string (uuid) // 非必填
    }
  ]
  "canvas"?: { // 非必填
  {
    "name": string
    "canvasType": 
    {
    }
    "title": string
    "content": string
  }
  }
  "queryMetadata"?: object // 非必填
  "metadata"?: object // 訊息的元數據，例如時區等環境資訊 (非必填)
  "broadcast"?: boolean // 非必填
  "skipCopilotTrigger"?: boolean // 非必填
  "suggestedForId"?: string (uuid) // 非必填
  "skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (非必填)
    string (uuid)
  ]
  "toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (非必填)
    string (uuid)
  ]
}

請求範例值

{
  "conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
  "sender": {
    "id": 2.992461161002561e+38,
    "name": "jessiekuo",
    "avatar": "https://media-dev.maiagent.ai/static/images/default-user-avatar.png"
  },
  "type": "incoming",
  "content": "這是一條測試訊息",
  "contentPayload": {
    "content": "這是一條測試訊息",
    "items": [
      {
        "type": "text",
        "text": "這是一條測試訊息",
        "startTimestamp": null,
        "citations": []
      }
    ],
    "metadata": null
  },
  "feedback": "like",
  "createdAt": "1748314926000",
  "attachments": [],
  "citations": [],
  "citationNodes": [],
  "canvas": {
    "id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
    "name": "system-architecture-diagram",
    "canvasType": "markdown",
    "title": "系統架構圖",
    "content": "```mermaid\ngraph TD\n    A[用戶] --> B[前端界面]\n    B --> C[API層]\n    C --> D[數據庫]\n```",
    "createdAt": "1748314926000"
  }
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/messages/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
    "sender": {
      "id": 2.992461161002561e+38,
      "name": "jessiekuo",
      "avatar": "https://media-dev.maiagent.ai/static/images/default-user-avatar.png"
    },
    "type": "incoming",
    "content": "這是一條測試訊息",
    "contentPayload": {
      "content": "這是一條測試訊息",
      "items": [
        {
          "type": "text",
          "text": "這是一條測試訊息",
          "startTimestamp": null,
          "citations": []
        }
      ],
      "metadata": null
    },
    "feedback": "like",
    "createdAt": "1748314926000",
    "attachments": [],
    "citations": [],
    "citationNodes": [],
    "canvas": {
      "id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
      "name": "system-architecture-diagram",
      "canvasType": "markdown",
      "title": "系統架構圖",
      "content": "```mermaid\ngraph TD\n    A[用戶] --> B[前端界面]\n    B --> C[API層]\n    C --> D[數據庫]\n```",
      "createdAt": "1748314926000"
    }
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "conversation": string (uuid)
  "sender": 
  {
    "id": string (uuid)
    "name": string
    "avatar": string
    "email"?: string (email) // 非必填
    "phoneNumber"?: string // 非必填
  }
  "type"?: string // 非必填
  "content"?: string // 非必填
  "contentPayload"?: object // 非必填
  "feedback": 
  {
    "id": string (uuid)
    "type": 
    {
    }
    "suggestion"?: string // 非必填
    "updatedAt": string (timestamp)
  }
  "createdAt": string (timestamp)
  "attachments"?: [ // 非必填
    {
      "id": string (uuid)
      "type"?:  // 非必填
      {
      }
      "filename": string
      "file": string (uri)
      "conversation"?: string (uuid) // 非必填
    }
  ]
  "citations": [
    {
      "id": string (uuid)
      "filename": string // 檔案名稱
      "file": string (uri) // 要上傳的檔案
      "fileType": string
      "knowledgeBase"?:  // 非必填
      {
        "id": string (uuid)
        "name": string
      }
      "size": integer
      "status": 
      {
      }
      "parser": {
      {
        "id": string (uuid)
        "name": string
        "provider": 
        {
        }
        "order"?: integer // 非必填
        "supportsDiarization": boolean
        "isTimestampSttProvider": boolean
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "speakerLabels": [
        {
          "id": string (uuid)
          "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
          "customName"?: string // User-defined speaker name (e.g., John) (非必填)
          "displayName": string
        }
      ]
      "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
      "chunksCount": integer // Number of chunks/nodes generated from this file
      "waitingTime": number (double)
      "processingTime": number (double)
      "processingTimeDetails": object
      "createdAt": string (timestamp)
    }
  ]
  "citationNodes": [
    {
      "chatbotTextNode": {
      {
        "id": string (uuid)
        "charactersCount": integer
        "hitsCount": integer
        "text": string
        "updatedAt": string (timestamp)
        "filename": string
        "chatbotFile": object // 返回 ChatbotFile 的完整資訊，包含檔案 URL 和類型，以支援前端圖片預覽
        "knowledgeBaseFile": object // 與 get_chatbot_file 相同，提供向後兼容
        "pageNumber": integer
        "citationTitle": string // 用於 inline citation hover card 顯示的來源標題
        "citationDescription": string // 用於 inline citation hover card 顯示的來源描述
        "citationQuote": string // 用於 inline citation hover card 顯示的引用文字片段
        "hasImage": boolean // 判斷是否包含圖片（檢查檔案類型或 text 中的 Markdown 圖片）
        "imageUrl": string // 提取圖片 URL（優先使用檔案 URL，否則從 Markdown 提取）
        "displayText": string // 返回移除圖片 Markdown 標記的完整文字
        "displayTitle": string // 返回顯示標題（fallback: citation_title -> filename）
        "highlightedText": string // Return text with matched terms wrapped in ``<mark>`` tags.

Priority:
1. ES/OpenSearch native highlight (set by retrieve_api via ``_es_highlighted_text``)
2. Python regex fallback (keyword-based, works for all backends)
        "labels": [
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "rawUserDefineMetadata"?: object // 使用者可以自行定義 metadata 的 key 和 value (非必填)
      }
      }
      "score"?: number (double) // 非必填
      "displayScore": integer
      "citationNumber"?: integer // Citation編號，對應回應內容中的 [1], [2] 等標記 (非必填)
      "highlightedText"?: string // ES/OpenSearch highlight result with <mark> tags (非必填)
    }
  ]
  "canvas"?: { // 非必填
  {
    "id": string (uuid)
    "name": string
    "canvasType": 
    {
    }
    "title": string
    "content": string
    "createdAt": string (timestamp)
  }
  }
  "queryMetadata"?: object // 非必填
  "metadata"?: object // 訊息的元數據，例如時區等環境資訊 (非必填)
  "recordId": string // 返回 Message 對應的 ChatbotRecord ID

Note:
    對於未儲存的 Message（如 streaming 中的虛擬 Message），直接返回 None，
    避免觸發 OneToOneField reverse relation 的 DB 查詢（N+1 問題）。
  "broadcast"?: boolean // 非必填
  "skipCopilotTrigger"?: boolean // 非必填
  "activeRevisionNumber": integer
  "revisions": [
    {
      "id": string (uuid)
      "revisionNumber": integer
      "content": string
      "contentPayload": object
      "isActive": boolean
      "createdAt": string (timestamp)
    }
  ]
  "suggestedForId"?: string (uuid) // 非必填
  "suggestionStatus": string
  "suggestionTriggerSource": string
  "suggestionError": string
  "retryCount": integer // How many times the LLM call was auto-retried during this message generation. Currently only Bedrock first-chunk stall triggers retry (max 1). Detailed per-attempt records live in metadata["retry_attempts"].
  "skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (非必填)
    string (uuid)
  ]
  "toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (非必填)
    string (uuid)
  ]
  "videoGeneration": object // Return the latest GeneratedVideo state for FE reload recovery;
``errorMessage`` is blank to match the socket emit (raw value stays on the DB row).
}

回應範例值

{
  "conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
  "sender": {
    "id": 2.992461161002561e+38,
    "name": "jessiekuo",
    "avatar": "https://media-dev.maiagent.ai/static/images/default-user-avatar.png"
  },
  "type": "incoming",
  "content": "這是一條測試訊息",
  "contentPayload": {
    "content": "這是一條測試訊息",
    "items": [
      {
        "type": "text",
        "text": "這是一條測試訊息",
        "startTimestamp": null,
        "citations": []
      }
    ],
    "metadata": null
  },
  "feedback": "like",
  "createdAt": "1748314926000",
  "attachments": [],
  "citations": [],
  "citationNodes": [],
  "canvas": {
    "id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
    "name": "system-architecture-diagram",
    "canvasType": "markdown",
    "title": "系統架構圖",
    "content": "```mermaid\ngraph TD\n    A[用戶] --> B[前端界面]\n    B --> C[API層]\n    C --> D[數據庫]\n```",
    "createdAt": "1748314926000"
  }
}

---

發送主動訊息

POST /api/v1/messages/outgoing/

請求內容

請求參數

欄位	類型	必填	說明
conversation	string (uuid)	是
type	string	否
content	string	否
contentPayload	object	否
attachments	array[AttachmentCreateInput]	否
canvas	object	否
canvas.name	string	是
canvas.canvasType	object	是
canvas.title	string	是
canvas.content	string	是
queryMetadata	object	否
metadata	object	否	訊息的元數據，例如時區等環境資訊
broadcast	boolean	否
skipCopilotTrigger	boolean	否
suggestedForId	string (uuid)	否
skillIds	array[string]	否	Per-message selected skill IDs from the WebChat client (camelCase: skillIds).
toolIds	array[string]	否	Per-message selected tool IDs from the WebChat client (camelCase: toolIds).

請求結構範例

{
  "conversation": string (uuid)
  "type"?: string // 非必填
  "content"?: string // 非必填
  "contentPayload"?: object // 非必填
  "attachments"?: [ // 非必填
    {
      "type"?:  // 非必填
      {
      }
      "filename": string
      "file": string (uri)
      "conversation"?: string (uuid) // 非必填
    }
  ]
  "canvas"?: { // 非必填
  {
    "name": string
    "canvasType": 
    {
    }
    "title": string
    "content": string
  }
  }
  "queryMetadata"?: object // 非必填
  "metadata"?: object // 訊息的元數據，例如時區等環境資訊 (非必填)
  "broadcast"?: boolean // 非必填
  "skipCopilotTrigger"?: boolean // 非必填
  "suggestedForId"?: string (uuid) // 非必填
  "skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (非必填)
    string (uuid)
  ]
  "toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (非必填)
    string (uuid)
  ]
}

請求範例值

{
  "conversation": "550e8400-e29b-41d4-a716-446655440000",
  "type": "範例字串",
  "content": "您好！我想了解產品資訊。",
  "contentPayload": null,
  "attachments": [
    {
      "type": {},
      "filename": "document.pdf",
      "file": "https://example.com/file.jpg",
      "conversation": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "canvas": {
    "name": "範例名稱",
    "canvasType": {},
    "title": "範例名稱",
    "content": "您好！我想了解產品資訊。"
  },
  "queryMetadata": null,
  "metadata": null,
  "broadcast": true,
  "skipCopilotTrigger": true,
  "suggestedForId": "550e8400-e29b-41d4-a716-446655440000",
  "skillIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "toolIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/messages/outgoing/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": "550e8400-e29b-41d4-a716-446655440000",
    "type": "範例字串",
    "content": "您好！我想了解產品資訊。",
    "contentPayload": null,
    "attachments": [
      {
        "type": {},
        "filename": "document.pdf",
        "file": "https://example.com/file.jpg",
        "conversation": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "canvas": {
      "name": "範例名稱",
      "canvasType": {},
      "title": "範例名稱",
      "content": "您好！我想了解產品資訊。"
    },
    "queryMetadata": null,
    "metadata": null,
    "broadcast": true,
    "skipCopilotTrigger": true,
    "suggestedForId": "550e8400-e29b-41d4-a716-446655440000",
    "skillIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "toolIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "conversation": string (uuid)
  "sender": 
  {
    "id": string (uuid)
    "name": string
    "avatar": string
    "email"?: string (email) // 非必填
    "phoneNumber"?: string // 非必填
  }
  "type"?: string // 非必填
  "content"?: string // 非必填
  "contentPayload"?: object // 非必填
  "feedback": 
  {
    "id": string (uuid)
    "type": 
    {
    }
    "suggestion"?: string // 非必填
    "updatedAt": string (timestamp)
  }
  "createdAt": string (timestamp)
  "attachments"?: [ // 非必填
    {
      "id": string (uuid)
      "type"?:  // 非必填
      {
      }
      "filename": string
      "file": string (uri)
      "conversation"?: string (uuid) // 非必填
    }
  ]
  "citations": [
    {
      "id": string (uuid)
      "filename": string // 檔案名稱
      "file": string (uri) // 要上傳的檔案
      "fileType": string
      "knowledgeBase"?:  // 非必填
      {
        "id": string (uuid)
        "name": string
      }
      "size": integer
      "status": 
      {
      }
      "parser": {
      {
        "id": string (uuid)
        "name": string
        "provider": 
        {
        }
        "order"?: integer // 非必填
        "supportsDiarization": boolean
        "isTimestampSttProvider": boolean
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "speakerLabels": [
        {
          "id": string (uuid)
          "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
          "customName"?: string // User-defined speaker name (e.g., John) (非必填)
          "displayName": string
        }
      ]
      "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
      "chunksCount": integer // Number of chunks/nodes generated from this file
      "waitingTime": number (double)
      "processingTime": number (double)
      "processingTimeDetails": object
      "createdAt": string (timestamp)
    }
  ]
  "citationNodes": [
    {
      "chatbotTextNode": {
      {
        "id": string (uuid)
        "charactersCount": integer
        "hitsCount": integer
        "text": string
        "updatedAt": string (timestamp)
        "filename": string
        "chatbotFile": object // 返回 ChatbotFile 的完整資訊，包含檔案 URL 和類型，以支援前端圖片預覽
        "knowledgeBaseFile": object // 與 get_chatbot_file 相同，提供向後兼容
        "pageNumber": integer
        "citationTitle": string // 用於 inline citation hover card 顯示的來源標題
        "citationDescription": string // 用於 inline citation hover card 顯示的來源描述
        "citationQuote": string // 用於 inline citation hover card 顯示的引用文字片段
        "hasImage": boolean // 判斷是否包含圖片（檢查檔案類型或 text 中的 Markdown 圖片）
        "imageUrl": string // 提取圖片 URL（優先使用檔案 URL，否則從 Markdown 提取）
        "displayText": string // 返回移除圖片 Markdown 標記的完整文字
        "displayTitle": string // 返回顯示標題（fallback: citation_title -> filename）
        "highlightedText": string // Return text with matched terms wrapped in ``<mark>`` tags.

Priority:
1. ES/OpenSearch native highlight (set by retrieve_api via ``_es_highlighted_text``)
2. Python regex fallback (keyword-based, works for all backends)
        "labels": [
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "rawUserDefineMetadata"?: object // 使用者可以自行定義 metadata 的 key 和 value (非必填)
      }
      }
      "score"?: number (double) // 非必填
      "displayScore": integer
      "citationNumber"?: integer // Citation編號，對應回應內容中的 [1], [2] 等標記 (非必填)
      "highlightedText"?: string // ES/OpenSearch highlight result with <mark> tags (非必填)
    }
  ]
  "canvas"?: { // 非必填
  {
    "id": string (uuid)
    "name": string
    "canvasType": 
    {
    }
    "title": string
    "content": string
    "createdAt": string (timestamp)
  }
  }
  "queryMetadata"?: object // 非必填
  "metadata"?: object // 訊息的元數據，例如時區等環境資訊 (非必填)
  "recordId": string // 返回 Message 對應的 ChatbotRecord ID

Note:
    對於未儲存的 Message（如 streaming 中的虛擬 Message），直接返回 None，
    避免觸發 OneToOneField reverse relation 的 DB 查詢（N+1 問題）。
  "broadcast"?: boolean // 非必填
  "skipCopilotTrigger"?: boolean // 非必填
  "activeRevisionNumber": integer
  "revisions": [
    {
      "id": string (uuid)
      "revisionNumber": integer
      "content": string
      "contentPayload": object
      "isActive": boolean
      "createdAt": string (timestamp)
    }
  ]
  "suggestedForId"?: string (uuid) // 非必填
  "suggestionStatus": string
  "suggestionTriggerSource": string
  "suggestionError": string
  "retryCount": integer // How many times the LLM call was auto-retried during this message generation. Currently only Bedrock first-chunk stall triggers retry (max 1). Detailed per-attempt records live in metadata["retry_attempts"].
  "skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (非必填)
    string (uuid)
  ]
  "toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (非必填)
    string (uuid)
  ]
  "videoGeneration": object // Return the latest GeneratedVideo state for FE reload recovery;
``errorMessage`` is blank to match the socket emit (raw value stays on the DB row).
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "conversation": "550e8400-e29b-41d4-a716-446655440000",
  "sender": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "avatar": "回應字串",
    "email": "[e-mail]",
    "phoneNumber": "回應字串"
  },
  "type": "回應字串",
  "content": "回應字串",
  "contentPayload": null,
  "feedback": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": {},
    "suggestion": "回應字串",
    "updatedAt": "回應字串"
  },
  "createdAt": "回應字串",
  "attachments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": {},
      "filename": "回應字串",
      "file": "https://example.com/file.jpg",
      "conversation": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "citations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "filename": "回應字串",
      "file": "https://example.com/file.jpg",
      "fileType": "回應字串",
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "size": 456,
      "status": {},
      "parser": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "provider": {},
        "order": 456,
        "supportsDiarization": false,
        "isTimestampSttProvider": false
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "speakerLabels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "originalLabel": "回應字串",
          "customName": "回應字串",
          "displayName": "回應字串"
        }
      ],
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "waitingTime": 456,
      "processingTime": 456,
      "processingTimeDetails": null,
      "createdAt": "回應字串"
    }
  ],
  "citationNodes": [
    {
      "chatbotTextNode": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "charactersCount": 456,
        "hitsCount": 456,
        "text": "回應字串",
        "updatedAt": "回應字串",
        "filename": "回應字串",
        "chatbotFile": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應範例名稱",
          "description": "回應範例描述"
        },
        "knowledgeBaseFile": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應範例名稱",
          "description": "回應範例描述"
        },
        "pageNumber": 456,
        "citationTitle": "回應字串",
        "citationDescription": "回應字串",
        "citationQuote": "回應字串",
        "hasImage": false,
        "imageUrl": "回應字串",
        "displayText": "回應字串",
        "displayTitle": "回應字串",
        "highlightedText": "回應字串",
        "labels": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "回應字串"
          }
        ],
        "rawUserDefineMetadata": null
      },
      "score": 456,
      "displayScore": 456,
      "citationNumber": 456,
      "highlightedText": "回應字串"
    }
  ],
  "canvas": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "canvasType": {},
    "title": "回應字串",
    "content": "回應字串",
    "createdAt": "回應字串"
  },
  "queryMetadata": null,
  "metadata": null,
  "recordId": "回應字串",
  "broadcast": false,
  "skipCopilotTrigger": false,
  "activeRevisionNumber": 456,
  "revisions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "revisionNumber": 456,
      "content": "回應字串",
      "contentPayload": null,
      "isActive": false,
      "createdAt": "回應字串"
    }
  ],
  "suggestedForId": "550e8400-e29b-41d4-a716-446655440000",
  "suggestionStatus": "回應字串",
  "suggestionTriggerSource": "回應字串",
  "suggestionError": "回應字串",
  "retryCount": 456,
  "skillIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "toolIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "videoGeneration": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}

---

建立新的對話

POST /api/v1/conversations/

請求內容

請求參數

欄位	類型	必填	說明
webChat	string (uuid)	是
contact	string (uuid)	否
clientPlatform	object	否
workingDirectory	string	否

請求結構範例

{
  "webChat": string (uuid)
  "contact"?: string (uuid) // 非必填
  "clientPlatform"?:  // 非必填
  {
  }
  "workingDirectory"?: string // 非必填
}

請求範例值

{
  "webChat": "550e8400-e29b-41d4-a716-446655440000",
  "contact": "550e8400-e29b-41d4-a716-446655440000",
  "clientPlatform": {},
  "workingDirectory": "範例字串"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/conversations/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webChat": "550e8400-e29b-41d4-a716-446655440000",
    "contact": "550e8400-e29b-41d4-a716-446655440000",
    "clientPlatform": {},
    "workingDirectory": "範例字串"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "contact": { // 輕量級 Contact Serializer，用於 Conversation List view

只包含 List view 必要的欄位，移除 inboxes、mcp_credentials 和 api_credentials
以避免 N+1 查詢問題。email / phone_number / metadata 為 Contact 自身的純量欄位，
前端對話側欄需要顯示，無 N+1 成本。
  {
    "id": string (uuid)
    "name": string
    "avatar"?: string (uri) // 非必填
    "email"?: string (email) // 非必填
    "phoneNumber"?: string // 非必填
    "metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
    "sourceId"?: string // 非必填
    "tags": [
      {
        "id": string (uuid)
        "name": string
      }
    ]
  }
  }
  "inbox": {
  {
    "id": string (uuid)
    "name": string
    "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
    "unreadConversationsCount"?: integer // 非必填
    "signAuth"?:  // 非必填
    {
      "id": string (uuid)
      "signSource": string (uuid)
      "signParams": {
      {
        "keycloak": 
        {
          "clientId": string
          "url": string
          "realm": string
        }
        "line": 
        {
          "liffId": string
        }
        "ad": 
        {
          "saml": string
        }
      }
      }
    }
    "enableAnalysis"?: boolean // 非必填
  }
  }
  "title": string
  "lastMessage"?: { // 非必填
  {
    "id": string (uuid)
    "type"?: string // 非必填
    "content"?: string // 非必填
    "createdAt": string (timestamp)
  }
  }
  "lastMessageCreatedAt": string (timestamp)
  "unreadMessagesCount": integer
  "autoReplyEnabled": boolean
  "isAutoReplyNow": boolean
  "lastReadAt": string (timestamp)
  "createdAt": string (timestamp)
  "isGroupChat": boolean
  "enableGroupMention"?: boolean // 非必填
  "queryMetadata"?: object // 非必填
  "toolMask"?: object // 記錄每個工具的啟用/停用狀態 {tool_id: bool} (非必填)
  "connectorMask"?: object // 記錄每個連接器的啟用/停用狀態 {connector_id: bool} (非必填)
  "thinkingConfig"?: object // None=未設定(使用 chatbot 設定), {}=明確關閉, {...}=自訂覆寫 (非必填)
  "thinkingConfigSchema": object
  "effectiveThinkingConfig": object // Return the effective thinking config after applying the priority chain:
conversation override > chatbot config > LLM metadata.

This allows the frontend to display the actual thinking config in use,
even when the conversation has no explicit override.

Returns None when nothing is configured at any level, so the frontend
can distinguish "Default" (None = use model/assistant default) from
"Off" ({} = explicitly disabled). Collapsing the unconfigured case to
{} would make a fresh conversation display as Off instead of Default.
  "llm": string (uuid)
  "deepResearchStatus":  // Status of deep research for this conversation

* `not_used` - Not Used
* `started` - Started
* `running` - Running
* `completed` - Completed
* `failed` - Failed
  {
  }
  "ipAddress": string
  "ipCountryCode": string
  "ipRecordedAt": string (timestamp)
  "assignee": 
  {
    "id": string (uuid)
    "name": string
    "userId": string (uuid)
  }
  "status"?: string (enum: open, resolved, queued) // * `open` - Open
* `resolved` - Resolved
* `queued` - Queued (非必填)
  "tags": [
    {
      "id": string (uuid)
      "name": string
      "memberIds"?: [ // 非必填
        string (uuid)
      ]
    }
  ]
  "progressStatus": string
  "firstResponseAt"?: string (timestamp) // 非必填
  "queuedAt"?: string (timestamp) // 非必填
  "assignedAt"?: string (timestamp) // 非必填
  "transferReason"?: string // 非必填
  "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied)
  "satisfactionComment": string
  "satisfactionSubmittedAt": string (timestamp)
  "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision).

Reads the `latest_analysis_summary` annotation added by `setup_eager_loading`
to avoid an N+1 query. All read paths (list / retrieve / create) eager-load,
so the annotation is present; it falls back to '' only for instances built
outside `setup_eager_loading`.
  "clientPlatform":  // Client platform that created this conversation (web, desktop)

* `web` - Web
* `desktop` - Desktop
  {
  }
  "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations.
  "slideProjectId": string
  "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet``
both read this, so resolving it once avoids recomputing the keyword and
title-match logic three times per serialized conversation.
  "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses.

Reads the ``matched_message_content`` annotation added by
``ConversationViewSet._annotate_keyword_match``; no extra query.
  "matchedMessageId": string
  "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned.
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "avatar": "https://example.com/file.jpg",
    "email": "[e-mail]",
    "phoneNumber": "回應字串",
    "metadata": null,
    "sourceId": "回應字串",
    "tags": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      }
    ]
  },
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "channelType": "line",
    "unreadConversationsCount": 456,
    "signAuth": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "signSource": "550e8400-e29b-41d4-a716-446655440000",
      "signParams": {
        "keycloak": {
          "clientId": "回應字串",
          "url": "回應字串",
          "realm": "回應字串"
        },
        "line": {
          "liffId": "回應字串"
        },
        "ad": {
          "saml": "回應字串"
        }
      }
    },
    "enableAnalysis": false
  },
  "title": "回應字串",
  "lastMessage": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "回應字串",
    "content": "回應字串",
    "createdAt": "回應字串"
  },
  "lastMessageCreatedAt": "回應字串",
  "unreadMessagesCount": 456,
  "autoReplyEnabled": false,
  "isAutoReplyNow": false,
  "lastReadAt": "回應字串",
  "createdAt": "回應字串",
  "isGroupChat": false,
  "enableGroupMention": false,
  "queryMetadata": null,
  "toolMask": null,
  "connectorMask": null,
  "thinkingConfig": null,
  "thinkingConfigSchema": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "effectiveThinkingConfig": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "llm": "550e8400-e29b-41d4-a716-446655440000",
  "deepResearchStatus": {},
  "ipAddress": "回應字串",
  "ipCountryCode": "回應字串",
  "ipRecordedAt": "回應字串",
  "assignee": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "status": "open",
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "memberIds": [
        "550e8400-e29b-41d4-a716-446655440000"
      ]
    }
  ],
  "progressStatus": "回應字串",
  "firstResponseAt": "回應字串",
  "queuedAt": "回應字串",
  "assignedAt": "回應字串",
  "transferReason": "回應字串",
  "satisfactionScore": 456,
  "satisfactionComment": "回應字串",
  "satisfactionSubmittedAt": "回應字串",
  "latestAnalysisSummary": "回應字串",
  "clientPlatform": {},
  "workingDirectory": "回應字串",
  "slideProjectId": "回應字串",
  "matchedField": "回應字串",
  "matchedSnippet": "回應字串",
  "matchedMessageId": "回應字串",
  "pinnedAt": "回應字串"
}

---

取得訊息列表

GET /api/v1/messages/

參數

參數名稱	必填	類型	說明
conversation	✅	string	對話 ID
cursor	❌	string	The pagination cursor value.
pageSize	❌	integer	Number of results to return per page.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/messages/?conversation=example&cursor=example&pageSize=1" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "conversation": string (uuid)
      "sender": 
      {
        "id": string (uuid)
        "name": string
        "avatar": string
        "email"?: string (email) // 非必填
        "phoneNumber"?: string // 非必填
      }
      "type"?: string // 非必填
      "content"?: string // 非必填
      "contentPayload"?: object // 非必填
      "feedback": 
      {
        "id": string (uuid)
        "type": 
        {
        }
        "suggestion"?: string // 非必填
        "updatedAt": string (timestamp)
      }
      "createdAt": string (timestamp)
      "attachments"?: [ // 非必填
        {
          "id": string (uuid)
          "type"?:  // 非必填
          {
          }
          "filename": string
          "file": string (uri)
          "conversation"?: string (uuid) // 非必填
        }
      ]
      "citations": [
        {
          "id": string (uuid)
          "filename": string // 檔案名稱
          "file": string (uri) // 要上傳的檔案
          "fileType": string
          "knowledgeBase"?:  // 非必填
          {
            "id": string (uuid)
            "name": string
          }
          "size": integer
          "status": 
          {
          }
          "parser": {
          {
            "id": string (uuid)
            "name": string
            "provider": 
            {
            }
            "order"?: integer // 非必填
            "supportsDiarization": boolean
            "isTimestampSttProvider": boolean
          }
          }
          "labels"?: [ // 非必填
            {
              "id": string (uuid)
              "name": string
            }
          ]
          "rawUserDefineMetadata"?: object // 非必填
          "speakerLabels": [
            {
              "id": string (uuid)
              "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
              "customName"?: string // User-defined speaker name (e.g., John) (非必填)
              "displayName": string
            }
          ]
          "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
          "chunksCount": integer // Number of chunks/nodes generated from this file
          "waitingTime": number (double)
          "processingTime": number (double)
          "processingTimeDetails": object
          "createdAt": string (timestamp)
        }
      ]
      "citationNodes": [
        {
          "chatbotTextNode": {
          {
            "id": string (uuid)
            "charactersCount": integer
            "hitsCount": integer
            "text": string
            "updatedAt": string (timestamp)
            "filename": string
            "chatbotFile": object // 返回 ChatbotFile 的完整資訊，包含檔案 URL 和類型，以支援前端圖片預覽
            "knowledgeBaseFile": object // 與 get_chatbot_file 相同，提供向後兼容
            "pageNumber": integer
            "citationTitle": string // 用於 inline citation hover card 顯示的來源標題
            "citationDescription": string // 用於 inline citation hover card 顯示的來源描述
            "citationQuote": string // 用於 inline citation hover card 顯示的引用文字片段
            "hasImage": boolean // 判斷是否包含圖片（檢查檔案類型或 text 中的 Markdown 圖片）
            "imageUrl": string // 提取圖片 URL（優先使用檔案 URL，否則從 Markdown 提取）
            "displayText": string // 返回移除圖片 Markdown 標記的完整文字
            "displayTitle": string // 返回顯示標題（fallback: citation_title -> filename）
            "highlightedText": string // Return text with matched terms wrapped in ``<mark>`` tags.

Priority:
1. ES/OpenSearch native highlight (set by retrieve_api via ``_es_highlighted_text``)
2. Python regex fallback (keyword-based, works for all backends)
            "labels": [
              {
                "id": string (uuid)
                "name": string
              }
            ]
            "rawUserDefineMetadata"?: object // 使用者可以自行定義 metadata 的 key 和 value (非必填)
          }
          }
          "score"?: number (double) // 非必填
          "displayScore": integer
          "citationNumber"?: integer // Citation編號，對應回應內容中的 [1], [2] 等標記 (非必填)
          "highlightedText"?: string // ES/OpenSearch highlight result with <mark> tags (非必填)
        }
      ]
      "canvas"?: { // 非必填
      {
        "id": string (uuid)
        "name": string
        "canvasType": 
        {
        }
        "title": string
        "content": string
        "createdAt": string (timestamp)
      }
      }
      "queryMetadata"?: object // 非必填
      "metadata"?: object // 訊息的元數據，例如時區等環境資訊 (非必填)
      "recordId": string // 返回 Message 對應的 ChatbotRecord ID

Note:
    對於未儲存的 Message（如 streaming 中的虛擬 Message），直接返回 None，
    避免觸發 OneToOneField reverse relation 的 DB 查詢（N+1 問題）。
      "broadcast"?: boolean // 非必填
      "skipCopilotTrigger"?: boolean // 非必填
      "activeRevisionNumber": integer
      "revisions": [
        {
          "id": string (uuid)
          "revisionNumber": integer
          "content": string
          "contentPayload": object
          "isActive": boolean
          "createdAt": string (timestamp)
        }
      ]
      "suggestedForId"?: string (uuid) // 非必填
      "suggestionStatus": string
      "suggestionTriggerSource": string
      "suggestionError": string
      "retryCount": integer // How many times the LLM call was auto-retried during this message generation. Currently only Bedrock first-chunk stall triggers retry (max 1). Detailed per-attempt records live in metadata["retry_attempts"].
      "skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (非必填)
        string (uuid)
      ]
      "toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (非必填)
        string (uuid)
      ]
      "videoGeneration": object // Return the latest GeneratedVideo state for FE reload recovery;
``errorMessage`` is blank to match the socket emit (raw value stays on the DB row).
    }
  ]
}

回應範例值

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "conversation": "550e8400-e29b-41d4-a716-446655440000",
      "sender": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "avatar": "回應字串",
        "email": "[e-mail]",
        "phoneNumber": "回應字串"
      },
      "type": "回應字串",
      "content": "回應字串",
      "contentPayload": null,
      "feedback": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": {},
        "suggestion": "回應字串",
        "updatedAt": "回應字串"
      },
      "createdAt": "回應字串",
      "attachments": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": {},
          "filename": "回應字串",
          "file": "https://example.com/file.jpg",
          "conversation": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "citations": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "filename": "回應字串",
          "file": "https://example.com/file.jpg",
          "fileType": "回應字串",
          "knowledgeBase": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "回應字串"
          },
          "size": 456,
          "status": {},
          "parser": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "回應字串",
            "provider": {},
            "order": 456,
            "supportsDiarization": false,
            "isTimestampSttProvider": false
          },
          "labels": [
            {
              "id": "550e8400-e29b-41d4-a716-446655440000",
              "name": "回應字串"
            }
          ],
          "rawUserDefineMetadata": null,
          "speakerLabels": [
            {
              "id": "550e8400-e29b-41d4-a716-446655440000",
              "originalLabel": "回應字串",
              "customName": "回應字串",
              "displayName": "回應字串"
            }
          ],
          "vectorStorageSize": 456,
          "chunksCount": 456,
          "waitingTime": 456,
          "processingTime": 456,
          "processingTimeDetails": null,
          "createdAt": "回應字串"
        }
      ],
      "citationNodes": [
        {
          "chatbotTextNode": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "charactersCount": 456,
            "hitsCount": 456,
            "text": "回應字串",
            "updatedAt": "回應字串",
            "filename": "回應字串",
            "chatbotFile": {
              "id": "550e8400-e29b-41d4-a716-446655440000",
              "name": "回應範例名稱",
              "description": "回應範例描述"
            },
            "knowledgeBaseFile": {
              "id": "550e8400-e29b-41d4-a716-446655440000",
              "name": "回應範例名稱",
              "description": "回應範例描述"
            },
            "pageNumber": 456,
            "citationTitle": "回應字串",
            "citationDescription": "回應字串",
            "citationQuote": "回應字串",
            "hasImage": false,
            "imageUrl": "回應字串",
            "displayText": "回應字串",
            "displayTitle": "回應字串",
            "highlightedText": "回應字串",
            "labels": [
              {
                "id": "550e8400-e29b-41d4-a716-446655440000",
                "name": "回應字串"
              }
            ],
            "rawUserDefineMetadata": null
          },
          "score": 456,
          "displayScore": 456,
          "citationNumber": 456,
          "highlightedText": "回應字串"
        }
      ],
      "canvas": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "canvasType": {},
        "title": "回應字串",
        "content": "回應字串",
        "createdAt": "回應字串"
      },
      "queryMetadata": null,
      "metadata": null,
      "recordId": "回應字串",
      "broadcast": false,
      "skipCopilotTrigger": false,
      "activeRevisionNumber": 456,
      "revisions": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "revisionNumber": 456,
          "content": "回應字串",
          "contentPayload": null,
          "isActive": false,
          "createdAt": "回應字串"
        }
      ],
      "suggestedForId": "550e8400-e29b-41d4-a716-446655440000",
      "suggestionStatus": "回應字串",
      "suggestionTriggerSource": "回應字串",
      "suggestionError": "回應字串",
      "retryCount": 456,
      "skillIds": [
        "550e8400-e29b-41d4-a716-446655440000"
      ],
      "toolIds": [
        "550e8400-e29b-41d4-a716-446655440000"
      ],
      "videoGeneration": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      }
    }
  ]
}

---

取得特定訊息

GET /api/v1/messages/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this 訊息.
conversation	✅	string	對話 ID

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "conversation": string (uuid)
  "sender": 
  {
    "id": string (uuid)
    "name": string
    "avatar": string
    "email"?: string (email) // 非必填
    "phoneNumber"?: string // 非必填
  }
  "type"?: string // 非必填
  "content"?: string // 非必填
  "contentPayload"?: object // 非必填
  "feedback": 
  {
    "id": string (uuid)
    "type": 
    {
    }
    "suggestion"?: string // 非必填
    "updatedAt": string (timestamp)
  }
  "createdAt": string (timestamp)
  "attachments"?: [ // 非必填
    {
      "id": string (uuid)
      "type"?:  // 非必填
      {
      }
      "filename": string
      "file": string (uri)
      "conversation"?: string (uuid) // 非必填
    }
  ]
  "citations": [
    {
      "id": string (uuid)
      "filename": string // 檔案名稱
      "file": string (uri) // 要上傳的檔案
      "fileType": string
      "knowledgeBase"?:  // 非必填
      {
        "id": string (uuid)
        "name": string
      }
      "size": integer
      "status": 
      {
      }
      "parser": {
      {
        "id": string (uuid)
        "name": string
        "provider": 
        {
        }
        "order"?: integer // 非必填
        "supportsDiarization": boolean
        "isTimestampSttProvider": boolean
      }
      }
      "labels"?: [ // 非必填
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // 非必填
      "speakerLabels": [
        {
          "id": string (uuid)
          "originalLabel": string // Original speaker label from diarization (e.g., SPEAKER_00)
          "customName"?: string // User-defined speaker name (e.g., John) (非必填)
          "displayName": string
        }
      ]
      "vectorStorageSize": integer // Size of vectors for this file in Elasticsearch (bytes)
      "chunksCount": integer // Number of chunks/nodes generated from this file
      "waitingTime": number (double)
      "processingTime": number (double)
      "processingTimeDetails": object
      "createdAt": string (timestamp)
    }
  ]
  "citationNodes": [
    {
      "chatbotTextNode": {
      {
        "id": string (uuid)
        "charactersCount": integer
        "hitsCount": integer
        "text": string
        "updatedAt": string (timestamp)
        "filename": string
        "chatbotFile": object // 返回 ChatbotFile 的完整資訊，包含檔案 URL 和類型，以支援前端圖片預覽
        "knowledgeBaseFile": object // 與 get_chatbot_file 相同，提供向後兼容
        "pageNumber": integer
        "citationTitle": string // 用於 inline citation hover card 顯示的來源標題
        "citationDescription": string // 用於 inline citation hover card 顯示的來源描述
        "citationQuote": string // 用於 inline citation hover card 顯示的引用文字片段
        "hasImage": boolean // 判斷是否包含圖片（檢查檔案類型或 text 中的 Markdown 圖片）
        "imageUrl": string // 提取圖片 URL（優先使用檔案 URL，否則從 Markdown 提取）
        "displayText": string // 返回移除圖片 Markdown 標記的完整文字
        "displayTitle": string // 返回顯示標題（fallback: citation_title -> filename）
        "highlightedText": string // Return text with matched terms wrapped in ``<mark>`` tags.

Priority:
1. ES/OpenSearch native highlight (set by retrieve_api via ``_es_highlighted_text``)
2. Python regex fallback (keyword-based, works for all backends)
        "labels": [
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "rawUserDefineMetadata"?: object // 使用者可以自行定義 metadata 的 key 和 value (非必填)
      }
      }
      "score"?: number (double) // 非必填
      "displayScore": integer
      "citationNumber"?: integer // Citation編號，對應回應內容中的 [1], [2] 等標記 (非必填)
      "highlightedText"?: string // ES/OpenSearch highlight result with <mark> tags (非必填)
    }
  ]
  "canvas"?: { // 非必填
  {
    "id": string (uuid)
    "name": string
    "canvasType": 
    {
    }
    "title": string
    "content": string
    "createdAt": string (timestamp)
  }
  }
  "queryMetadata"?: object // 非必填
  "metadata"?: object // 訊息的元數據，例如時區等環境資訊 (非必填)
  "recordId": string // 返回 Message 對應的 ChatbotRecord ID

Note:
    對於未儲存的 Message（如 streaming 中的虛擬 Message），直接返回 None，
    避免觸發 OneToOneField reverse relation 的 DB 查詢（N+1 問題）。
  "broadcast"?: boolean // 非必填
  "skipCopilotTrigger"?: boolean // 非必填
  "activeRevisionNumber": integer
  "revisions": [
    {
      "id": string (uuid)
      "revisionNumber": integer
      "content": string
      "contentPayload": object
      "isActive": boolean
      "createdAt": string (timestamp)
    }
  ]
  "suggestedForId"?: string (uuid) // 非必填
  "suggestionStatus": string
  "suggestionTriggerSource": string
  "suggestionError": string
  "retryCount": integer // How many times the LLM call was auto-retried during this message generation. Currently only Bedrock first-chunk stall triggers retry (max 1). Detailed per-attempt records live in metadata["retry_attempts"].
  "skillIds"?: [ // Per-message selected skill IDs from the WebChat client (camelCase: skillIds). (非必填)
    string (uuid)
  ]
  "toolIds"?: [ // Per-message selected tool IDs from the WebChat client (camelCase: toolIds). (非必填)
    string (uuid)
  ]
  "videoGeneration": object // Return the latest GeneratedVideo state for FE reload recovery;
``errorMessage`` is blank to match the socket emit (raw value stays on the DB row).
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "conversation": "550e8400-e29b-41d4-a716-446655440000",
  "sender": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "avatar": "回應字串",
    "email": "[e-mail]",
    "phoneNumber": "回應字串"
  },
  "type": "回應字串",
  "content": "回應字串",
  "contentPayload": null,
  "feedback": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": {},
    "suggestion": "回應字串",
    "updatedAt": "回應字串"
  },
  "createdAt": "回應字串",
  "attachments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": {},
      "filename": "回應字串",
      "file": "https://example.com/file.jpg",
      "conversation": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "citations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "filename": "回應字串",
      "file": "https://example.com/file.jpg",
      "fileType": "回應字串",
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "size": 456,
      "status": {},
      "parser": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "provider": {},
        "order": 456,
        "supportsDiarization": false,
        "isTimestampSttProvider": false
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rawUserDefineMetadata": null,
      "speakerLabels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "originalLabel": "回應字串",
          "customName": "回應字串",
          "displayName": "回應字串"
        }
      ],
      "vectorStorageSize": 456,
      "chunksCount": 456,
      "waitingTime": 456,
      "processingTime": 456,
      "processingTimeDetails": null,
      "createdAt": "回應字串"
    }
  ],
  "citationNodes": [
    {
      "chatbotTextNode": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "charactersCount": 456,
        "hitsCount": 456,
        "text": "回應字串",
        "updatedAt": "回應字串",
        "filename": "回應字串",
        "chatbotFile": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應範例名稱",
          "description": "回應範例描述"
        },
        "knowledgeBaseFile": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應範例名稱",
          "description": "回應範例描述"
        },
        "pageNumber": 456,
        "citationTitle": "回應字串",
        "citationDescription": "回應字串",
        "citationQuote": "回應字串",
        "hasImage": false,
        "imageUrl": "回應字串",
        "displayText": "回應字串",
        "displayTitle": "回應字串",
        "highlightedText": "回應字串",
        "labels": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "回應字串"
          }
        ],
        "rawUserDefineMetadata": null
      },
      "score": 456,
      "displayScore": 456,
      "citationNumber": 456,
      "highlightedText": "回應字串"
    }
  ],
  "canvas": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "canvasType": {},
    "title": "回應字串",
    "content": "回應字串",
    "createdAt": "回應字串"
  },
  "queryMetadata": null,
  "metadata": null,
  "recordId": "回應字串",
  "broadcast": false,
  "skipCopilotTrigger": false,
  "activeRevisionNumber": 456,
  "revisions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "revisionNumber": 456,
      "content": "回應字串",
      "contentPayload": null,
      "isActive": false,
      "createdAt": "回應字串"
    }
  ],
  "suggestedForId": "550e8400-e29b-41d4-a716-446655440000",
  "suggestionStatus": "回應字串",
  "suggestionTriggerSource": "回應字串",
  "suggestionError": "回應字串",
  "retryCount": 456,
  "skillIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "toolIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "videoGeneration": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  }
}

---

取得對話列表

GET /api/v1/conversations/

參數

參數名稱	必填	類型	說明
assignee	❌	string
contact	❌	string	聯絡人 ID
contactTags	❌	array	Multiple values may be separated by commas.
cursor	❌	string	The pagination cursor value.
endDate	❌	string
externalConversationId	❌	string
externalSource	❌	string
inbox	❌	string	對話平台 ID
isPinned	❌	string
keyword	❌	string	關鍵字搜尋
mine	❌	boolean
mode	❌	string	`chat`: Chat ; `cowork`: Cowork;
pageSize	❌	integer	Number of results to return per page.
startDate	❌	string
status	❌	array	`open`: Open ; `resolved`: Resolved ; `queued`: Queued;
tags	❌	array	Multiple values may be separated by commas.
unassigned	❌	boolean
updatedAfter	❌	string

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/conversations/?assignee=550e8400-e29b-41d4-a716-446655440000&contact=example&contactTags=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=example&isPinned=example&keyword=example&mine=true&mode=chat&pageSize=1&startDate=example&status=example&tags=example&unassigned=true&updatedAfter=2026-07-06T03:41:44.674Z" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "contact": { // 輕量級 Contact Serializer，用於 Conversation List view

只包含 List view 必要的欄位，移除 inboxes、mcp_credentials 和 api_credentials
以避免 N+1 查詢問題。email / phone_number / metadata 為 Contact 自身的純量欄位，
前端對話側欄需要顯示，無 N+1 成本。
      {
        "id": string (uuid)
        "name": string
        "avatar"?: string (uri) // 非必填
        "email"?: string (email) // 非必填
        "phoneNumber"?: string // 非必填
        "metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
        "sourceId"?: string // 非必填
        "tags": [
          {
            "id": string (uuid)
            "name": string
          }
        ]
      }
      }
      "inbox": {
      {
        "id": string (uuid)
        "name": string
        "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
        "unreadConversationsCount"?: integer // 非必填
        "signAuth"?:  // 非必填
        {
          "id": string (uuid)
          "signSource": string (uuid)
          "signParams": {
          {
            "keycloak": 
            {
              "clientId": string
              "url": string
              "realm": string
            }
            "line": 
            {
              "liffId": string
            }
            "ad": 
            {
              "saml": string
            }
          }
          }
        }
        "enableAnalysis"?: boolean // 非必填
      }
      }
      "title": string
      "lastMessage"?: { // 非必填
      {
        "id": string (uuid)
        "type"?: string // 非必填
        "content"?: string // 非必填
        "createdAt": string (timestamp)
      }
      }
      "lastMessageCreatedAt": string (timestamp)
      "unreadMessagesCount": integer
      "autoReplyEnabled": boolean
      "isAutoReplyNow": boolean
      "lastReadAt": string (timestamp)
      "createdAt": string (timestamp)
      "isGroupChat": boolean
      "enableGroupMention"?: boolean // 非必填
      "queryMetadata"?: object // 非必填
      "toolMask"?: object // 記錄每個工具的啟用/停用狀態 {tool_id: bool} (非必填)
      "connectorMask"?: object // 記錄每個連接器的啟用/停用狀態 {connector_id: bool} (非必填)
      "thinkingConfig"?: object // None=未設定(使用 chatbot 設定), {}=明確關閉, {...}=自訂覆寫 (非必填)
      "thinkingConfigSchema": object
      "effectiveThinkingConfig": object // Return the effective thinking config after applying the priority chain:
conversation override > chatbot config > LLM metadata.

This allows the frontend to display the actual thinking config in use,
even when the conversation has no explicit override.

Returns None when nothing is configured at any level, so the frontend
can distinguish "Default" (None = use model/assistant default) from
"Off" ({} = explicitly disabled). Collapsing the unconfigured case to
{} would make a fresh conversation display as Off instead of Default.
      "llm": string (uuid)
      "deepResearchStatus":  // Status of deep research for this conversation

* `not_used` - Not Used
* `started` - Started
* `running` - Running
* `completed` - Completed
* `failed` - Failed
      {
      }
      "ipAddress": string
      "ipCountryCode": string
      "ipRecordedAt": string (timestamp)
      "assignee": 
      {
        "id": string (uuid)
        "name": string
        "userId": string (uuid)
      }
      "status"?: string (enum: open, resolved, queued) // * `open` - Open
* `resolved` - Resolved
* `queued` - Queued (非必填)
      "tags": [
        {
          "id": string (uuid)
          "name": string
          "memberIds"?: [ // 非必填
            string (uuid)
          ]
        }
      ]
      "progressStatus": string
      "firstResponseAt"?: string (timestamp) // 非必填
      "queuedAt"?: string (timestamp) // 非必填
      "assignedAt"?: string (timestamp) // 非必填
      "transferReason"?: string // 非必填
      "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied)
      "satisfactionComment": string
      "satisfactionSubmittedAt": string (timestamp)
      "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision).

Reads the `latest_analysis_summary` annotation added by `setup_eager_loading`
to avoid an N+1 query. All read paths (list / retrieve / create) eager-load,
so the annotation is present; it falls back to '' only for instances built
outside `setup_eager_loading`.
      "clientPlatform":  // Client platform that created this conversation (web, desktop)

* `web` - Web
* `desktop` - Desktop
      {
      }
      "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations.
      "slideProjectId": string
      "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet``
both read this, so resolving it once avoids recomputing the keyword and
title-match logic three times per serialized conversation.
      "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses.

Reads the ``matched_message_content`` annotation added by
``ConversationViewSet._annotate_keyword_match``; no extra query.
      "matchedMessageId": string
      "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned.
    }
  ]
}

回應範例值

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "contact": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "avatar": "https://example.com/file.jpg",
        "email": "[e-mail]",
        "phoneNumber": "回應字串",
        "metadata": null,
        "sourceId": "回應字串",
        "tags": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "回應字串"
          }
        ]
      },
      "inbox": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "channelType": "line",
        "unreadConversationsCount": 456,
        "signAuth": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "signSource": "550e8400-e29b-41d4-a716-446655440000",
          "signParams": {
            "keycloak": {
              "clientId": "回應字串",
              "url": "回應字串",
              "realm": "回應字串"
            },
            "line": {
              "liffId": "回應字串"
            },
            "ad": {
              "saml": "回應字串"
            }
          }
        },
        "enableAnalysis": false
      },
      "title": "回應字串",
      "lastMessage": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "回應字串",
        "content": "回應字串",
        "createdAt": "回應字串"
      },
      "lastMessageCreatedAt": "回應字串",
      "unreadMessagesCount": 456,
      "autoReplyEnabled": false,
      "isAutoReplyNow": false,
      "lastReadAt": "回應字串",
      "createdAt": "回應字串",
      "isGroupChat": false,
      "enableGroupMention": false,
      "queryMetadata": null,
      "toolMask": null,
      "connectorMask": null,
      "thinkingConfig": null,
      "thinkingConfigSchema": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      },
      "effectiveThinkingConfig": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      },
      "llm": "550e8400-e29b-41d4-a716-446655440000",
      "deepResearchStatus": {},
      "ipAddress": "回應字串",
      "ipCountryCode": "回應字串",
      "ipRecordedAt": "回應字串",
      "assignee": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "userId": "550e8400-e29b-41d4-a716-446655440000"
      },
      "status": "open",
      "tags": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "memberIds": [
            "550e8400-e29b-41d4-a716-446655440000"
          ]
        }
      ],
      "progressStatus": "回應字串",
      "firstResponseAt": "回應字串",
      "queuedAt": "回應字串",
      "assignedAt": "回應字串",
      "transferReason": "回應字串",
      "satisfactionScore": 456,
      "satisfactionComment": "回應字串",
      "satisfactionSubmittedAt": "回應字串",
      "latestAnalysisSummary": "回應字串",
      "clientPlatform": {},
      "workingDirectory": "回應字串",
      "slideProjectId": "回應字串",
      "matchedField": "回應字串",
      "matchedSnippet": "回應字串",
      "matchedMessageId": "回應字串",
      "pinnedAt": "回應字串"
    }
  ]
}

---

取得特定對話

GET /api/v1/conversations/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this 對話.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "contact": { // 輕量級 Contact Serializer，用於 Conversation List view

只包含 List view 必要的欄位，移除 inboxes、mcp_credentials 和 api_credentials
以避免 N+1 查詢問題。email / phone_number / metadata 為 Contact 自身的純量欄位，
前端對話側欄需要顯示，無 N+1 成本。
  {
    "id": string (uuid)
    "name": string
    "avatar"?: string (uri) // 非必填
    "email"?: string (email) // 非必填
    "phoneNumber"?: string // 非必填
    "metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
    "sourceId"?: string // 非必填
    "tags": [
      {
        "id": string (uuid)
        "name": string
      }
    ]
  }
  }
  "inbox": {
  {
    "id": string (uuid)
    "name": string
    "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
    "unreadConversationsCount"?: integer // 非必填
    "signAuth"?:  // 非必填
    {
      "id": string (uuid)
      "signSource": string (uuid)
      "signParams": {
      {
        "keycloak": 
        {
          "clientId": string
          "url": string
          "realm": string
        }
        "line": 
        {
          "liffId": string
        }
        "ad": 
        {
          "saml": string
        }
      }
      }
    }
    "enableAnalysis"?: boolean // 非必填
  }
  }
  "title": string
  "lastMessage"?: { // 非必填
  {
    "id": string (uuid)
    "type"?: string // 非必填
    "content"?: string // 非必填
    "createdAt": string (timestamp)
  }
  }
  "lastMessageCreatedAt": string (timestamp)
  "unreadMessagesCount": integer
  "autoReplyEnabled": boolean
  "isAutoReplyNow": boolean
  "lastReadAt": string (timestamp)
  "createdAt": string (timestamp)
  "isGroupChat": boolean
  "enableGroupMention"?: boolean // 非必填
  "queryMetadata"?: object // 非必填
  "toolMask"?: object // 記錄每個工具的啟用/停用狀態 {tool_id: bool} (非必填)
  "connectorMask"?: object // 記錄每個連接器的啟用/停用狀態 {connector_id: bool} (非必填)
  "thinkingConfig"?: object // None=未設定(使用 chatbot 設定), {}=明確關閉, {...}=自訂覆寫 (非必填)
  "thinkingConfigSchema": object
  "effectiveThinkingConfig": object // Return the effective thinking config after applying the priority chain:
conversation override > chatbot config > LLM metadata.

This allows the frontend to display the actual thinking config in use,
even when the conversation has no explicit override.

Returns None when nothing is configured at any level, so the frontend
can distinguish "Default" (None = use model/assistant default) from
"Off" ({} = explicitly disabled). Collapsing the unconfigured case to
{} would make a fresh conversation display as Off instead of Default.
  "llm": string (uuid)
  "deepResearchStatus":  // Status of deep research for this conversation

* `not_used` - Not Used
* `started` - Started
* `running` - Running
* `completed` - Completed
* `failed` - Failed
  {
  }
  "ipAddress": string
  "ipCountryCode": string
  "ipRecordedAt": string (timestamp)
  "assignee": 
  {
    "id": string (uuid)
    "name": string
    "userId": string (uuid)
  }
  "status"?: string (enum: open, resolved, queued) // * `open` - Open
* `resolved` - Resolved
* `queued` - Queued (非必填)
  "tags": [
    {
      "id": string (uuid)
      "name": string
      "memberIds"?: [ // 非必填
        string (uuid)
      ]
    }
  ]
  "progressStatus": string
  "firstResponseAt"?: string (timestamp) // 非必填
  "queuedAt"?: string (timestamp) // 非必填
  "assignedAt"?: string (timestamp) // 非必填
  "transferReason"?: string // 非必填
  "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied)
  "satisfactionComment": string
  "satisfactionSubmittedAt": string (timestamp)
  "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision).

Reads the `latest_analysis_summary` annotation added by `setup_eager_loading`
to avoid an N+1 query. All read paths (list / retrieve / create) eager-load,
so the annotation is present; it falls back to '' only for instances built
outside `setup_eager_loading`.
  "clientPlatform":  // Client platform that created this conversation (web, desktop)

* `web` - Web
* `desktop` - Desktop
  {
  }
  "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations.
  "slideProjectId": string
  "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet``
both read this, so resolving it once avoids recomputing the keyword and
title-match logic three times per serialized conversation.
  "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses.

Reads the ``matched_message_content`` annotation added by
``ConversationViewSet._annotate_keyword_match``; no extra query.
  "matchedMessageId": string
  "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned.
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "avatar": "https://example.com/file.jpg",
    "email": "[e-mail]",
    "phoneNumber": "回應字串",
    "metadata": null,
    "sourceId": "回應字串",
    "tags": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      }
    ]
  },
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "channelType": "line",
    "unreadConversationsCount": 456,
    "signAuth": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "signSource": "550e8400-e29b-41d4-a716-446655440000",
      "signParams": {
        "keycloak": {
          "clientId": "回應字串",
          "url": "回應字串",
          "realm": "回應字串"
        },
        "line": {
          "liffId": "回應字串"
        },
        "ad": {
          "saml": "回應字串"
        }
      }
    },
    "enableAnalysis": false
  },
  "title": "回應字串",
  "lastMessage": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "回應字串",
    "content": "回應字串",
    "createdAt": "回應字串"
  },
  "lastMessageCreatedAt": "回應字串",
  "unreadMessagesCount": 456,
  "autoReplyEnabled": false,
  "isAutoReplyNow": false,
  "lastReadAt": "回應字串",
  "createdAt": "回應字串",
  "isGroupChat": false,
  "enableGroupMention": false,
  "queryMetadata": null,
  "toolMask": null,
  "connectorMask": null,
  "thinkingConfig": null,
  "thinkingConfigSchema": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "effectiveThinkingConfig": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "llm": "550e8400-e29b-41d4-a716-446655440000",
  "deepResearchStatus": {},
  "ipAddress": "回應字串",
  "ipCountryCode": "回應字串",
  "ipRecordedAt": "回應字串",
  "assignee": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "status": "open",
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "memberIds": [
        "550e8400-e29b-41d4-a716-446655440000"
      ]
    }
  ],
  "progressStatus": "回應字串",
  "firstResponseAt": "回應字串",
  "queuedAt": "回應字串",
  "assignedAt": "回應字串",
  "transferReason": "回應字串",
  "satisfactionScore": 456,
  "satisfactionComment": "回應字串",
  "satisfactionSubmittedAt": "回應字串",
  "latestAnalysisSummary": "回應字串",
  "clientPlatform": {},
  "workingDirectory": "回應字串",
  "slideProjectId": "回應字串",
  "matchedField": "回應字串",
  "matchedSnippet": "回應字串",
  "matchedMessageId": "回應字串",
  "pinnedAt": "回應字串"
}

---

取得特定對話

GET /api/v1/conversations/tab-counts/

參數

參數名稱	必填	類型	說明
inbox	❌	string	Filter by inbox UUID

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/conversations/tab-counts/?inbox=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200 - Tab counts

回應結構範例

{
  "mine"?: integer // 非必填
  "unassigned"?: integer // 非必填
  "all"?: integer // 非必填
}

回應範例值

{
  "mine": 456,
  "unassigned": 456,
  "all": 456
}

---

重新命名對話

PATCH /api/v1/conversations/{id}/rename/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this 對話.

請求內容

請求參數

欄位	類型	必填	說明
title	string	否

請求結構範例

{
  "title"?: string // 非必填
}

請求範例值

{
  "title": "範例名稱"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/rename/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "範例名稱"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "contact": { // 輕量級 Contact Serializer，用於 Conversation List view

只包含 List view 必要的欄位，移除 inboxes、mcp_credentials 和 api_credentials
以避免 N+1 查詢問題。email / phone_number / metadata 為 Contact 自身的純量欄位，
前端對話側欄需要顯示，無 N+1 成本。
  {
    "id": string (uuid)
    "name": string
    "avatar"?: string (uri) // 非必填
    "email"?: string (email) // 非必填
    "phoneNumber"?: string // 非必填
    "metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
    "sourceId"?: string // 非必填
    "tags": [
      {
        "id": string (uuid)
        "name": string
      }
    ]
  }
  }
  "inbox": {
  {
    "id": string (uuid)
    "name": string
    "channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp, slack) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
    "unreadConversationsCount"?: integer // 非必填
    "signAuth"?:  // 非必填
    {
      "id": string (uuid)
      "signSource": string (uuid)
      "signParams": {
      {
        "keycloak": 
        {
          "clientId": string
          "url": string
          "realm": string
        }
        "line": 
        {
          "liffId": string
        }
        "ad": 
        {
          "saml": string
        }
      }
      }
    }
    "enableAnalysis"?: boolean // 非必填
  }
  }
  "title": string
  "lastMessage"?: { // 非必填
  {
    "id": string (uuid)
    "type"?: string // 非必填
    "content"?: string // 非必填
    "createdAt": string (timestamp)
  }
  }
  "lastMessageCreatedAt": string (timestamp)
  "unreadMessagesCount": integer
  "autoReplyEnabled": boolean
  "isAutoReplyNow": boolean
  "lastReadAt": string (timestamp)
  "createdAt": string (timestamp)
  "isGroupChat": boolean
  "enableGroupMention"?: boolean // 非必填
  "queryMetadata"?: object // 非必填
  "toolMask"?: object // 記錄每個工具的啟用/停用狀態 {tool_id: bool} (非必填)
  "connectorMask"?: object // 記錄每個連接器的啟用/停用狀態 {connector_id: bool} (非必填)
  "thinkingConfig"?: object // None=未設定(使用 chatbot 設定), {}=明確關閉, {...}=自訂覆寫 (非必填)
  "thinkingConfigSchema": object
  "effectiveThinkingConfig": object // Return the effective thinking config after applying the priority chain:
conversation override > chatbot config > LLM metadata.

This allows the frontend to display the actual thinking config in use,
even when the conversation has no explicit override.

Returns None when nothing is configured at any level, so the frontend
can distinguish "Default" (None = use model/assistant default) from
"Off" ({} = explicitly disabled). Collapsing the unconfigured case to
{} would make a fresh conversation display as Off instead of Default.
  "llm": string (uuid)
  "deepResearchStatus":  // Status of deep research for this conversation

* `not_used` - Not Used
* `started` - Started
* `running` - Running
* `completed` - Completed
* `failed` - Failed
  {
  }
  "ipAddress": string
  "ipCountryCode": string
  "ipRecordedAt": string (timestamp)
  "assignee": 
  {
    "id": string (uuid)
    "name": string
    "userId": string (uuid)
  }
  "status"?: string (enum: open, resolved, queued) // * `open` - Open
* `resolved` - Resolved
* `queued` - Queued (非必填)
  "tags": [
    {
      "id": string (uuid)
      "name": string
      "memberIds"?: [ // 非必填
        string (uuid)
      ]
    }
  ]
  "progressStatus": string
  "firstResponseAt"?: string (timestamp) // 非必填
  "queuedAt"?: string (timestamp) // 非必填
  "assignedAt"?: string (timestamp) // 非必填
  "transferReason"?: string // 非必填
  "satisfactionScore": integer // Conversation satisfaction rating on a 5-point scale (1=very dissatisfied, 5=very satisfied)
  "satisfactionComment": string
  "satisfactionSubmittedAt": string (timestamp)
  "latestAnalysisSummary": string // The conversation's current analysis summary (its active summary revision).

Reads the `latest_analysis_summary` annotation added by `setup_eager_loading`
to avoid an N+1 query. All read paths (list / retrieve / create) eager-load,
so the annotation is present; it falls back to '' only for instances built
outside `setup_eager_loading`.
  "clientPlatform":  // Client platform that created this conversation (web, desktop)

* `web` - Web
* `desktop` - Desktop
  {
  }
  "workingDirectory": string // Absolute path of the local folder bound to a desktop conversation. Only set for desktop conversations; null for web conversations.
  "slideProjectId": string
  "matchedField": string // Cached per instance: ``get_matched_message_id`` / ``get_matched_snippet``
both read this, so resolving it once avoids recomputing the keyword and
title-match logic three times per serialized conversation.
  "matchedSnippet": string // Keyword-centred excerpt of the matched message, with ellipses.

Reads the ``matched_message_content`` annotation added by
``ConversationViewSet._annotate_keyword_match``; no extra query.
  "matchedMessageId": string
  "pinnedAt": string (timestamp) // When the conversation was pinned. Null means unpinned.
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "avatar": "https://example.com/file.jpg",
    "email": "[e-mail]",
    "phoneNumber": "回應字串",
    "metadata": null,
    "sourceId": "回應字串",
    "tags": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      }
    ]
  },
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "channelType": "line",
    "unreadConversationsCount": 456,
    "signAuth": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "signSource": "550e8400-e29b-41d4-a716-446655440000",
      "signParams": {
        "keycloak": {
          "clientId": "回應字串",
          "url": "回應字串",
          "realm": "回應字串"
        },
        "line": {
          "liffId": "回應字串"
        },
        "ad": {
          "saml": "回應字串"
        }
      }
    },
    "enableAnalysis": false
  },
  "title": "回應字串",
  "lastMessage": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "回應字串",
    "content": "回應字串",
    "createdAt": "回應字串"
  },
  "lastMessageCreatedAt": "回應字串",
  "unreadMessagesCount": 456,
  "autoReplyEnabled": false,
  "isAutoReplyNow": false,
  "lastReadAt": "回應字串",
  "createdAt": "回應字串",
  "isGroupChat": false,
  "enableGroupMention": false,
  "queryMetadata": null,
  "toolMask": null,
  "connectorMask": null,
  "thinkingConfig": null,
  "thinkingConfigSchema": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "effectiveThinkingConfig": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "llm": "550e8400-e29b-41d4-a716-446655440000",
  "deepResearchStatus": {},
  "ipAddress": "回應字串",
  "ipCountryCode": "回應字串",
  "ipRecordedAt": "回應字串",
  "assignee": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "status": "open",
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "memberIds": [
        "550e8400-e29b-41d4-a716-446655440000"
      ]
    }
  ],
  "progressStatus": "回應字串",
  "firstResponseAt": "回應字串",
  "queuedAt": "回應字串",
  "assignedAt": "回應字串",
  "transferReason": "回應字串",
  "satisfactionScore": 456,
  "satisfactionComment": "回應字串",
  "satisfactionSubmittedAt": "回應字串",
  "latestAnalysisSummary": "回應字串",
  "clientPlatform": {},
  "workingDirectory": "回應字串",
  "slideProjectId": "回應字串",
  "matchedField": "回應字串",
  "matchedSnippet": "回應字串",
  "matchedMessageId": "回應字串",
  "pinnedAt": "回應字串"
}

---

分享對話

POST /api/v1/conversations/{conversationPk}/share/

參數

參數名稱	必填	類型	說明
conversationPk	✅	string

請求內容

請求參數

欄位	類型	必填	說明
shareScope	string (enum: organization, group, member)	是	organization: Organization ; group: Group ; member: Member;
permission	object	否
title	string	否
description	string	否
groupIds	array[string]	否
memberIds	array[string]	否

請求結構範例

{
  "shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
  "permission"?:  // 非必填
  {
  }
  "title"?: string // 非必填
  "description"?: string // 非必填
  "groupIds"?: [ // 非必填
    string (uuid)
  ]
  "memberIds"?: [ // 非必填
    string (uuid)
  ]
}

請求範例值

{
  "shareScope": "organization",
  "permission": {},
  "title": "範例名稱",
  "description": "範例字串",
  "groupIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "memberIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/conversations/{conversationPk}/share/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shareScope": "organization",
    "permission": {},
    "title": "範例名稱",
    "description": "範例字串",
    "groupIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "memberIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

{
  "shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
  "permission"?:  // 非必填
  {
  }
  "title"?: string // 非必填
  "description"?: string // 非必填
  "groupIds"?: [ // 非必填
    string (uuid)
  ]
  "memberIds"?: [ // 非必填
    string (uuid)
  ]
}

回應範例值

{
  "shareScope": "organization",
  "permission": {},
  "title": "回應字串",
  "description": "回應字串",
  "groupIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "memberIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}

---

快速分享對話

POST /api/v1/conversations/{conversationPk}/share/quick/

參數

參數名稱	必填	類型	說明
conversationPk	✅	string

請求內容

請求參數

欄位	類型	必填	說明
shareScope	string (enum: organization, group, member)	是	organization: Organization ; group: Group ; member: Member;
permission	object	否
title	string	否
description	string	否
groupIds	array[string]	否
memberIds	array[string]	否

請求結構範例

{
  "shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
  "permission"?:  // 非必填
  {
  }
  "title"?: string // 非必填
  "description"?: string // 非必填
  "groupIds"?: [ // 非必填
    string (uuid)
  ]
  "memberIds"?: [ // 非必填
    string (uuid)
  ]
}

請求範例值

{
  "shareScope": "organization",
  "permission": {},
  "title": "範例名稱",
  "description": "範例字串",
  "groupIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "memberIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/conversations/{conversationPk}/share/quick/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shareScope": "organization",
    "permission": {},
    "title": "範例名稱",
    "description": "範例字串",
    "groupIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "memberIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
  "permission"?:  // 非必填
  {
  }
  "title"?: string // 非必填
  "description"?: string // 非必填
  "groupIds"?: [ // 非必填
    string (uuid)
  ]
  "memberIds"?: [ // 非必填
    string (uuid)
  ]
}

回應範例值

{
  "shareScope": "organization",
  "permission": {},
  "title": "回應字串",
  "description": "回應字串",
  "groupIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "memberIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}

---

列出分享的對話

GET /api/v1/shared-conversations/

參數

參數名稱	必填	類型	說明
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/shared-conversations/?page=1&pageSize=1" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "title": string // Custom title for the shared conversation
      "description": string // Custom description for the shared conversation
      "shareScope": 
      {
      }
      "permission": 
      {
      }
      "sharedBy": 
      {
        "id": string (uuid)
        "name": string
      }
      "messageCount": integer
      "createdAt": string (timestamp)
    }
  ]
}

回應範例值

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "回應字串",
      "description": "回應字串",
      "shareScope": {},
      "permission": {},
      "sharedBy": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "messageCount": 456,
      "createdAt": "回應字串"
    }
  ]
}

---

取得特定分享對話

GET /api/v1/shared-conversations/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Shared Conversation.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "title": string // Custom title for the shared conversation
  "description": string // Custom description for the shared conversation
  "permission": 
  {
  }
  "sharedBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "createdAt": string (timestamp)
  "conversationSnapshot": object // Frozen conversation snapshot: {title, messages[]}
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "回應字串",
  "description": "回應字串",
  "permission": {},
  "sharedBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "createdAt": "回應字串",
  "conversationSnapshot": null
}

---

更新分享對話

PATCH /api/v1/shared-conversations/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Shared Conversation.

請求內容

請求參數

欄位	類型	必填	說明
title	string	否
description	string	否
permission	string (enum: readonly, copy)	否	readonly: Read Only ; copy: Copyable;

請求結構範例

{
  "title"?: string // 非必填
  "description"?: string // 非必填
  "permission"?: string (enum: readonly, copy) // * `readonly` - Read Only
* `copy` - Copyable (非必填)
}

請求範例值

{
  "title": "範例名稱",
  "description": "範例字串",
  "permission": "readonly"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "範例名稱",
    "description": "範例字串",
    "permission": "readonly"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "title"?: string // 非必填
  "description"?: string // 非必填
  "permission"?: string (enum: readonly, copy) // * `readonly` - Read Only
* `copy` - Copyable (非必填)
}

回應範例值

{
  "title": "回應字串",
  "description": "回應字串",
  "permission": "readonly"
}

---

刪除分享對話

DELETE /api/v1/shared-conversations/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Shared Conversation.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	No response body

---

複製分享對話

POST /api/v1/shared-conversations/{id}/fork/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Shared Conversation.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "title": string // Custom title for the shared conversation
  "description": string // Custom description for the shared conversation
  "permission": 
  {
  }
  "sharedBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "createdAt": string (timestamp)
  "conversationSnapshot": object // Frozen conversation snapshot: {title, messages[]}
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "回應字串",
  "description": "回應字串",
  "permission": {},
  "sharedBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "createdAt": "回應字串",
  "conversationSnapshot": null
}

---

取得我的分享列表

GET /api/v1/shared-conversations/my-shares/

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/shared-conversations/my-shares/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "title": string // Custom title for the shared conversation
  "description": string // Custom description for the shared conversation
  "shareScope": 
  {
  }
  "permission": 
  {
  }
  "sharedBy": 
  {
    "id": string (uuid)
    "name": string
  }
  "messageCount": integer
  "createdAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "回應字串",
  "description": "回應字串",
  "shareScope": {},
  "permission": {},
  "sharedBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "messageCount": 456,
  "createdAt": "回應字串"
}

---

建立訊息回饋

POST /api/v1/messages/{messagePk}/feedback/

參數

參數名稱	必填	類型	說明
messagePk	✅	string

請求內容

請求參數

欄位	類型	必填	說明
type	object	是
suggestion	string	否

請求結構範例

{
  "type": 
  {
  }
  "suggestion"?: string // 非必填
}

請求範例值

{
  "type": {},
  "suggestion": "範例字串"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": {},
    "suggestion": "範例字串"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "type": 
  {
  }
  "suggestion"?: string // 非必填
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": {},
  "suggestion": "回應字串",
  "updatedAt": "回應字串"
}

狀態碼: 400 - 此訊息已有回饋，請使用 PATCH 方法更新

---

更新訊息回饋

PUT /api/v1/messages/{messagePk}/feedback/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this 訊息回饋.
messagePk	✅	string

請求內容

請求參數

欄位	類型	必填	說明
type	object	是
suggestion	string	否

請求結構範例

{
  "type": 
  {
  }
  "suggestion"?: string // 非必填
}

請求範例值

{
  "type": {},
  "suggestion": "範例字串"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": {},
    "suggestion": "範例字串"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "type": 
  {
  }
  "suggestion"?: string // 非必填
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": {},
  "suggestion": "回應字串",
  "updatedAt": "回應字串"
}

---

刪除訊息回饋

DELETE /api/v1/messages/{messagePk}/feedback/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this 訊息回饋.
messagePk	✅	string

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	成功刪除回饋
400	此回饋不屬於指定的訊息

---

取得對話紀錄列表

GET /api/v1/records/

參數

參數名稱	必填	類型	說明
chatbot	❌	string	篩選特定 AI 助理 (UUID)
endDate	❌	string	結束日期（格式：YYYY-MM-DD，如：2025-01-31）
errorType	❌	array	Multiple values may be separated by commas. `system`: System ; `llm`: LLM ; `embedding`: Embedding ; `reranker`: Reranker ; `vector_db`: Vector DB ; `workflow`: Workflow ; `tool`: Tool ; `timeout`: Ti...
feedbackType	❌	array	Multiple values may be separated by commas. `like`: Like ; `dislike`: Dislike;
hasError	❌	boolean
hasFeedback	❌	boolean
keyword	❌	string	關鍵字搜尋 (同時搜尋使用者訊息和機器人回答內容)
largeLanguageModel	❌	string	篩選特定大型語言模型 (UUID)
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
startDate	❌	string	開始日期（格式：YYYY-MM-DD，如：2025-01-01）

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/records/?chatbot=example&endDate=example&errorType=example&feedbackType=example&hasError=true&hasFeedback=true&keyword=example&largeLanguageModel=example&page=1&pageSize=1&startDate=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "senderName": string // 返回使用者訊息發送者的名稱
      "feedback": 
      {
        "id": string (uuid)
        "type": 
        {
        }
        "suggestion"?: string // 非必填
        "updatedAt": string (timestamp)
      }
      "inputMessage": string
      "condenseMessage": string // 綜合聊天歷史與上下文後，修飾過後的使用者訊息
      "outputMessage": string
      "faithfulnessScore": number (double) // 判斷chatbot回覆是否符合資料庫內容，是否憑空想像
      "displayFaithfulnessScore": integer
      "answerRelevancyScore": number (double) // 判斷chatbot回覆是否與使用者問題相關
      "displayAnswerRelevancyScore": integer
      "contextPrecisionScore": number (double) // 判斷chatbot回覆是否與參考資料相關
      "displayContextPrecisionScore": integer
      "answerCorrectnessScore": number (double) // 判斷chatbot回覆是否正確(需要有標準答案)
      "displayAnswerCorrectnessScore": integer
      "answerSimilarityScore": number (double) // 判斷chatbot回覆是否與標準答案相似
      "displayAnswerSimilarityScore": integer
      "contextRecallScore": number (double) // 判斷chatbot回覆是否能夠從參考資料中召回相關資料
      "displayContextRecallScore": integer
      "replyTime": string
      "createdAt": string (timestamp)
      "error": string // 儲存執行過程中的錯誤訊息
      "errorType": // 可能有不同的類型
      string (enum: system, llm, embedding, reranker, vector_db, workflow, tool, timeout, client_interrupt, evaluation, other) // 區分錯誤來源：系統、LLM、Embedding、Reranker 等

* `system` - System
* `llm` - LLM
* `embedding` - Embedding
* `reranker` - Reranker
* `vector_db` - Vector DB
* `workflow` - Workflow
* `tool` - Tool
* `timeout` - Timeout
* `client_interrupt` - Client Interrupt
* `evaluation` - Evaluation
* `other` - Other
      "processingTime": object // 回傳各個處理階段的時間統計，含 streaming_metrics waterfall
      "usage": object // 回傳使用量統計，包含字數和 token 數
      "citationNodes": [
        {
          "id": string
          "text": string
          "chatbotFileId": string
          "fileName": string
          "url": string
        }
      ]
      "inputHookLogs": [
        {
          "id": string (uuid)
          "hook": string (uuid)
          "hookName": string
          "hookTypeLabel": string
          "hookAction": string
          "conversation": string (uuid)
          "message": string (uuid)
          "messageContent": string // Return the raw message text.
          "chatbotId": string
          "chatbotName": string
          "metadata": object
          "triggerPoint": string
          "createdAt": string (timestamp)
          "updatedAt": string (timestamp)
        }
      ]
      "outputHookLogs": [
        {
          "id": string (uuid)
          "hook": string (uuid)
          "hookName": string
          "hookTypeLabel": string
          "hookAction": string
          "conversation": string (uuid)
          "message": string (uuid)
          "messageContent": string // Return the raw message text.
          "chatbotId": string
          "chatbotName": string
          "metadata": object
          "triggerPoint": string
          "createdAt": string (timestamp)
          "updatedAt": string (timestamp)
        }
      ]
      "instructionId": string
      "llm": 
      {
        "id": string (uuid)
        "name": string
      }
      "effectiveMaxLlmOutputTokens": integer // 此次問答實際使用的 max_tokens 設定值，可能來自 Chatbot.custom_max_llm_output_tokens 或 LLM.max_tokens
      "chatbot": 
      {
        "id": string (uuid)
        "name": string
      }
      "context": string
      "conversationId": string (uuid)
      "inboxId": string (uuid)
      "botMessageId": string (uuid)
      "userMessageId": string (uuid)
      "creditCosts": [ // Return credit costs aggregated by item_code for credit-mode organizations.
        object
      ]
      "llmRawRequest": object // Raw messages array sent to the LLM on the final round, including system prompt and memory
    }
  ]
}

回應範例值

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "senderName": "回應字串",
      "feedback": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": {},
        "suggestion": "回應字串",
        "updatedAt": "回應字串"
      },
      "inputMessage": "回應字串",
      "condenseMessage": "回應字串",
      "outputMessage": "回應字串",
      "faithfulnessScore": 456,
      "displayFaithfulnessScore": 456,
      "answerRelevancyScore": 456,
      "displayAnswerRelevancyScore": 456,
      "contextPrecisionScore": 456,
      "displayContextPrecisionScore": 456,
      "answerCorrectnessScore": 456,
      "displayAnswerCorrectnessScore": 456,
      "answerSimilarityScore": 456,
      "displayAnswerSimilarityScore": 456,
      "contextRecallScore": 456,
      "displayContextRecallScore": 456,
      "replyTime": "回應字串",
      "createdAt": "回應字串",
      "error": "回應字串",
      "errorType": "system",
      "processingTime": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      },
      "usage": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      },
      "citationNodes": [
        {
          "id": "回應字串",
          "text": "回應字串",
          "chatbotFileId": "回應字串",
          "fileName": "回應字串",
          "url": "回應字串"
        }
      ],
      "inputHookLogs": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "hook": "550e8400-e29b-41d4-a716-446655440000",
          "hookName": "回應字串",
          "hookTypeLabel": "回應字串",
          "hookAction": "回應字串",
          "conversation": "550e8400-e29b-41d4-a716-446655440000",
          "message": "550e8400-e29b-41d4-a716-446655440000",
          "messageContent": "回應字串",
          "chatbotId": "回應字串",
          "chatbotName": "回應字串",
          "metadata": null,
          "triggerPoint": "回應字串",
          "createdAt": "回應字串",
          "updatedAt": "回應字串"
        }
      ],
      "outputHookLogs": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "hook": "550e8400-e29b-41d4-a716-446655440000",
          "hookName": "回應字串",
          "hookTypeLabel": "回應字串",
          "hookAction": "回應字串",
          "conversation": "550e8400-e29b-41d4-a716-446655440000",
          "message": "550e8400-e29b-41d4-a716-446655440000",
          "messageContent": "回應字串",
          "chatbotId": "回應字串",
          "chatbotName": "回應字串",
          "metadata": null,
          "triggerPoint": "回應字串",
          "createdAt": "回應字串",
          "updatedAt": "回應字串"
        }
      ],
      "instructionId": "回應字串",
      "llm": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "effectiveMaxLlmOutputTokens": 456,
      "chatbot": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "context": "回應字串",
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "inboxId": "550e8400-e29b-41d4-a716-446655440000",
      "botMessageId": "550e8400-e29b-41d4-a716-446655440000",
      "userMessageId": "550e8400-e29b-41d4-a716-446655440000",
      "creditCosts": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應範例名稱",
          "description": "回應範例描述"
        }
      ],
      "llmRawRequest": null
    }
  ]
}

---

取得特定對話紀錄

GET /api/v1/records/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Chatbot 紀錄.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/records/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "senderName": string // 返回使用者訊息發送者的名稱
  "feedback": 
  {
    "id": string (uuid)
    "type": 
    {
    }
    "suggestion"?: string // 非必填
    "updatedAt": string (timestamp)
  }
  "inputMessage": string
  "condenseMessage": string // 綜合聊天歷史與上下文後，修飾過後的使用者訊息
  "outputMessage": string
  "faithfulnessScore": number (double) // 判斷chatbot回覆是否符合資料庫內容，是否憑空想像
  "displayFaithfulnessScore": integer
  "answerRelevancyScore": number (double) // 判斷chatbot回覆是否與使用者問題相關
  "displayAnswerRelevancyScore": integer
  "contextPrecisionScore": number (double) // 判斷chatbot回覆是否與參考資料相關
  "displayContextPrecisionScore": integer
  "answerCorrectnessScore": number (double) // 判斷chatbot回覆是否正確(需要有標準答案)
  "displayAnswerCorrectnessScore": integer
  "answerSimilarityScore": number (double) // 判斷chatbot回覆是否與標準答案相似
  "displayAnswerSimilarityScore": integer
  "contextRecallScore": number (double) // 判斷chatbot回覆是否能夠從參考資料中召回相關資料
  "displayContextRecallScore": integer
  "replyTime": string
  "createdAt": string (timestamp)
  "error": string // 儲存執行過程中的錯誤訊息
  "errorType": // 可能有不同的類型
  string (enum: system, llm, embedding, reranker, vector_db, workflow, tool, timeout, client_interrupt, evaluation, other) // 區分錯誤來源：系統、LLM、Embedding、Reranker 等

* `system` - System
* `llm` - LLM
* `embedding` - Embedding
* `reranker` - Reranker
* `vector_db` - Vector DB
* `workflow` - Workflow
* `tool` - Tool
* `timeout` - Timeout
* `client_interrupt` - Client Interrupt
* `evaluation` - Evaluation
* `other` - Other
  "processingTime": object // 回傳各個處理階段的時間統計，含 streaming_metrics waterfall
  "usage": object // 回傳使用量統計，包含字數和 token 數
  "citationNodes": [
    {
      "id": string
      "text": string
      "chatbotFileId": string
      "fileName": string
      "url": string
    }
  ]
  "inputHookLogs": [
    {
      "id": string (uuid)
      "hook": string (uuid)
      "hookName": string
      "hookTypeLabel": string
      "hookAction": string
      "conversation": string (uuid)
      "message": string (uuid)
      "messageContent": string // Return the raw message text.
      "chatbotId": string
      "chatbotName": string
      "metadata": object
      "triggerPoint": string
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
  "outputHookLogs": [
    {
      "id": string (uuid)
      "hook": string (uuid)
      "hookName": string
      "hookTypeLabel": string
      "hookAction": string
      "conversation": string (uuid)
      "message": string (uuid)
      "messageContent": string // Return the raw message text.
      "chatbotId": string
      "chatbotName": string
      "metadata": object
      "triggerPoint": string
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
  "instructionId": string
  "llm": 
  {
    "id": string (uuid)
    "name": string
  }
  "effectiveMaxLlmOutputTokens": integer // 此次問答實際使用的 max_tokens 設定值，可能來自 Chatbot.custom_max_llm_output_tokens 或 LLM.max_tokens
  "chatbot": 
  {
    "id": string (uuid)
    "name": string
  }
  "context": string
  "conversationId": string (uuid)
  "inboxId": string (uuid)
  "botMessageId": string (uuid)
  "userMessageId": string (uuid)
  "creditCosts": [ // Return credit costs aggregated by item_code for credit-mode organizations.
    object
  ]
  "llmRawRequest": object // Raw messages array sent to the LLM on the final round, including system prompt and memory
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "senderName": "回應字串",
  "feedback": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": {},
    "suggestion": "回應字串",
    "updatedAt": "回應字串"
  },
  "inputMessage": "回應字串",
  "condenseMessage": "回應字串",
  "outputMessage": "回應字串",
  "faithfulnessScore": 456,
  "displayFaithfulnessScore": 456,
  "answerRelevancyScore": 456,
  "displayAnswerRelevancyScore": 456,
  "contextPrecisionScore": 456,
  "displayContextPrecisionScore": 456,
  "answerCorrectnessScore": 456,
  "displayAnswerCorrectnessScore": 456,
  "answerSimilarityScore": 456,
  "displayAnswerSimilarityScore": 456,
  "contextRecallScore": 456,
  "displayContextRecallScore": 456,
  "replyTime": "回應字串",
  "createdAt": "回應字串",
  "error": "回應字串",
  "errorType": "system",
  "processingTime": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "usage": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "citationNodes": [
    {
      "id": "回應字串",
      "text": "回應字串",
      "chatbotFileId": "回應字串",
      "fileName": "回應字串",
      "url": "回應字串"
    }
  ],
  "inputHookLogs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "hook": "550e8400-e29b-41d4-a716-446655440000",
      "hookName": "回應字串",
      "hookTypeLabel": "回應字串",
      "hookAction": "回應字串",
      "conversation": "550e8400-e29b-41d4-a716-446655440000",
      "message": "550e8400-e29b-41d4-a716-446655440000",
      "messageContent": "回應字串",
      "chatbotId": "回應字串",
      "chatbotName": "回應字串",
      "metadata": null,
      "triggerPoint": "回應字串",
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ],
  "outputHookLogs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "hook": "550e8400-e29b-41d4-a716-446655440000",
      "hookName": "回應字串",
      "hookTypeLabel": "回應字串",
      "hookAction": "回應字串",
      "conversation": "550e8400-e29b-41d4-a716-446655440000",
      "message": "550e8400-e29b-41d4-a716-446655440000",
      "messageContent": "回應字串",
      "chatbotId": "回應字串",
      "chatbotName": "回應字串",
      "metadata": null,
      "triggerPoint": "回應字串",
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ],
  "instructionId": "回應字串",
  "llm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "effectiveMaxLlmOutputTokens": 456,
  "chatbot": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "context": "回應字串",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "inboxId": "550e8400-e29b-41d4-a716-446655440000",
  "botMessageId": "550e8400-e29b-41d4-a716-446655440000",
  "userMessageId": "550e8400-e29b-41d4-a716-446655440000",
  "creditCosts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    }
  ],
  "llmRawRequest": null
}

狀態碼: 404 - 找不到指定的對話記錄

---

取得特定對話紀錄

GET /api/v1/records/export-excel-requests/

參數

參數名稱	必填	類型	說明
endDate	❌	string	結束日期（格式：YYYY-MM-DD，如：2025-01-31）
keyword	❌	string	過濾包含特定關鍵字的對話記錄（同時搜尋用戶訊息和機器人回覆）
startDate	❌	string	開始日期（格式：YYYY-MM-DD，如：2025-01-01）

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
200	Excel 檔案下載

---

建立對話紀錄匯出請求

POST /api/v1/records/export-excel-requests/

參數

參數名稱	必填	類型	說明
endDate	❌	string	結束日期（格式：YYYY-MM-DD，如：2025-01-31）
keyword	❌	string	過濾包含特定關鍵字的對話記錄（同時搜尋用戶訊息和機器人回覆）
startDate	❌	string	開始日期（格式：YYYY-MM-DD，如：2025-01-01）

請求內容

請求參數

欄位	類型	必填	說明
chatbot	string	否	指定要匯出的 Chatbot UUID，支援逗號分隔多個 UUID。留空則匯出組織內所有有權限的 Chatbot。
chatbotId	string (uuid)	否	指定要匯出的 Chatbot UUID（chatbot 的別名，僅支援單個 UUID）。
largeLanguageModel	string	否	指定要匯出的大型語言模型 UUID，支援逗號分隔多個 UUID。

請求結構範例

{
  "chatbot"?: string // 指定要匯出的 Chatbot UUID，支援逗號分隔多個 UUID。留空則匯出組織內所有有權限的 Chatbot。 (非必填)
  "chatbotId"?: string (uuid) // 指定要匯出的 Chatbot UUID（chatbot 的別名，僅支援單個 UUID）。 (非必填)
  "largeLanguageModel"?: string // 指定要匯出的大型語言模型 UUID，支援逗號分隔多個 UUID。 (非必填)
}

請求範例值

{
  "chatbot": "範例字串",
  "chatbotId": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "範例字串"
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=example" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatbot": "範例字串",
    "chatbotId": "550e8400-e29b-41d4-a716-446655440000",
    "keyword": "範例字串",
    "largeLanguageModel": "範例字串",
    "startDate": "範例字串",
    "endDate": "範例字串"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
200	Excel 檔案下載

---

取得對話紀錄匯出狀態

GET /api/v1/records/export-excel-requests/{exportId}/

參數

參數名稱	必填	類型	說明
exportId	✅	string

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/records/export-excel-requests/{exportId}/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "senderName": string // 返回使用者訊息發送者的名稱
  "inputMessage": string
  "outputMessage": string
  "chatbot": 
  {
    "id": string (uuid)
    "name": string
  }
  "condenseMessage": string // 綜合聊天歷史與上下文後，修飾過後的使用者訊息
  "feedback": 
  {
    "id": string (uuid)
    "type": 
    {
    }
    "suggestion"?: string // 非必填
    "updatedAt": string (timestamp)
  }
  "displayFaithfulnessScore": integer
  "displayAnswerRelevancyScore": integer
  "displayContextPrecisionScore": integer
  "displayAnswerCorrectnessScore": integer
  "displayAnswerSimilarityScore": integer
  "displayContextRecallScore": integer
  "replyTime": string
  "processingTime": object // 回傳列表頁處理時間統計，與詳情頁算式一致但不含 streaming_metrics waterfall
  "usage": object // 回傳使用量統計，包含字數和 token 數
  "llm": 
  {
    "id": string (uuid)
    "name": string
  }
  "createdAt": string (timestamp)
  "conversationId": string (uuid)
  "errorType": // 可能有不同的類型
  string (enum: system, llm, embedding, reranker, vector_db, workflow, tool, timeout, client_interrupt, evaluation, other) // 區分錯誤來源：系統、LLM、Embedding、Reranker 等

* `system` - System
* `llm` - LLM
* `embedding` - Embedding
* `reranker` - Reranker
* `vector_db` - Vector DB
* `workflow` - Workflow
* `tool` - Tool
* `timeout` - Timeout
* `client_interrupt` - Client Interrupt
* `evaluation` - Evaluation
* `other` - Other
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "senderName": "回應字串",
  "inputMessage": "回應字串",
  "outputMessage": "回應字串",
  "chatbot": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "condenseMessage": "回應字串",
  "feedback": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": {},
    "suggestion": "回應字串",
    "updatedAt": "回應字串"
  },
  "displayFaithfulnessScore": 456,
  "displayAnswerRelevancyScore": 456,
  "displayContextPrecisionScore": 456,
  "displayAnswerCorrectnessScore": 456,
  "displayAnswerSimilarityScore": 456,
  "displayContextRecallScore": 456,
  "replyTime": "回應字串",
  "processingTime": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "usage": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "llm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "createdAt": "回應字串",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "errorType": "system"
}

---