# 對話與訊息
### 發送訊息 (串流)
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"
}
```
***
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.maiagent.ai/api/api-reference/dui-hua-he-xun-xi.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.