# 聯絡人
### 列出聯絡人
GET `/api/contacts/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------- | -- | ------- | ---------------------------------------------- |
| `inbox` | ❌ | string | Deprecated: Use inboxes instead |
| `inboxes` | ❌ | string | 對話平台 ID (用於過濾特定 inbox 的聯絡人) |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | 姓名或來源ID搜尋 |
| `search` | ❌ | string | 全文搜尋 |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=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/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=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/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=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/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=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)
"inboxes"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 向前相容欄位：單一 inbox，若同時提供 inboxes 則忽略此欄位 (非必填)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: string (uri) // 聯絡人頭像 URL，支援完整 URL 或相對路徑 (非必填)
"phoneNumber"?: string // 非必填
"email"?: string (email) // 非必填
"sourceId"?: string // 非必填
"queryMetadata"?: object // 非必填
"metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
[
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
},
{
"id": "user2_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user2",
"avatar": "avatar_url",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata",
"createdAt": "1751875400000",
"updatedAt": "1751875400000"
}
]
]
}
```
***
### 列出聯絡人
GET `/api/v1/contacts/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------- | -- | ------- | ---------------------------------------------- |
| `inbox` | ❌ | string | Deprecated: Use inboxes instead |
| `inboxes` | ❌ | string | 對話平台 ID (用於過濾特定 inbox 的聯絡人) |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | 姓名或來源ID搜尋 |
| `search` | ❌ | string | 全文搜尋 |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=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/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=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/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=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/contacts/?inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=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)
"inboxes"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 向前相容欄位：單一 inbox，若同時提供 inboxes 則忽略此欄位 (非必填)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: string (uri) // 聯絡人頭像 URL，支援完整 URL 或相對路徑 (非必填)
"phoneNumber"?: string // 非必填
"email"?: string (email) // 非必填
"sourceId"?: string // 非必填
"queryMetadata"?: object // 非必填
"metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
[
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
},
{
"id": "user2_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user2",
"avatar": "avatar_url",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata",
"createdAt": "1751875400000",
"updatedAt": "1751875400000"
}
]
]
}
```
***
### 建立聯絡人
POST `/api/contacts/`
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/contacts/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inboxes": [
{
"id": "inbox_uuid"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VIP"
},
{
"key": "偏好語言",
"value": "繁體中文"
}
]
}'
# 請確認在執行前替換 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 = {
"inboxes": [
{
"id": "inbox_uuid"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VIP"
},
{
"key": "偏好語言",
"value": "繁體中文"
}
]
};
axios.post("https://api.maiagent.ai/api/contacts/", 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/contacts/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"inboxes": [
{
"id": "inbox_uuid"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VIP"
},
{
"key": "偏好語言",
"value": "繁體中文"
}
]
}
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/contacts/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"inboxes": [
{
"id": "inbox_uuid"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VIP"
},
{
"key": "偏好語言",
"value": "繁體中文"
}
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 向前相容欄位：單一 inbox，若同時提供 inboxes 則忽略此欄位 (非必填)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: string (uri) // 聯絡人頭像 URL，支援完整 URL 或相對路徑 (非必填)
"phoneNumber"?: string // 非必填
"email"?: string (email) // 非必填
"sourceId"?: string // 非必填
"queryMetadata"?: object // 非必填
"metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
}
```
***
### 建立聯絡人
POST `/api/v1/contacts/`
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/contacts/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inboxes": [
{
"id": "inbox_uuid"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VIP"
},
{
"key": "偏好語言",
"value": "繁體中文"
}
]
}'
# 請確認在執行前替換 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 = {
"inboxes": [
{
"id": "inbox_uuid"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VIP"
},
{
"key": "偏好語言",
"value": "繁體中文"
}
]
};
axios.post("https://api.maiagent.ai/api/v1/contacts/", 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/contacts/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"inboxes": [
{
"id": "inbox_uuid"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VIP"
},
{
"key": "偏好語言",
"value": "繁體中文"
}
]
}
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/contacts/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"inboxes": [
{
"id": "inbox_uuid"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VIP"
},
{
"key": "偏好語言",
"value": "繁體中文"
}
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 向前相容欄位：單一 inbox，若同時提供 inboxes 則忽略此欄位 (非必填)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: string (uri) // 聯絡人頭像 URL，支援完整 URL 或相對路徑 (非必填)
"phoneNumber"?: string // 非必填
"email"?: string (email) // 非必填
"sourceId"?: string // 非必填
"queryMetadata"?: object // 非必填
"metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
}
```
***
### 取得聯絡人詳情
GET `/api/contacts/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/contacts/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/contacts/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/contacts/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/contacts/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)
"inboxes"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 向前相容欄位：單一 inbox，若同時提供 inboxes 則忽略此欄位 (非必填)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: string (uri) // 聯絡人頭像 URL，支援完整 URL 或相對路徑 (非必填)
"phoneNumber"?: string // 非必填
"email"?: string (email) // 非必填
"sourceId"?: string // 非必填
"queryMetadata"?: object // 非必填
"metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
}
```
***
### 取得聯絡人詳情
GET `/api/v1/contacts/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/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/contacts/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/contacts/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/contacts/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)
"inboxes"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 向前相容欄位：單一 inbox，若同時提供 inboxes 則忽略此欄位 (非必填)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: string (uri) // 聯絡人頭像 URL，支援完整 URL 或相對路徑 (非必填)
"phoneNumber"?: string // 非必填
"email"?: string (email) // 非必填
"sourceId"?: string // 非必填
"queryMetadata"?: object // 非必填
"metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
}
```
***
### 更新聯絡人
PUT `/api/contacts/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------- | -------------- | -- | ----------------- |
| name | string | 否 | 聯絡人姓名 |
| inboxes | array\[object] | 否 | 對話平台列表（新版格式） |
| inbox | object | 否 | 單一對話平台（舊版格式，向前相容） |
| inbox.id | string (uuid) | 是 | 對話平台 ID |
| avatar | string | 否 | 頭像URL |
| sourceId | string | 否 | 來源ID |
| queryMetadata | string | 否 | 查詢元資料 |
| metadata | array\[object] | 否 | 自訂聯絡人屬性列表 |
**請求結構範例**
```typescript
{
"name"?: string // 聯絡人姓名 (非必填)
"inboxes"?: [ // 對話平台列表（新版格式） (非必填)
{
"id": string (uuid) // 對話平台 ID
}
]
"inbox"?: { // 單一對話平台（舊版格式，向前相容） (非必填)
{
"id": string (uuid) // 對話平台 ID
}
}
"avatar"?: string // 頭像URL (非必填)
"sourceId"?: string // 來源ID (非必填)
"queryMetadata"?: string // 查詢元資料 (非必填)
"metadata"?: [ // 自訂聯絡人屬性列表 (非必填)
{
"key": string // 屬性名稱
"value": string // 屬性值
"updatedAt"?: string // 更新時間（ISO 格式，可選，未提供則自動填入） (非必填)
}
]
}
```
**請求範例值**
```json
{
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}'
# 請確認在執行前替換 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 = {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
};
axios.put("https://api.maiagent.ai/api/contacts/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/contacts/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}
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/contacts/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 向前相容欄位：單一 inbox，若同時提供 inboxes 則忽略此欄位 (非必填)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: string (uri) // 聯絡人頭像 URL，支援完整 URL 或相對路徑 (非必填)
"phoneNumber"?: string // 非必填
"email"?: string (email) // 非必填
"sourceId"?: string // 非必填
"queryMetadata"?: object // 非必填
"metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
}
```
***
### 更新聯絡人
PUT `/api/v1/contacts/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------- | -------------- | -- | ----------------- |
| name | string | 否 | 聯絡人姓名 |
| inboxes | array\[object] | 否 | 對話平台列表（新版格式） |
| inbox | object | 否 | 單一對話平台（舊版格式，向前相容） |
| inbox.id | string (uuid) | 是 | 對話平台 ID |
| avatar | string | 否 | 頭像URL |
| sourceId | string | 否 | 來源ID |
| queryMetadata | string | 否 | 查詢元資料 |
| metadata | array\[object] | 否 | 自訂聯絡人屬性列表 |
**請求結構範例**
```typescript
{
"name"?: string // 聯絡人姓名 (非必填)
"inboxes"?: [ // 對話平台列表（新版格式） (非必填)
{
"id": string (uuid) // 對話平台 ID
}
]
"inbox"?: { // 單一對話平台（舊版格式，向前相容） (非必填)
{
"id": string (uuid) // 對話平台 ID
}
}
"avatar"?: string // 頭像URL (非必填)
"sourceId"?: string // 來源ID (非必填)
"queryMetadata"?: string // 查詢元資料 (非必填)
"metadata"?: [ // 自訂聯絡人屬性列表 (非必填)
{
"key": string // 屬性名稱
"value": string // 屬性值
"updatedAt"?: string // 更新時間（ISO 格式，可選，未提供則自動填入） (非必填)
}
]
}
```
**請求範例值**
```json
{
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}'
# 請確認在執行前替換 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 = {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
};
axios.put("https://api.maiagent.ai/api/v1/contacts/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/contacts/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}
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/contacts/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 向前相容欄位：單一 inbox，若同時提供 inboxes 則忽略此欄位 (非必填)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: string (uri) // 聯絡人頭像 URL，支援完整 URL 或相對路徑 (非必填)
"phoneNumber"?: string // 非必填
"email"?: string (email) // 非必填
"sourceId"?: string // 非必填
"queryMetadata"?: object // 非必填
"metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
}
```
***
### 部分更新聯絡人
PATCH `/api/contacts/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------- | -------------- | -- | ----------------- |
| name | string | 否 | 聯絡人姓名 |
| inboxes | array\[object] | 否 | 對話平台列表（新版格式） |
| inbox | object | 否 | 單一對話平台（舊版格式，向前相容） |
| inbox.id | string (uuid) | 是 | 對話平台 ID |
| avatar | string | 否 | 頭像URL |
| sourceId | string | 否 | 來源ID |
| queryMetadata | string | 否 | 查詢元資料 |
| metadata | array\[object] | 否 | 自訂聯絡人屬性列表 |
**請求結構範例**
```typescript
{
"name"?: string // 聯絡人姓名 (非必填)
"inboxes"?: [ // 對話平台列表（新版格式） (非必填)
{
"id": string (uuid) // 對話平台 ID
}
]
"inbox"?: { // 單一對話平台（舊版格式，向前相容） (非必填)
{
"id": string (uuid) // 對話平台 ID
}
}
"avatar"?: string // 頭像URL (非必填)
"sourceId"?: string // 來源ID (非必填)
"queryMetadata"?: string // 查詢元資料 (非必填)
"metadata"?: [ // 自訂聯絡人屬性列表 (非必填)
{
"key": string // 屬性名稱
"value": string // 屬性值
"updatedAt"?: string // 更新時間（ISO 格式，可選，未提供則自動填入） (非必填)
}
]
}
```
**請求範例值**
```json
{
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}'
# 請確認在執行前替換 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 = {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
};
axios.patch("https://api.maiagent.ai/api/contacts/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/contacts/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}
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/contacts/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 向前相容欄位：單一 inbox，若同時提供 inboxes 則忽略此欄位 (非必填)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: string (uri) // 聯絡人頭像 URL，支援完整 URL 或相對路徑 (非必填)
"phoneNumber"?: string // 非必填
"email"?: string (email) // 非必填
"sourceId"?: string // 非必填
"queryMetadata"?: object // 非必填
"metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
}
```
***
### 部分更新聯絡人
PATCH `/api/v1/contacts/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------- | -------------- | -- | ----------------- |
| name | string | 否 | 聯絡人姓名 |
| inboxes | array\[object] | 否 | 對話平台列表（新版格式） |
| inbox | object | 否 | 單一對話平台（舊版格式，向前相容） |
| inbox.id | string (uuid) | 是 | 對話平台 ID |
| avatar | string | 否 | 頭像URL |
| sourceId | string | 否 | 來源ID |
| queryMetadata | string | 否 | 查詢元資料 |
| metadata | array\[object] | 否 | 自訂聯絡人屬性列表 |
**請求結構範例**
```typescript
{
"name"?: string // 聯絡人姓名 (非必填)
"inboxes"?: [ // 對話平台列表（新版格式） (非必填)
{
"id": string (uuid) // 對話平台 ID
}
]
"inbox"?: { // 單一對話平台（舊版格式，向前相容） (非必填)
{
"id": string (uuid) // 對話平台 ID
}
}
"avatar"?: string // 頭像URL (非必填)
"sourceId"?: string // 來源ID (非必填)
"queryMetadata"?: string // 查詢元資料 (非必填)
"metadata"?: [ // 自訂聯絡人屬性列表 (非必填)
{
"key": string // 屬性名稱
"value": string // 屬性值
"updatedAt"?: string // 更新時間（ISO 格式，可選，未提供則自動填入） (非必填)
}
]
}
```
**請求範例值**
```json
{
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}'
# 請確認在執行前替換 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 = {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
};
axios.patch("https://api.maiagent.ai/api/v1/contacts/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/contacts/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}
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/contacts/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "updated@example.com",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata",
"metadata": [
{
"key": "客戶等級",
"value": "VVIP"
},
{
"key": "偏好語言",
"value": "日本語"
}
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"inboxes"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"inbox"?: // 向前相容欄位：單一 inbox，若同時提供 inboxes 則忽略此欄位 (非必填)
{
"id": string (uuid)
"name": string
}
"name": string
"avatar"?: string (uri) // 聯絡人頭像 URL，支援完整 URL 或相對路徑 (非必填)
"phoneNumber"?: string // 非必填
"email"?: string (email) // 非必填
"sourceId"?: string // 非必填
"queryMetadata"?: object // 非必填
"metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "user1@example.com",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
}
```
***
### 刪除聯絡人
DELETE `/api/contacts/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/contacts/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/contacts/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/contacts/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/contacts/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 |
| 400 | 聯絡人還有關聯的對話，無法刪除 |
***
### 刪除聯絡人
DELETE `/api/v1/contacts/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/contacts/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/contacts/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/contacts/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/contacts/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 |
| 400 | 聯絡人還有關聯的對話，無法刪除 |
***
### 取得聯絡人的對話列表
GET `/api/contacts/{id}/conversations/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------- | -- | ------- | ----------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
| `inbox` | ❌ | string | 按單一 inbox ID 過濾（UUID 格式） |
| `inboxes` | ❌ | string | 按多個 inbox IDs 過濾（逗號分隔，如：uuid1,uuid2 或使用多個 inboxes 參數） |
| `keyword` | ❌ | string | 搜尋對話中的訊息內容（不區分大小寫） |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=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/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=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/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=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/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=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)
"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/contacts/{id}/conversations/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------- | -- | ------- | ----------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
| `inbox` | ❌ | string | 按單一 inbox ID 過濾（UUID 格式） |
| `inboxes` | ❌ | string | 按多個 inbox IDs 過濾（逗號分隔，如：uuid1,uuid2 或使用多個 inboxes 參數） |
| `keyword` | ❌ | string | 搜尋對話中的訊息內容（不區分大小寫） |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=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/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=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/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=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/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=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)
"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/contacts/{id}/conversations/latest/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| --------- | -- | ------ | ----------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
| `inbox` | ❌ | string | 按單一 inbox ID 過濾（UUID 格式） |
| `inboxes` | ❌ | string | 按多個 inbox IDs 過濾（逗號分隔，如：uuid1,uuid2 或使用多個 inboxes 參數） |
| `keyword` | ❌ | string | 搜尋對話中的訊息內容（不區分大小寫） |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/latest/?inbox=example&inboxes=example&keyword=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/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/latest/?inbox=example&inboxes=example&keyword=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/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/latest/?inbox=example&inboxes=example&keyword=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/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/latest/?inbox=example&inboxes=example&keyword=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)
"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": "回應字串"
}
```
**狀態碼: 404 - No response body**
***
### 取得聯絡人最新對話
GET `/api/v1/contacts/{id}/conversations/latest/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| --------- | -- | ------ | ----------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Contact. |
| `inbox` | ❌ | string | 按單一 inbox ID 過濾（UUID 格式） |
| `inboxes` | ❌ | string | 按多個 inbox IDs 過濾（逗號分隔，如：uuid1,uuid2 或使用多個 inboxes 參數） |
| `keyword` | ❌ | string | 搜尋對話中的訊息內容（不區分大小寫） |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/latest/?inbox=example&inboxes=example&keyword=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/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/latest/?inbox=example&inboxes=example&keyword=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/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/latest/?inbox=example&inboxes=example&keyword=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/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/latest/?inbox=example&inboxes=example&keyword=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)
"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": "回應字串"
}
```
**狀態碼: 404 - No response body**
***
### 群發訊息
POST `/api/contacts/broadcast-message/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ----------------- | -------------- | -- | ------------------------------------------------- |
| contactIds | array\[string] | 否 | \[正向指定模式] 要發送訊息的 contact ID 列表 |
| inboxId | string (uuid) | 否 | \[反向排除/全部發送模式] Inbox ID，會發送給該 inbox 下的所有 contacts |
| excludeContactIds | array\[string] | 否 | \[反向排除模式] 要排除的 contact ID 列表，需配合 inbox\_id 使用 |
| message | string | 是 | 要發送的訊息內容 |
**請求結構範例**
```typescript
{
"contactIds"?: [ // [正向指定模式] 要發送訊息的 contact ID 列表 (非必填)
string (uuid)
]
"inboxId"?: string (uuid) // [反向排除/全部發送模式] Inbox ID，會發送給該 inbox 下的所有 contacts (非必填)
"excludeContactIds"?: [ // [反向排除模式] 要排除的 contact ID 列表，需配合 inbox_id 使用 (非必填)
string (uuid)
]
"message": string // 要發送的訊息內容
}
```
**請求範例值**
```json
{
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"excludeContactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"message": "這是一個範例訊息"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/contacts/broadcast-message/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"excludeContactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"message": "這是一個範例訊息"
}'
# 請確認在執行前替換 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 = {
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"excludeContactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"message": "這是一個範例訊息"
};
axios.post("https://api.maiagent.ai/api/contacts/broadcast-message/", 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/contacts/broadcast-message/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"excludeContactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"message": "這是一個範例訊息"
}
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/contacts/broadcast-message/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"excludeContactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"message": "這是一個範例訊息"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"results"?: [ // 非必填
{
"contact_id"?: string (uuid) // 非必填
"conversation_id"?: string (uuid) // 非必填
"message_id"?: string (uuid) // 非必填
"status"?: string // 非必填
}
]
"errors"?: [ // 非必填
{
"contact_id"?: string (uuid) // 非必填
"error"?: string // 非必填
}
]
"total_contacts"?: integer // 非必填
"success_count"?: integer // 非必填
"error_count"?: integer // 非必填
}
```
**回應範例值**
```json
{
"results": [
{
"contact_id": "550e8400-e29b-41d4-a716-446655440000",
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"message_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "success"
}
],
"errors": [
{
"contact_id": "550e8400-e29b-41d4-a716-446655440000",
"error": "回應字串"
}
],
"total_contacts": 456,
"success_count": 456,
"error_count": 456
}
```
***
### 群發訊息
POST `/api/v1/contacts/broadcast-message/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ----------------- | -------------- | -- | ------------------------------------------------- |
| contactIds | array\[string] | 否 | \[正向指定模式] 要發送訊息的 contact ID 列表 |
| inboxId | string (uuid) | 否 | \[反向排除/全部發送模式] Inbox ID，會發送給該 inbox 下的所有 contacts |
| excludeContactIds | array\[string] | 否 | \[反向排除模式] 要排除的 contact ID 列表，需配合 inbox\_id 使用 |
| message | string | 是 | 要發送的訊息內容 |
**請求結構範例**
```typescript
{
"contactIds"?: [ // [正向指定模式] 要發送訊息的 contact ID 列表 (非必填)
string (uuid)
]
"inboxId"?: string (uuid) // [反向排除/全部發送模式] Inbox ID，會發送給該 inbox 下的所有 contacts (非必填)
"excludeContactIds"?: [ // [反向排除模式] 要排除的 contact ID 列表，需配合 inbox_id 使用 (非必填)
string (uuid)
]
"message": string // 要發送的訊息內容
}
```
**請求範例值**
```json
{
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"excludeContactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"message": "這是一個範例訊息"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/contacts/broadcast-message/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"excludeContactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"message": "這是一個範例訊息"
}'
# 請確認在執行前替換 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 = {
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"excludeContactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"message": "這是一個範例訊息"
};
axios.post("https://api.maiagent.ai/api/v1/contacts/broadcast-message/", 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/contacts/broadcast-message/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"excludeContactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"message": "這是一個範例訊息"
}
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/contacts/broadcast-message/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"inboxId": "550e8400-e29b-41d4-a716-446655440000",
"excludeContactIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"message": "這是一個範例訊息"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"results"?: [ // 非必填
{
"contact_id"?: string (uuid) // 非必填
"conversation_id"?: string (uuid) // 非必填
"message_id"?: string (uuid) // 非必填
"status"?: string // 非必填
}
]
"errors"?: [ // 非必填
{
"contact_id"?: string (uuid) // 非必填
"error"?: string // 非必填
}
]
"total_contacts"?: integer // 非必填
"success_count"?: integer // 非必填
"error_count"?: integer // 非必填
}
```
**回應範例值**
```json
{
"results": [
{
"contact_id": "550e8400-e29b-41d4-a716-446655440000",
"conversation_id": "550e8400-e29b-41d4-a716-446655440000",
"message_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "success"
}
],
"errors": [
{
"contact_id": "550e8400-e29b-41d4-a716-446655440000",
"error": "回應字串"
}
],
"total_contacts": 456,
"success_count": 456,
"error_count": 456
}
```
***