聯絡人
列出聯絡人
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
全文搜尋
程式碼範例
# 呼叫 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 並核對請求資料。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);
});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)<?php
require 'vendor/autoload.php';
$client = new GuzzleHttp\Client();
try {
$response = $client->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();
}
?>回應內容
狀態碼: 200
回應結構範例
{
"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 // 非必填
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}回應範例值
{
"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/
程式碼範例
# 呼叫 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": "[email protected]",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata"
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。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": "[email protected]",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata"
};
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);
});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": "[email protected]",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata"
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)<?php
require 'vendor/autoload.php';
$client = new GuzzleHttp\Client();
try {
$response = $client->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": "[email protected]",
"sourceId": "self defined source id",
"queryMetadata": "self defined query metadata"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>回應內容
狀態碼: 201
回應結構範例
{
"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 // 非必填
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}回應範例值
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "[email protected]",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
}獲取聯絡人詳情
GET /api/contacts/{id}/
參數
參數名稱
必填
類型
說明
id
✅
string
A UUID string identifying this Contact.
程式碼範例
# 呼叫 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 並核對請求資料。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);
});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)<?php
require 'vendor/autoload.php';
$client = new GuzzleHttp\Client();
try {
$response = $client->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();
}
?>回應內容
狀態碼: 200
回應結構範例
{
"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 // 非必填
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}回應範例值
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "[email protected]",
"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
否
查詢元資料
請求結構範例
{
"name"?: string // 聯絡人姓名 (非必填)
"inboxes"?: [ // 對話平台列表（新版格式） (非必填)
{
"id": string (uuid) // 對話平台 ID
}
]
"inbox"?: { // 單一對話平台（舊版格式，向前相容） (非必填)
{
"id": string (uuid) // 對話平台 ID
}
}
"avatar"?: string // 頭像URL (非必填)
"sourceId"?: string // 來源ID (非必填)
"queryMetadata"?: string // 查詢元資料 (非必填)
}請求範例值
{
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "[email protected]",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata"
}程式碼範例
# 呼叫 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": "[email protected]",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata"
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。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": "[email protected]",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata"
};
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);
});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": "[email protected]",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata"
}
response = requests.put(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)<?php
require 'vendor/autoload.php';
$client = new GuzzleHttp\Client();
try {
$response = $client->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": "[email protected]",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>回應內容
狀態碼: 200
回應結構範例
{
"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 // 非必填
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}回應範例值
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "[email protected]",
"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
否
查詢元資料
請求結構範例
{
"name"?: string // 聯絡人姓名 (非必填)
"inboxes"?: [ // 對話平台列表（新版格式） (非必填)
{
"id": string (uuid) // 對話平台 ID
}
]
"inbox"?: { // 單一對話平台（舊版格式，向前相容） (非必填)
{
"id": string (uuid) // 對話平台 ID
}
}
"avatar"?: string // 頭像URL (非必填)
"sourceId"?: string // 來源ID (非必填)
"queryMetadata"?: string // 查詢元資料 (非必填)
}請求範例值
{
"inboxes": [
{
"id": "new_inbox_uuid"
}
],
"name": "updated_user_name",
"avatar": "updated_avatar_url",
"phoneNumber": 987654321,
"email": "[email protected]",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata"
}程式碼範例
# 呼叫 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": "[email protected]",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata"
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。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": "[email protected]",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata"
};
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);
});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": "[email protected]",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata"
}
response = requests.patch(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)<?php
require 'vendor/autoload.php';
$client = new GuzzleHttp\Client();
try {
$response = $client->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": "[email protected]",
"sourceId": "updated_source_id",
"queryMetadata": "updated_query_metadata"
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>回應內容
狀態碼: 200
回應結構範例
{
"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 // 非必填
"mcpCredentials": string // 聯絡人的 MCP 認證憑證列表
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}回應範例值
{
"id": "user1_uuid",
"inboxes": [
{
"id": "inbox_uuid",
"name": "inbox_name"
}
],
"name": "user1",
"avatar": "",
"phoneNumber": 912345678,
"email": "[email protected]",
"sourceId": null,
"queryMetadata": null,
"createdAt": "1751875361000",
"updatedAt": "1751875361000"
}刪除聯絡人
DELETE /api/contacts/{id}/
參數
參數名稱
必填
類型
說明
id
✅
string
A UUID string identifying this Contact.
程式碼範例
# 呼叫 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 並核對請求資料。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);
});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)<?php
require 'vendor/autoload.php';
$client = new GuzzleHttp\Client();
try {
$response = $client->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();
}
?>回應內容
狀態碼
說明
204
No response body
400
聯絡人還有關聯的對話，無法刪除
Last updated
Was this helpful?