# 對話與訊息
### 發送訊息 (串流)
POST `/api/chatbots/{chatbotId}/completions/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------ | -- |
| `chatbotId` | ✅ | string | |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------------------- | ----------------------------------------------------------- | -- | ------------------------------------------ |
| conversation | string (uuid) | 否 | 對話的唯一識別碼，如果為空則會建立新對話（可選） |
| message | object (含 6 個屬性: content, contentPayload, queryMetadata...) | 是 | 要發送的訊息內容 |
| message.content | string | 是 | 訊息的文字內容 |
| message.contentPayload | object | 否 | 訊息的額外內容負載，JSON 格式（可選） |
| message.queryMetadata | object | 否 | 查詢元數據，JSON 格式（可選） |
| message.metadata | object | 否 | 訊息的環境元數據，例如時區等資訊，JSON 格式（可選） |
| message.attachments | array\[AttachmentInput] | 否 | 訊息的附件列表（可選） |
| message.sender | string (uuid) | 否 | 發送者的 Contact ID（可選） |
| isStreaming | boolean | 否 | 是否使用串流模式回應，預設為 false（可選） |
| waitForAttachments | boolean | 否 | 是否等待附件處理完成後再進入 agent workflow，預設為 true（可選） |
**請求結構範例**
```typescript
{
"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 位址
}
]
"sender"?: string (uuid) // 發送者的 Contact ID（可選） (非必填)
}
"isStreaming"?: boolean // 是否使用串流模式回應，預設為 false（可選） (非必填)
"waitForAttachments"?: boolean // 是否等待附件處理完成後再進入 agent workflow，預設為 true（可選） (非必填)
}
```
**請求範例值**
```json
{
"message": {
"content": "你好，請介紹一下你自己"
},
"is_streaming": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"message": {
"content": "你好，請介紹一下你自己"
},
"is_streaming": true
};
axios.post("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"message": {
"content": "你好，請介紹一下你自己"
},
"is_streaming": true
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"message": {
"content": "你好，請介紹一下你自己"
},
"is_streaming": true
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ------------------------------- |
| 200 | 對話回應內容，若是串流則為事件流 |
| 400 | 請求參數錯誤，可能原因包括：Contact ID 不屬於該組織 |
***
### 發送訊息 (串流)
POST `/api/v1/chatbots/{chatbotId}/completions/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------ | -- |
| `chatbotId` | ✅ | string | |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------------------- | ----------------------------------------------------------- | -- | ------------------------------------------ |
| conversation | string (uuid) | 否 | 對話的唯一識別碼，如果為空則會建立新對話（可選） |
| message | object (含 6 個屬性: content, contentPayload, queryMetadata...) | 是 | 要發送的訊息內容 |
| message.content | string | 是 | 訊息的文字內容 |
| message.contentPayload | object | 否 | 訊息的額外內容負載，JSON 格式（可選） |
| message.queryMetadata | object | 否 | 查詢元數據，JSON 格式（可選） |
| message.metadata | object | 否 | 訊息的環境元數據，例如時區等資訊，JSON 格式（可選） |
| message.attachments | array\[AttachmentInput] | 否 | 訊息的附件列表（可選） |
| message.sender | string (uuid) | 否 | 發送者的 Contact ID（可選） |
| isStreaming | boolean | 否 | 是否使用串流模式回應，預設為 false（可選） |
| waitForAttachments | boolean | 否 | 是否等待附件處理完成後再進入 agent workflow，預設為 true（可選） |
**請求結構範例**
```typescript
{
"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 位址
}
]
"sender"?: string (uuid) // 發送者的 Contact ID（可選） (非必填)
}
"isStreaming"?: boolean // 是否使用串流模式回應，預設為 false（可選） (非必填)
"waitForAttachments"?: boolean // 是否等待附件處理完成後再進入 agent workflow，預設為 true（可選） (非必填)
}
```
**請求範例值**
```json
{
"message": {
"content": "你好，請介紹一下你自己"
},
"is_streaming": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"message": {
"content": "你好，請介紹一下你自己"
},
"is_streaming": true
};
axios.post("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"message": {
"content": "你好，請介紹一下你自己"
},
"is_streaming": true
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"message": {
"content": "你好，請介紹一下你自己"
},
"is_streaming": true
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ------------------------------- |
| 200 | 對話回應內容，若是串流則為事件流 |
| 400 | 請求參數錯誤，可能原因包括：Contact ID 不屬於該組織 |
***
### 發送訊息 (建立)
POST `/api/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 | 否 | |
**請求結構範例**
```typescript
{
"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 // 非必填
}
```
**請求範例值**
````json
{
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://autox-media-dev.playma.app/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"
}
}
````
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
````bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/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://autox-media-dev.playma.app/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 並核對請求資料。
````
{% endtab %}
{% tab title="JavaScript" %}
````javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://autox-media-dev.playma.app/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"
}
};
axios.post("https://api.maiagent.ai/api/messages/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
````
{% endtab %}
{% tab title="Python" %}
````python
import requests
url = "https://api.maiagent.ai/api/messages/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://autox-media-dev.playma.app/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"
}
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
````
{% endtab %}
{% tab title="PHP" %}
````php
post("https://api.maiagent.ai/api/messages/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://autox-media-dev.playma.app/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"
}
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
````
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"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 // 非必填
}
}
"labels"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // 非必填
"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 ```` 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)
}
}
"score"?: number (double) // 非必填
"displayScore": integer
"citationNumber"?: integer // Citation編號，對應回應內容中的 [1], [2] 等標記 (非必填)
"highlightedText"?: string // ES/OpenSearch highlight result with 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 // 非必填
}
```
**回應範例值**
````json
{
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://autox-media-dev.playma.app/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/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ----------------- | ----------------------------- | -- | ---------------- |
| 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 | 否 | |
**請求結構範例**
```typescript
{
"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 // 非必填
}
```
**請求範例值**
````json
{
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://autox-media-dev.playma.app/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"
}
}
````
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
````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://autox-media-dev.playma.app/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 並核對請求資料。
````
{% endtab %}
{% tab title="JavaScript" %}
````javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://autox-media-dev.playma.app/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"
}
};
axios.post("https://api.maiagent.ai/api/v1/messages/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
````
{% endtab %}
{% tab title="Python" %}
````python
import requests
url = "https://api.maiagent.ai/api/v1/messages/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://autox-media-dev.playma.app/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"
}
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
````
{% endtab %}
{% tab title="PHP" %}
````php
post("https://api.maiagent.ai/api/v1/messages/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://autox-media-dev.playma.app/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"
}
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
````
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"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 // 非必填
}
}
"labels"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // 非必填
"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 ```` 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)
}
}
"score"?: number (double) // 非必填
"displayScore": integer
"citationNumber"?: integer // Citation編號，對應回應內容中的 [1], [2] 等標記 (非必填)
"highlightedText"?: string // ES/OpenSearch highlight result with 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 // 非必填
}
```
**回應範例值**
````json
{
"conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
"sender": {
"id": 2.992461161002561e+38,
"name": "jessiekuo",
"avatar": "https://autox-media-dev.playma.app/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/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 | 否 | |
**請求結構範例**
```typescript
{
"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 // 非必填
}
```
**請求範例值**
```json
{
"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
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/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
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"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
};
axios.post("https://api.maiagent.ai/api/messages/outgoing/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/messages/outgoing/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"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
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/messages/outgoing/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"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
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"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 // 非必填
}
}
"labels"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // 非必填
"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 ```` 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)
}
}
"score"?: number (double) // 非必填
"displayScore": integer
"citationNumber"?: integer // Citation編號，對應回應內容中的 [1], [2] 等標記 (非必填)
"highlightedText"?: string // ES/OpenSearch highlight result with 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 // 非必填
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"sender": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"avatar": "回應字串",
"email": "response@example.com",
"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
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"rawUserDefineMetadata": null,
"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": "回應字串"
},
"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
}
```
***
### 發送主動訊息
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 | 否 | |
**請求結構範例**
```typescript
{
"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 // 非必填
}
```
**請求範例值**
```json
{
"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
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"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
};
axios.post("https://api.maiagent.ai/api/v1/messages/outgoing/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/messages/outgoing/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"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
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/messages/outgoing/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"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
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"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 // 非必填
}
}
"labels"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // 非必填
"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 ```` 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)
}
}
"score"?: number (double) // 非必填
"displayScore": integer
"citationNumber"?: integer // Citation編號，對應回應內容中的 [1], [2] 等標記 (非必填)
"highlightedText"?: string // ES/OpenSearch highlight result with 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 // 非必填
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"sender": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"avatar": "回應字串",
"email": "response@example.com",
"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
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"rawUserDefineMetadata": null,
"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": "回應字串"
},
"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
}
```
***
### 建立新的對話
POST `/api/conversations/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------- | ------------- | -- | -- |
| webChat | string (uuid) | 是 | |
| contact | string (uuid) | 否 | |
**請求結構範例**
```typescript
{
"webChat": string (uuid)
"contact"?: string (uuid) // 非必填
}
```
**請求範例值**
```json
{
"webChat": "550e8400-e29b-41d4-a716-446655440000",
"contact": "550e8400-e29b-41d4-a716-446655440000"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/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"
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"webChat": "550e8400-e29b-41d4-a716-446655440000",
"contact": "550e8400-e29b-41d4-a716-446655440000"
};
axios.post("https://api.maiagent.ai/api/conversations/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/conversations/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"webChat": "550e8400-e29b-41d4-a716-446655440000",
"contact": "550e8400-e29b-41d4-a716-446655440000"
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/conversations/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"webChat": "550e8400-e29b-41d4-a716-446655440000",
"contact": "550e8400-e29b-41d4-a716-446655440000"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"contact": { // 輕量級 Contact Serializer，用於 Conversation List view
只包含 List view 必要的欄位，移除 inboxes 和 mcp_credentials
以避免 N+1 查詢問題
{
"id": string (uuid)
"name": string
"avatar"?: string (uri) // 非必填
"sourceId"?: string // 非必填
}
}
"inbox": {
{
"id": string (uuid)
"name": string
"channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
"unreadConversationsCount"?: integer // 非必填
"signAuth"?: // 非必填
{
"id": string (uuid)
"signSource": string (uuid)
"signParams": {
{
"keycloak":
{
"clientId": string
"url": string
"realm": string
}
"line":
{
"liffId": string
}
"ad":
{
"saml": string
}
}
}
}
}
}
"title": string
"lastMessage"?: { // 非必填
{
"id": string (uuid)
"type"?: string // 非必填
"content"?: string // 非必填
"contentPayload"?: object // 非必填
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 非必填
"updatedAt": string (timestamp)
}
"createdAt": string (timestamp)
"queryMetadata"?: object // 非必填
}
}
"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.
"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)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"contact": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"avatar": "https://example.com/file.jpg",
"sourceId": "回應字串"
},
"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": "回應字串"
}
}
}
},
"title": "回應字串",
"lastMessage": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "回應字串",
"content": "回應字串",
"contentPayload": null,
"feedback": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "回應字串",
"updatedAt": "回應字串"
},
"createdAt": "回應字串",
"queryMetadata": null
},
"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": "回應字串"
}
```
***
### 建立新的對話
POST `/api/v1/conversations/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------- | ------------- | -- | -- |
| webChat | string (uuid) | 是 | |
| contact | string (uuid) | 否 | |
**請求結構範例**
```typescript
{
"webChat": string (uuid)
"contact"?: string (uuid) // 非必填
}
```
**請求範例值**
```json
{
"webChat": "550e8400-e29b-41d4-a716-446655440000",
"contact": "550e8400-e29b-41d4-a716-446655440000"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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"
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"webChat": "550e8400-e29b-41d4-a716-446655440000",
"contact": "550e8400-e29b-41d4-a716-446655440000"
};
axios.post("https://api.maiagent.ai/api/v1/conversations/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/conversations/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"webChat": "550e8400-e29b-41d4-a716-446655440000",
"contact": "550e8400-e29b-41d4-a716-446655440000"
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/conversations/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"webChat": "550e8400-e29b-41d4-a716-446655440000",
"contact": "550e8400-e29b-41d4-a716-446655440000"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"contact": { // 輕量級 Contact Serializer，用於 Conversation List view
只包含 List view 必要的欄位，移除 inboxes 和 mcp_credentials
以避免 N+1 查詢問題
{
"id": string (uuid)
"name": string
"avatar"?: string (uri) // 非必填
"sourceId"?: string // 非必填
}
}
"inbox": {
{
"id": string (uuid)
"name": string
"channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
"unreadConversationsCount"?: integer // 非必填
"signAuth"?: // 非必填
{
"id": string (uuid)
"signSource": string (uuid)
"signParams": {
{
"keycloak":
{
"clientId": string
"url": string
"realm": string
}
"line":
{
"liffId": string
}
"ad":
{
"saml": string
}
}
}
}
}
}
"title": string
"lastMessage"?: { // 非必填
{
"id": string (uuid)
"type"?: string // 非必填
"content"?: string // 非必填
"contentPayload"?: object // 非必填
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 非必填
"updatedAt": string (timestamp)
}
"createdAt": string (timestamp)
"queryMetadata"?: object // 非必填
}
}
"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.
"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)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"contact": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"avatar": "https://example.com/file.jpg",
"sourceId": "回應字串"
},
"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": "回應字串"
}
}
}
},
"title": "回應字串",
"lastMessage": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "回應字串",
"content": "回應字串",
"contentPayload": null,
"feedback": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "回應字串",
"updatedAt": "回應字串"
},
"createdAt": "回應字串",
"queryMetadata": null
},
"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": "回應字串"
}
```
***
### 取得訊息列表
GET `/api/messages/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| -------------- | -- | ------- | ------------------------------------- |
| `conversation` | ✅ | string | 對話 ID |
| `cursor` | ❌ | string | The pagination cursor value. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/messages/?conversation=example&cursor=example&pageSize=1" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/messages/?conversation=example&cursor=example&pageSize=1", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/messages/?conversation=example&cursor=example&pageSize=1"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/messages/?conversation=example&cursor=example&pageSize=1", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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 // 非必填
}
}
"labels"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // 非必填
"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 ```` 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)
}
}
"score"?: number (double) // 非必填
"displayScore": integer
"citationNumber"?: integer // Citation編號，對應回應內容中的 [1], [2] 等標記 (非必填)
"highlightedText"?: string // ES/OpenSearch highlight result with 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 // 非必填
}
]
}
```
**回應範例值**
```json
{
"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": "response@example.com",
"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
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"rawUserDefineMetadata": null,
"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": "回應字串"
},
"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
}
]
}
```
***
### 取得訊息列表
GET `/api/v1/messages/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| -------------- | -- | ------- | ------------------------------------- |
| `conversation` | ✅ | string | 對話 ID |
| `cursor` | ❌ | string | The pagination cursor value. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/messages/?conversation=example&cursor=example&pageSize=1", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/messages/?conversation=example&cursor=example&pageSize=1"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/messages/?conversation=example&cursor=example&pageSize=1", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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 // 非必填
}
}
"labels"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // 非必填
"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 ```` 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)
}
}
"score"?: number (double) // 非必填
"displayScore": integer
"citationNumber"?: integer // Citation編號，對應回應內容中的 [1], [2] 等標記 (非必填)
"highlightedText"?: string // ES/OpenSearch highlight result with 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 // 非必填
}
]
}
```
**回應範例值**
```json
{
"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": "response@example.com",
"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
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"rawUserDefineMetadata": null,
"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": "回應字串"
},
"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
}
]
}
```
***
### 取得特定訊息
GET `/api/messages/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| -------------- | -- | ------ | ---------------------------------- |
| `id` | ✅ | string | A UUID string identifying this 訊息. |
| `conversation` | ✅ | string | 對話 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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 // 非必填
}
}
"labels"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // 非必填
"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 ```` 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)
}
}
"score"?: number (double) // 非必填
"displayScore": integer
"citationNumber"?: integer // Citation編號，對應回應內容中的 [1], [2] 等標記 (非必填)
"highlightedText"?: string // ES/OpenSearch highlight result with 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 // 非必填
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"sender": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"avatar": "回應字串",
"email": "response@example.com",
"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
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"rawUserDefineMetadata": null,
"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": "回應字串"
},
"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
}
```
***
### 取得特定訊息
GET `/api/v1/messages/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| -------------- | -- | ------ | ---------------------------------- |
| `id` | ✅ | string | A UUID string identifying this 訊息. |
| `conversation` | ✅ | string | 對話 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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 // 非必填
}
}
"labels"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"rawUserDefineMetadata"?: object // 非必填
"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 ```` 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)
}
}
"score"?: number (double) // 非必填
"displayScore": integer
"citationNumber"?: integer // Citation編號，對應回應內容中的 [1], [2] 等標記 (非必填)
"highlightedText"?: string // ES/OpenSearch highlight result with 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 // 非必填
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"conversation": "550e8400-e29b-41d4-a716-446655440000",
"sender": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"avatar": "回應字串",
"email": "response@example.com",
"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
},
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"rawUserDefineMetadata": null,
"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": "回應字串"
},
"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
}
```
***
### 取得對話列表
GET `/api/conversations/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ------------------------ | -- | ------- | ------------------------------------- |
| `contact` | ❌ | string | 聯絡人 ID |
| `cursor` | ❌ | string | The pagination cursor value. |
| `endDate` | ❌ | string | |
| `externalConversationId` | ❌ | string | |
| `externalSource` | ❌ | string | |
| `inbox` | ❌ | string | 對話平台 ID |
| `keyword` | ❌ | string | 關鍵字搜尋 |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `startDate` | ❌ | string | |
| `updatedAfter` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/conversations/?contact=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=example&keyword=example&pageSize=1&startDate=example&updatedAfter=2026-03-21T14:31:44.842Z" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/conversations/?contact=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=example&keyword=example&pageSize=1&startDate=example&updatedAfter=2026-03-21T14:31:44.842Z", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/conversations/?contact=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=example&keyword=example&pageSize=1&startDate=example&updatedAfter=2026-03-21T14:31:44.842Z"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/conversations/?contact=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=example&keyword=example&pageSize=1&startDate=example&updatedAfter=2026-03-21T14:31:44.842Z", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"contact": { // 輕量級 Contact Serializer，用於 Conversation List view
只包含 List view 必要的欄位，移除 inboxes 和 mcp_credentials
以避免 N+1 查詢問題
{
"id": string (uuid)
"name": string
"avatar"?: string (uri) // 非必填
"sourceId"?: string // 非必填
}
}
"inbox": {
{
"id": string (uuid)
"name": string
"channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
"unreadConversationsCount"?: integer // 非必填
"signAuth"?: // 非必填
{
"id": string (uuid)
"signSource": string (uuid)
"signParams": {
{
"keycloak":
{
"clientId": string
"url": string
"realm": string
}
"line":
{
"liffId": string
}
"ad":
{
"saml": string
}
}
}
}
}
}
"title": string
"lastMessage"?: { // 非必填
{
"id": string (uuid)
"type"?: string // 非必填
"content"?: string // 非必填
"contentPayload"?: object // 非必填
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 非必填
"updatedAt": string (timestamp)
}
"createdAt": string (timestamp)
"queryMetadata"?: object // 非必填
}
}
"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.
"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)
}
]
}
```
**回應範例值**
```json
{
"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",
"sourceId": "回應字串"
},
"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": "回應字串"
}
}
}
},
"title": "回應字串",
"lastMessage": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "回應字串",
"content": "回應字串",
"contentPayload": null,
"feedback": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "回應字串",
"updatedAt": "回應字串"
},
"createdAt": "回應字串",
"queryMetadata": null
},
"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": "回應字串"
}
]
}
```
***
### 取得對話列表
GET `/api/v1/conversations/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ------------------------ | -- | ------- | ------------------------------------- |
| `contact` | ❌ | string | 聯絡人 ID |
| `cursor` | ❌ | string | The pagination cursor value. |
| `endDate` | ❌ | string | |
| `externalConversationId` | ❌ | string | |
| `externalSource` | ❌ | string | |
| `inbox` | ❌ | string | 對話平台 ID |
| `keyword` | ❌ | string | 關鍵字搜尋 |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `startDate` | ❌ | string | |
| `updatedAfter` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/conversations/?contact=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=example&keyword=example&pageSize=1&startDate=example&updatedAfter=2026-03-21T14:31:44.842Z" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/conversations/?contact=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=example&keyword=example&pageSize=1&startDate=example&updatedAfter=2026-03-21T14:31:44.842Z", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/conversations/?contact=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=example&keyword=example&pageSize=1&startDate=example&updatedAfter=2026-03-21T14:31:44.842Z"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/conversations/?contact=example&cursor=example&endDate=example&externalConversationId=example&externalSource=example&inbox=example&keyword=example&pageSize=1&startDate=example&updatedAfter=2026-03-21T14:31:44.842Z", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"contact": { // 輕量級 Contact Serializer，用於 Conversation List view
只包含 List view 必要的欄位，移除 inboxes 和 mcp_credentials
以避免 N+1 查詢問題
{
"id": string (uuid)
"name": string
"avatar"?: string (uri) // 非必填
"sourceId"?: string // 非必填
}
}
"inbox": {
{
"id": string (uuid)
"name": string
"channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
"unreadConversationsCount"?: integer // 非必填
"signAuth"?: // 非必填
{
"id": string (uuid)
"signSource": string (uuid)
"signParams": {
{
"keycloak":
{
"clientId": string
"url": string
"realm": string
}
"line":
{
"liffId": string
}
"ad":
{
"saml": string
}
}
}
}
}
}
"title": string
"lastMessage"?: { // 非必填
{
"id": string (uuid)
"type"?: string // 非必填
"content"?: string // 非必填
"contentPayload"?: object // 非必填
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 非必填
"updatedAt": string (timestamp)
}
"createdAt": string (timestamp)
"queryMetadata"?: object // 非必填
}
}
"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.
"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)
}
]
}
```
**回應範例值**
```json
{
"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",
"sourceId": "回應字串"
},
"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": "回應字串"
}
}
}
},
"title": "回應字串",
"lastMessage": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "回應字串",
"content": "回應字串",
"contentPayload": null,
"feedback": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "回應字串",
"updatedAt": "回應字串"
},
"createdAt": "回應字串",
"queryMetadata": null
},
"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": "回應字串"
}
]
}
```
***
### 取得特定對話
GET `/api/conversations/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ---------------------------------- |
| `id` | ✅ | string | A UUID string identifying this 對話. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"contact": { // 輕量級 Contact Serializer，用於 Conversation List view
只包含 List view 必要的欄位，移除 inboxes 和 mcp_credentials
以避免 N+1 查詢問題
{
"id": string (uuid)
"name": string
"avatar"?: string (uri) // 非必填
"sourceId"?: string // 非必填
}
}
"inbox": {
{
"id": string (uuid)
"name": string
"channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
"unreadConversationsCount"?: integer // 非必填
"signAuth"?: // 非必填
{
"id": string (uuid)
"signSource": string (uuid)
"signParams": {
{
"keycloak":
{
"clientId": string
"url": string
"realm": string
}
"line":
{
"liffId": string
}
"ad":
{
"saml": string
}
}
}
}
}
}
"title": string
"lastMessage"?: { // 非必填
{
"id": string (uuid)
"type"?: string // 非必填
"content"?: string // 非必填
"contentPayload"?: object // 非必填
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 非必填
"updatedAt": string (timestamp)
}
"createdAt": string (timestamp)
"queryMetadata"?: object // 非必填
}
}
"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.
"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)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"contact": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"avatar": "https://example.com/file.jpg",
"sourceId": "回應字串"
},
"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": "回應字串"
}
}
}
},
"title": "回應字串",
"lastMessage": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "回應字串",
"content": "回應字串",
"contentPayload": null,
"feedback": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "回應字串",
"updatedAt": "回應字串"
},
"createdAt": "回應字串",
"queryMetadata": null
},
"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": "回應字串"
}
```
***
### 取得特定對話
GET `/api/v1/conversations/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ---------------------------------- |
| `id` | ✅ | string | A UUID string identifying this 對話. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"contact": { // 輕量級 Contact Serializer，用於 Conversation List view
只包含 List view 必要的欄位，移除 inboxes 和 mcp_credentials
以避免 N+1 查詢問題
{
"id": string (uuid)
"name": string
"avatar"?: string (uri) // 非必填
"sourceId"?: string // 非必填
}
}
"inbox": {
{
"id": string (uuid)
"name": string
"channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
"unreadConversationsCount"?: integer // 非必填
"signAuth"?: // 非必填
{
"id": string (uuid)
"signSource": string (uuid)
"signParams": {
{
"keycloak":
{
"clientId": string
"url": string
"realm": string
}
"line":
{
"liffId": string
}
"ad":
{
"saml": string
}
}
}
}
}
}
"title": string
"lastMessage"?: { // 非必填
{
"id": string (uuid)
"type"?: string // 非必填
"content"?: string // 非必填
"contentPayload"?: object // 非必填
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 非必填
"updatedAt": string (timestamp)
}
"createdAt": string (timestamp)
"queryMetadata"?: object // 非必填
}
}
"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.
"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)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"contact": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"avatar": "https://example.com/file.jpg",
"sourceId": "回應字串"
},
"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": "回應字串"
}
}
}
},
"title": "回應字串",
"lastMessage": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "回應字串",
"content": "回應字串",
"contentPayload": null,
"feedback": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "回應字串",
"updatedAt": "回應字串"
},
"createdAt": "回應字串",
"queryMetadata": null
},
"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": "回應字串"
}
```
***
### 重新命名對話
PATCH `/api/conversations/{id}/rename/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ---------------------------------- |
| `id` | ✅ | string | A UUID string identifying this 對話. |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ----- | ------ | -- | -- |
| title | string | 否 | |
**請求結構範例**
```typescript
{
"title"?: string // 非必填
}
```
**請求範例值**
```json
{
"title": "範例名稱"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/rename/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "範例名稱"
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"title": "範例名稱"
};
axios.patch("https://api.maiagent.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/rename/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/rename/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"title": "範例名稱"
}
response = requests.patch(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/rename/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"title": "範例名稱"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"contact": { // 輕量級 Contact Serializer，用於 Conversation List view
只包含 List view 必要的欄位，移除 inboxes 和 mcp_credentials
以避免 N+1 查詢問題
{
"id": string (uuid)
"name": string
"avatar"?: string (uri) // 非必填
"sourceId"?: string // 非必填
}
}
"inbox": {
{
"id": string (uuid)
"name": string
"channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
"unreadConversationsCount"?: integer // 非必填
"signAuth"?: // 非必填
{
"id": string (uuid)
"signSource": string (uuid)
"signParams": {
{
"keycloak":
{
"clientId": string
"url": string
"realm": string
}
"line":
{
"liffId": string
}
"ad":
{
"saml": string
}
}
}
}
}
}
"title": string
"lastMessage"?: { // 非必填
{
"id": string (uuid)
"type"?: string // 非必填
"content"?: string // 非必填
"contentPayload"?: object // 非必填
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 非必填
"updatedAt": string (timestamp)
}
"createdAt": string (timestamp)
"queryMetadata"?: object // 非必填
}
}
"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.
"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)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"contact": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"avatar": "https://example.com/file.jpg",
"sourceId": "回應字串"
},
"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": "回應字串"
}
}
}
},
"title": "回應字串",
"lastMessage": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "回應字串",
"content": "回應字串",
"contentPayload": null,
"feedback": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "回應字串",
"updatedAt": "回應字串"
},
"createdAt": "回應字串",
"queryMetadata": null
},
"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": "回應字串"
}
```
***
### 重新命名對話
PATCH `/api/v1/conversations/{id}/rename/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ---------------------------------- |
| `id` | ✅ | string | A UUID string identifying this 對話. |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ----- | ------ | -- | -- |
| title | string | 否 | |
**請求結構範例**
```typescript
{
"title"?: string // 非必填
}
```
**請求範例值**
```json
{
"title": "範例名稱"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"title": "範例名稱"
};
axios.patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/rename/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/rename/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"title": "範例名稱"
}
response = requests.patch(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/rename/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"title": "範例名稱"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"contact": { // 輕量級 Contact Serializer，用於 Conversation List view
只包含 List view 必要的欄位，移除 inboxes 和 mcp_credentials
以避免 N+1 查詢問題
{
"id": string (uuid)
"name": string
"avatar"?: string (uri) // 非必填
"sourceId"?: string // 非必填
}
}
"inbox": {
{
"id": string (uuid)
"name": string
"channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
"unreadConversationsCount"?: integer // 非必填
"signAuth"?: // 非必填
{
"id": string (uuid)
"signSource": string (uuid)
"signParams": {
{
"keycloak":
{
"clientId": string
"url": string
"realm": string
}
"line":
{
"liffId": string
}
"ad":
{
"saml": string
}
}
}
}
}
}
"title": string
"lastMessage"?: { // 非必填
{
"id": string (uuid)
"type"?: string // 非必填
"content"?: string // 非必填
"contentPayload"?: object // 非必填
"feedback":
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 非必填
"updatedAt": string (timestamp)
}
"createdAt": string (timestamp)
"queryMetadata"?: object // 非必填
}
}
"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.
"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)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"contact": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"avatar": "https://example.com/file.jpg",
"sourceId": "回應字串"
},
"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": "回應字串"
}
}
}
},
"title": "回應字串",
"lastMessage": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "回應字串",
"content": "回應字串",
"contentPayload": null,
"feedback": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "回應字串",
"updatedAt": "回應字串"
},
"createdAt": "回應字串",
"queryMetadata": null
},
"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": "回應字串"
}
```
***
### 分享對話
POST `/api/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] | 否 | |
**請求結構範例**
```typescript
{
"shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
"permission"?: // 非必填
{
}
"title"?: string // 非必填
"description"?: string // 非必填
"groupIds"?: [ // 非必填
string (uuid)
]
"memberIds"?: [ // 非必填
string (uuid)
]
}
```
**請求範例值**
```json
{
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/conversations/{conversationPk}/share/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/conversations/{conversationPk}/share/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/conversations/{conversationPk}/share/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
"permission"?: // 非必填
{
}
"title"?: string // 非必填
"description"?: string // 非必填
"groupIds"?: [ // 非必填
string (uuid)
]
"memberIds"?: [ // 非必填
string (uuid)
]
}
```
**回應範例值**
```json
{
"shareScope": "organization",
"permission": {},
"title": "回應字串",
"description": "回應字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
***
### 分享對話
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] | 否 | |
**請求結構範例**
```typescript
{
"shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
"permission"?: // 非必填
{
}
"title"?: string // 非必填
"description"?: string // 非必填
"groupIds"?: [ // 非必填
string (uuid)
]
"memberIds"?: [ // 非必填
string (uuid)
]
}
```
**請求範例值**
```json
{
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/v1/conversations/{conversationPk}/share/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/conversations/{conversationPk}/share/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/conversations/{conversationPk}/share/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
"permission"?: // 非必填
{
}
"title"?: string // 非必填
"description"?: string // 非必填
"groupIds"?: [ // 非必填
string (uuid)
]
"memberIds"?: [ // 非必填
string (uuid)
]
}
```
**回應範例值**
```json
{
"shareScope": "organization",
"permission": {},
"title": "回應字串",
"description": "回應字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
***
### 快速分享對話
POST `/api/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] | 否 | |
**請求結構範例**
```typescript
{
"shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
"permission"?: // 非必填
{
}
"title"?: string // 非必填
"description"?: string // 非必填
"groupIds"?: [ // 非必填
string (uuid)
]
"memberIds"?: [ // 非必填
string (uuid)
]
}
```
**請求範例值**
```json
{
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/conversations/{conversationPk}/share/quick/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/conversations/{conversationPk}/share/quick/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/conversations/{conversationPk}/share/quick/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
"permission"?: // 非必填
{
}
"title"?: string // 非必填
"description"?: string // 非必填
"groupIds"?: [ // 非必填
string (uuid)
]
"memberIds"?: [ // 非必填
string (uuid)
]
}
```
**回應範例值**
```json
{
"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] | 否 | |
**請求結構範例**
```typescript
{
"shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
"permission"?: // 非必填
{
}
"title"?: string // 非必填
"description"?: string // 非必填
"groupIds"?: [ // 非必填
string (uuid)
]
"memberIds"?: [ // 非必填
string (uuid)
]
}
```
**請求範例值**
```json
{
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/v1/conversations/{conversationPk}/share/quick/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/conversations/{conversationPk}/share/quick/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/conversations/{conversationPk}/share/quick/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"shareScope": "organization",
"permission": {},
"title": "範例名稱",
"description": "範例字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"shareScope": string (enum: organization, group, member) // * `organization` - Organization
* `group` - Group
* `member` - Member
"permission"?: // 非必填
{
}
"title"?: string // 非必填
"description"?: string // 非必填
"groupIds"?: [ // 非必填
string (uuid)
]
"memberIds"?: [ // 非必填
string (uuid)
]
}
```
**回應範例值**
```json
{
"shareScope": "organization",
"permission": {},
"title": "回應字串",
"description": "回應字串",
"groupIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"memberIds": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
***
### 列出分享的對話
GET `/api/shared-conversations/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------- | -- | ------- | ---------------------------------------------- |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/shared-conversations/?page=1&pageSize=1" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/shared-conversations/?page=1&pageSize=1", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/shared-conversations/?page=1&pageSize=1"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/shared-conversations/?page=1&pageSize=1", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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)
}
]
}
```
**回應範例值**
```json
{
"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/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------- | -- | ------- | ---------------------------------------------- |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/shared-conversations/?page=1&pageSize=1", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/shared-conversations/?page=1&pageSize=1"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/shared-conversations/?page=1&pageSize=1", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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)
}
]
}
```
**回應範例值**
```json
{
"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/shared-conversations/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Shared Conversation. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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[]}
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "回應字串",
"description": "回應字串",
"permission": {},
"sharedBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"createdAt": "回應字串",
"conversationSnapshot": null
}
```
***
### 取得特定分享對話
GET `/api/shared-conversations/my-shares/`
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/shared-conversations/my-shares/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/shared-conversations/my-shares/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/shared-conversations/my-shares/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/shared-conversations/my-shares/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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)
}
```
**回應範例值**
```json
{
"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. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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[]}
}
```
**回應範例值**
```json
{
"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/`
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/shared-conversations/my-shares/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/shared-conversations/my-shares/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/shared-conversations/my-shares/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "回應字串",
"description": "回應字串",
"shareScope": {},
"permission": {},
"sharedBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"messageCount": 456,
"createdAt": "回應字串"
}
```
***
### 更新分享對話
PATCH `/api/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; |
**請求結構範例**
```typescript
{
"title"?: string // 非必填
"description"?: string // 非必填
"permission"?: string (enum: readonly, copy) // * `readonly` - Read Only
* `copy` - Copyable (非必填)
}
```
**請求範例值**
```json
{
"title": "範例名稱",
"description": "範例字串",
"permission": "readonly"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"title": "範例名稱",
"description": "範例字串",
"permission": "readonly"
};
axios.patch("https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"title": "範例名稱",
"description": "範例字串",
"permission": "readonly"
}
response = requests.patch(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"title": "範例名稱",
"description": "範例字串",
"permission": "readonly"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"title"?: string // 非必填
"description"?: string // 非必填
"permission"?: string (enum: readonly, copy) // * `readonly` - Read Only
* `copy` - Copyable (非必填)
}
```
**回應範例值**
```json
{
"title": "回應字串",
"description": "回應字串",
"permission": "readonly"
}
```
***
### 更新分享對話
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; |
**請求結構範例**
```typescript
{
"title"?: string // 非必填
"description"?: string // 非必填
"permission"?: string (enum: readonly, copy) // * `readonly` - Read Only
* `copy` - Copyable (非必填)
}
```
**請求範例值**
```json
{
"title": "範例名稱",
"description": "範例字串",
"permission": "readonly"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"title": "範例名稱",
"description": "範例字串",
"permission": "readonly"
};
axios.patch("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"title": "範例名稱",
"description": "範例字串",
"permission": "readonly"
}
response = requests.patch(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"title": "範例名稱",
"description": "範例字串",
"permission": "readonly"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"title"?: string // 非必填
"description"?: string // 非必填
"permission"?: string (enum: readonly, copy) // * `readonly` - Read Only
* `copy` - Copyable (非必填)
}
```
**回應範例值**
```json
{
"title": "回應字串",
"description": "回應字串",
"permission": "readonly"
}
```
***
### 刪除分享對話
DELETE `/api/shared-conversations/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Shared Conversation. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 刪除分享對話
DELETE `/api/v1/shared-conversations/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Shared Conversation. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 複製分享對話
POST `/api/shared-conversations/{id}/fork/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Shared Conversation. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {};
axios.post("https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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[]}
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "回應字串",
"description": "回應字串",
"permission": {},
"sharedBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"createdAt": "回應字串",
"conversationSnapshot": null
}
```
***
### 複製分享對話
POST `/api/v1/shared-conversations/{id}/fork/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | --------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Shared Conversation. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {};
axios.post("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/shared-conversations/550e8400-e29b-41d4-a716-446655440000/fork/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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[]}
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "回應字串",
"description": "回應字串",
"permission": {},
"sharedBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"createdAt": "回應字串",
"conversationSnapshot": null
}
```
***
### 建立訊息回饋
POST `/api/messages/{messagePk}/feedback/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------ | -- |
| `messagePk` | ✅ | string | |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------- | ------ | -- | -- |
| type | object | 是 | |
| suggestion | string | 否 | |
**請求結構範例**
```typescript
{
"type":
{
}
"suggestion"?: string // 非必填
}
```
**請求範例值**
```json
{
"type": {},
"suggestion": "範例字串"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/messages/{messagePk}/feedback/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": {},
"suggestion": "範例字串"
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"type": {},
"suggestion": "範例字串"
};
axios.post("https://api.maiagent.ai/api/messages/{messagePk}/feedback/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/messages/{messagePk}/feedback/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"type": {},
"suggestion": "範例字串"
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/messages/{messagePk}/feedback/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"type": {},
"suggestion": "範例字串"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 非必填
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "回應字串",
"updatedAt": "回應字串"
}
```
**狀態碼: 400 - 此訊息已有回饋，請使用 PATCH 方法更新**
***
### 建立訊息回饋
POST `/api/v1/messages/{messagePk}/feedback/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------ | -- |
| `messagePk` | ✅ | string | |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------- | ------ | -- | -- |
| type | object | 是 | |
| suggestion | string | 否 | |
**請求結構範例**
```typescript
{
"type":
{
}
"suggestion"?: string // 非必填
}
```
**請求範例值**
```json
{
"type": {},
"suggestion": "範例字串"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"type": {},
"suggestion": "範例字串"
};
axios.post("https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"type": {},
"suggestion": "範例字串"
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"type": {},
"suggestion": "範例字串"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 非必填
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "回應字串",
"updatedAt": "回應字串"
}
```
**狀態碼: 400 - 此訊息已有回饋，請使用 PATCH 方法更新**
***
### 更新訊息回饋
PUT `/api/messages/{messagePk}/feedback/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------ | ------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this 訊息回饋. |
| `messagePk` | ✅ | string | |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------- | ------ | -- | -- |
| type | object | 是 | |
| suggestion | string | 否 | |
**請求結構範例**
```typescript
{
"type":
{
}
"suggestion"?: string // 非必填
}
```
**請求範例值**
```json
{
"type": {},
"suggestion": "範例字串"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"type": {},
"suggestion": "範例字串"
};
axios.put("https://api.maiagent.ai/api/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"type": {},
"suggestion": "範例字串"
}
response = requests.put(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"type": {},
"suggestion": "範例字串"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 非必填
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 更新訊息回饋
PUT `/api/v1/messages/{messagePk}/feedback/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------ | ------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this 訊息回饋. |
| `messagePk` | ✅ | string | |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------- | ------ | -- | -- |
| type | object | 是 | |
| suggestion | string | 否 | |
**請求結構範例**
```typescript
{
"type":
{
}
"suggestion"?: string // 非必填
}
```
**請求範例值**
```json
{
"type": {},
"suggestion": "範例字串"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"type": {},
"suggestion": "範例字串"
};
axios.put("https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"type": {},
"suggestion": "範例字串"
}
response = requests.put(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"type": {},
"suggestion": "範例字串"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"type":
{
}
"suggestion"?: string // 非必填
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": {},
"suggestion": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 刪除訊息回饋
DELETE `/api/messages/{messagePk}/feedback/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------ | ------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this 訊息回饋. |
| `messagePk` | ✅ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ----------- |
| 204 | 成功刪除回饋 |
| 400 | 此回饋不屬於指定的訊息 |
***
### 刪除訊息回饋
DELETE `/api/v1/messages/{messagePk}/feedback/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------ | ------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this 訊息回饋. |
| `messagePk` | ✅ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/messages/{messagePk}/feedback/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ----------- |
| 204 | 成功刪除回饋 |
| 400 | 此回饋不屬於指定的訊息 |
***
### 取得對話紀錄列表
GET `/api/records/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| -------------------- | -- | ------- | ---------------------------------------------- |
| `chatbot` | ❌ | string | 篩選特定 AI 助理 (UUID) |
| `endDate` | ❌ | string | 結束日期（格式：YYYY-MM-DD，如：2025-01-31） |
| `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） |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/records/?chatbot=example&endDate=example&keyword=example&largeLanguageModel=example&page=1&pageSize=1&startDate=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/records/?chatbot=example&endDate=example&keyword=example&largeLanguageModel=example&page=1&pageSize=1&startDate=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/records/?chatbot=example&endDate=example&keyword=example&largeLanguageModel=example&page=1&pageSize=1&startDate=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/records/?chatbot=example&endDate=example&keyword=example&largeLanguageModel=example&page=1&pageSize=1&startDate=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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 // 回傳各個處理階段的時間統計
"usage": object // 回傳使用量統計，包含字數和 token 數
"citationNodes": [
{
"id": string
"text": string
"chatbotFileId": string
"fileName": string
}
]
"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 only for credit-mode organizations.
object
]
}
]
}
```
**回應範例值**
```json
{
"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": "回應字串"
}
],
"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": "回應範例描述"
}
]
}
]
}
```
***
### 取得對話紀錄列表
GET `/api/v1/records/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| -------------------- | -- | ------- | ---------------------------------------------- |
| `chatbot` | ❌ | string | 篩選特定 AI 助理 (UUID) |
| `endDate` | ❌ | string | 結束日期（格式：YYYY-MM-DD，如：2025-01-31） |
| `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） |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/records/?chatbot=example&endDate=example&keyword=example&largeLanguageModel=example&page=1&pageSize=1&startDate=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/records/?chatbot=example&endDate=example&keyword=example&largeLanguageModel=example&page=1&pageSize=1&startDate=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/records/?chatbot=example&endDate=example&keyword=example&largeLanguageModel=example&page=1&pageSize=1&startDate=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/records/?chatbot=example&endDate=example&keyword=example&largeLanguageModel=example&page=1&pageSize=1&startDate=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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 // 回傳各個處理階段的時間統計
"usage": object // 回傳使用量統計，包含字數和 token 數
"citationNodes": [
{
"id": string
"text": string
"chatbotFileId": string
"fileName": string
}
]
"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 only for credit-mode organizations.
object
]
}
]
}
```
**回應範例值**
```json
{
"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": "回應字串"
}
],
"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": "回應範例描述"
}
]
}
]
}
```
***
### 取得特定對話紀錄
GET `/api/records/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ------------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this Chatbot 紀錄. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/records/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/records/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/records/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/records/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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 // 回傳各個處理階段的時間統計
"usage": object // 回傳使用量統計，包含字數和 token 數
"citationNodes": [
{
"id": string
"text": string
"chatbotFileId": string
"fileName": string
}
]
"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 only for credit-mode organizations.
object
]
}
```
**回應範例值**
```json
{
"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": "回應字串"
}
],
"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": "回應範例描述"
}
]
}
```
**狀態碼: 404 - 找不到指定的對話記錄**
***
### 取得特定對話紀錄
GET `/api/records/export-excel-requests/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------ | -------------------------------- |
| `endDate` | ❌ | string | 結束日期（格式：YYYY-MM-DD，如：2025-01-31） |
| `keyword` | ❌ | string | 過濾包含特定關鍵字的對話記錄（同時搜尋用戶訊息和機器人回覆） |
| `startDate` | ❌ | string | 開始日期（格式：YYYY-MM-DD，如：2025-01-01） |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/records/export-excel-requests/?endDate=example&keyword=example&startDate=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/records/export-excel-requests/?endDate=example&keyword=example&startDate=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/records/export-excel-requests/?endDate=example&keyword=example&startDate=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/records/export-excel-requests/?endDate=example&keyword=example&startDate=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------- |
| 200 | Excel 檔案下載 |
***
### 取得特定對話紀錄
GET `/api/v1/records/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ------------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this Chatbot 紀錄. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/records/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/records/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/records/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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 // 回傳各個處理階段的時間統計
"usage": object // 回傳使用量統計，包含字數和 token 數
"citationNodes": [
{
"id": string
"text": string
"chatbotFileId": string
"fileName": string
}
]
"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 only for credit-mode organizations.
object
]
}
```
**回應範例值**
```json
{
"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": "回應字串"
}
],
"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": "回應範例描述"
}
]
}
```
**狀態碼: 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） |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------- |
| 200 | Excel 檔案下載 |
***
### 建立對話紀錄匯出請求
POST `/api/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。 |
**請求結構範例**
```typescript
{
"chatbot"?: string // 指定要匯出的 Chatbot UUID，支援逗號分隔多個 UUID。留空則匯出組織內所有有權限的 Chatbot。 (非必填)
"chatbotId"?: string (uuid) // 指定要匯出的 Chatbot UUID（chatbot 的別名，僅支援單個 UUID）。 (非必填)
"largeLanguageModel"?: string // 指定要匯出的大型語言模型 UUID，支援逗號分隔多個 UUID。 (非必填)
}
```
**請求範例值**
```json
{
"chatbot": "範例字串",
"chatbotId": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "範例字串"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"chatbot": "範例字串",
"chatbotId": "550e8400-e29b-41d4-a716-446655440000",
"keyword": "範例字串",
"largeLanguageModel": "範例字串",
"startDate": "範例字串",
"endDate": "範例字串"
};
axios.post("https://api.maiagent.ai/api/records/export-excel-requests/?endDate=example&keyword=example&startDate=example", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/records/export-excel-requests/?endDate=example&keyword=example&startDate=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"chatbot": "範例字串",
"chatbotId": "550e8400-e29b-41d4-a716-446655440000",
"keyword": "範例字串",
"largeLanguageModel": "範例字串",
"startDate": "範例字串",
"endDate": "範例字串"
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/records/export-excel-requests/?endDate=example&keyword=example&startDate=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"chatbot": "範例字串",
"chatbotId": "550e8400-e29b-41d4-a716-446655440000",
"keyword": "範例字串",
"largeLanguageModel": "範例字串",
"startDate": "範例字串",
"endDate": "範例字串"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------- |
| 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。 |
**請求結構範例**
```typescript
{
"chatbot"?: string // 指定要匯出的 Chatbot UUID，支援逗號分隔多個 UUID。留空則匯出組織內所有有權限的 Chatbot。 (非必填)
"chatbotId"?: string (uuid) // 指定要匯出的 Chatbot UUID（chatbot 的別名，僅支援單個 UUID）。 (非必填)
"largeLanguageModel"?: string // 指定要匯出的大型語言模型 UUID，支援逗號分隔多個 UUID。 (非必填)
}
```
**請求範例值**
```json
{
"chatbot": "範例字串",
"chatbotId": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "範例字串"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"chatbot": "範例字串",
"chatbotId": "550e8400-e29b-41d4-a716-446655440000",
"keyword": "範例字串",
"largeLanguageModel": "範例字串",
"startDate": "範例字串",
"endDate": "範例字串"
};
axios.post("https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=example", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"chatbot": "範例字串",
"chatbotId": "550e8400-e29b-41d4-a716-446655440000",
"keyword": "範例字串",
"largeLanguageModel": "範例字串",
"startDate": "範例字串",
"endDate": "範例字串"
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/records/export-excel-requests/?endDate=example&keyword=example&startDate=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"chatbot": "範例字串",
"chatbotId": "550e8400-e29b-41d4-a716-446655440000",
"keyword": "範例字串",
"largeLanguageModel": "範例字串",
"startDate": "範例字串",
"endDate": "範例字串"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------- |
| 200 | Excel 檔案下載 |
***
### 取得對話紀錄匯出狀態
GET `/api/records/export-excel-requests/{exportId}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------- | -- | ------ | -- |
| `exportId` | ✅ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/records/export-excel-requests/{exportId}/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/records/export-excel-requests/{exportId}/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/records/export-excel-requests/{exportId}/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/records/export-excel-requests/{exportId}/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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 和 reranker）
"usage": object // 回傳使用量統計，包含字數和 token 數
"llm":
{
"id": string (uuid)
"name": string
}
"createdAt": string (timestamp)
"conversationId": string (uuid)
}
```
**回應範例值**
```json
{
"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"
}
```
***
### 取得對話紀錄匯出狀態
GET `/api/v1/records/export-excel-requests/{exportId}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------- | -- | ------ | -- |
| `exportId` | ✅ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```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 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/records/export-excel-requests/{exportId}/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/records/export-excel-requests/{exportId}/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/records/export-excel-requests/{exportId}/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"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 和 reranker）
"usage": object // 回傳使用量統計，包含字數和 token 數
"llm":
{
"id": string (uuid)
"name": string
}
"createdAt": string (timestamp)
"conversationId": string (uuid)
}
```
**回應範例值**
```json
{
"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"
}
```
***