聯絡人

列出聯絡人

GET /api/v1/contacts/

參數

參數名稱	必填	類型	說明
channels	❌	array	Multiple values may be separated by commas.
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	全文搜尋
tags	❌	array	Multiple values may be separated by commas.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/?channels=example&inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example&tags=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/contacts/?channels=example&inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example&tags=example", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/contacts/?channels=example&inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example&tags=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

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/contacts/?channels=example&inbox=550e8400-e29b-41d4-a716-446655440000&inboxes=example&page=1&pageSize=1&query=example&search=example&tags=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 // 非必填
      "metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
      "mcpCredentials": [ // 聯絡人的 MCP 認證憑證列表
        object
      ]
      "apiCredentials": [ // 聯絡人的 API 認證憑證列表
        object
      ]
      "contactConnectors": [ // 聯絡人的 Connector OAuth 授權列表（不含 token 本體）
        object
      ]
      "tags": [
        {
          "id": string (uuid)
          "name": string
          "createdAt": string (timestamp)
          "updatedAt": string (timestamp)
        }
      ]
      "preChatFieldIndex": object // 來自此 Contact 所屬 inboxes 的 pre-chat form 欄位設定，mapping {field_id: {label: {locale: text}}}，前端用來把 metadata 的 UUID key 解析成顯示名稱
      "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/v1/contacts/

程式碼範例

Shell/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": "[e-mail]",
    "sourceId": "self defined source id",
    "queryMetadata": "self defined query metadata",
    "metadata": [
      {
        "key": "客戶等級",
        "value": "VIP"
      },
      {
        "key": "偏好語言",
        "value": "繁體中文"
      }
    ]
  }'

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

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": "[e-mail]",
    "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);
  });

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": "[e-mail]",
      "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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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": "[e-mail]",
            "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();
}
?>

回應內容

狀態碼: 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 // 非必填
  "metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
  "mcpCredentials": [ // 聯絡人的 MCP 認證憑證列表
    object
  ]
  "apiCredentials": [ // 聯絡人的 API 認證憑證列表
    object
  ]
  "contactConnectors": [ // 聯絡人的 Connector OAuth 授權列表（不含 token 本體）
    object
  ]
  "tags": [
    {
      "id": string (uuid)
      "name": string
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
  "preChatFieldIndex": object // 來自此 Contact 所屬 inboxes 的 pre-chat form 欄位設定，mapping {field_id: {label: {locale: text}}}，前端用來把 metadata 的 UUID key 解析成顯示名稱
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

取得聯絡人詳情

GET /api/v1/contacts/{id}/

參數

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

程式碼範例

Shell/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 並核對請求資料。

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);
  });

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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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();
}
?>

回應內容

狀態碼: 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 // 非必填
  "metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
  "mcpCredentials": [ // 聯絡人的 MCP 認證憑證列表
    object
  ]
  "apiCredentials": [ // 聯絡人的 API 認證憑證列表
    object
  ]
  "contactConnectors": [ // 聯絡人的 Connector OAuth 授權列表（不含 token 本體）
    object
  ]
  "tags": [
    {
      "id": string (uuid)
      "name": string
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
  "preChatFieldIndex": object // 來自此 Contact 所屬 inboxes 的 pre-chat form 欄位設定，mapping {field_id: {label: {locale: text}}}，前端用來把 metadata 的 UUID key 解析成顯示名稱
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

取得聯絡人詳情

GET /api/v1/contacts/bulk-import-template/

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/bulk-import-template/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/contacts/bulk-import-template/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/contacts/bulk-import-template/"
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

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/contacts/bulk-import-template/", [
        '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 // 非必填
  "metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
  "mcpCredentials": [ // 聯絡人的 MCP 認證憑證列表
    object
  ]
  "apiCredentials": [ // 聯絡人的 API 認證憑證列表
    object
  ]
  "contactConnectors": [ // 聯絡人的 Connector OAuth 授權列表（不含 token 本體）
    object
  ]
  "tags": [
    {
      "id": string (uuid)
      "name": string
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
  "preChatFieldIndex": object // 來自此 Contact 所屬 inboxes 的 pre-chat form 欄位設定，mapping {field_id: {label: {locale: text}}}，前端用來把 metadata 的 UUID key 解析成顯示名稱
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "inboxes": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串"
  },
  "name": "回應字串",
  "avatar": "https://example.com/file.jpg",
  "phoneNumber": "回應字串",
  "email": "[e-mail]",
  "sourceId": "回應字串",
  "queryMetadata": null,
  "metadata": null,
  "mcpCredentials": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    }
  ],
  "apiCredentials": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    }
  ],
  "contactConnectors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    }
  ],
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "createdAt": "回應字串",
      "updatedAt": "回應字串"
    }
  ],
  "preChatFieldIndex": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

取得聯絡人詳情

GET /api/v1/contacts/connector-management/

程式碼範例

Shell/Bash

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

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

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/contacts/connector-management/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/contacts/connector-management/"
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

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/contacts/connector-management/", [
        '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	No response body

---

更新聯絡人

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]	否	自訂聯絡人屬性列表

請求結構範例

{
  "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 格式，可選，未提供則自動填入） (非必填)
    }
  ]
}

請求範例值

{
  "inboxes": [
    {
      "id": "new_inbox_uuid"
    }
  ],
  "name": "updated_user_name",
  "avatar": "updated_avatar_url",
  "phoneNumber": 987654321,
  "email": "[e-mail]",
  "sourceId": "updated_source_id",
  "queryMetadata": "updated_query_metadata",
  "metadata": [
    {
      "key": "客戶等級",
      "value": "VVIP"
    },
    {
      "key": "偏好語言",
      "value": "日本語"
    }
  ]
}

程式碼範例

Shell/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": "[e-mail]",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata",
    "metadata": [
      {
        "key": "客戶等級",
        "value": "VVIP"
      },
      {
        "key": "偏好語言",
        "value": "日本語"
      }
    ]
  }'

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

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": "[e-mail]",
    "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);
  });

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": "[e-mail]",
      "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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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": "[e-mail]",
            "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();
}
?>

回應內容

狀態碼: 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 // 非必填
  "metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
  "mcpCredentials": [ // 聯絡人的 MCP 認證憑證列表
    object
  ]
  "apiCredentials": [ // 聯絡人的 API 認證憑證列表
    object
  ]
  "contactConnectors": [ // 聯絡人的 Connector OAuth 授權列表（不含 token 本體）
    object
  ]
  "tags": [
    {
      "id": string (uuid)
      "name": string
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
  "preChatFieldIndex": object // 來自此 Contact 所屬 inboxes 的 pre-chat form 欄位設定，mapping {field_id: {label: {locale: text}}}，前端用來把 metadata 的 UUID key 解析成顯示名稱
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "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]	否	自訂聯絡人屬性列表

請求結構範例

{
  "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 格式，可選，未提供則自動填入） (非必填)
    }
  ]
}

請求範例值

{
  "inboxes": [
    {
      "id": "new_inbox_uuid"
    }
  ],
  "name": "updated_user_name",
  "avatar": "updated_avatar_url",
  "phoneNumber": 987654321,
  "email": "[e-mail]",
  "sourceId": "updated_source_id",
  "queryMetadata": "updated_query_metadata",
  "metadata": [
    {
      "key": "客戶等級",
      "value": "VVIP"
    },
    {
      "key": "偏好語言",
      "value": "日本語"
    }
  ]
}

程式碼範例

Shell/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": "[e-mail]",
    "sourceId": "updated_source_id",
    "queryMetadata": "updated_query_metadata",
    "metadata": [
      {
        "key": "客戶等級",
        "value": "VVIP"
      },
      {
        "key": "偏好語言",
        "value": "日本語"
      }
    ]
  }'

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

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": "[e-mail]",
    "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);
  });

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": "[e-mail]",
      "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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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": "[e-mail]",
            "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();
}
?>

回應內容

狀態碼: 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 // 非必填
  "metadata"?: object // 自訂的客戶資訊，會顯示在對話頁的客戶資訊區塊 (非必填)
  "mcpCredentials": [ // 聯絡人的 MCP 認證憑證列表
    object
  ]
  "apiCredentials": [ // 聯絡人的 API 認證憑證列表
    object
  ]
  "contactConnectors": [ // 聯絡人的 Connector OAuth 授權列表（不含 token 本體）
    object
  ]
  "tags": [
    {
      "id": string (uuid)
      "name": string
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
    }
  ]
  "preChatFieldIndex": object // 來自此 Contact 所屬 inboxes 的 pre-chat form 欄位設定，mapping {field_id: {label: {locale: text}}}，前端用來把 metadata 的 UUID key 解析成顯示名稱
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "id": "user1_uuid",
  "inboxes": [
    {
      "id": "inbox_uuid",
      "name": "inbox_name"
    }
  ],
  "name": "user1",
  "avatar": "",
  "phoneNumber": 912345678,
  "email": "[e-mail]",
  "sourceId": null,
  "queryMetadata": null,
  "createdAt": "1751875361000",
  "updatedAt": "1751875361000"
}

---

刪除聯絡人

DELETE /api/v1/contacts/{id}/

參數

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

程式碼範例

Shell/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 並核對請求資料。

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);
  });

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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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();
}
?>

回應內容

狀態碼	說明
204	No response body
400	聯絡人還有關聯的對話，無法刪除

---

取得聯絡人的對話列表

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

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Contact.
channels	❌	array	Multiple values may be separated by commas.
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
tags	❌	array	Multiple values may be separated by commas.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?channels=example&inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example&tags=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

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

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/?channels=example&inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example&tags=example", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?channels=example&inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example&tags=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

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000/conversations/?channels=example&inbox=example&inboxes=example&keyword=example&page=1&pageSize=1&query=example&tags=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)
      "contact": { // 輕量級 Contact Serializer，用於 Conversation List view

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

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

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

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

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

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

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

回應範例值

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

---

取得聯絡人最新對話

GET /api/v1/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	搜尋對話中的訊息內容（不區分大小寫）

程式碼範例

Shell/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 並核對請求資料。

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);
  });

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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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();
}
?>

回應內容

狀態碼: 200

回應結構範例

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

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

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

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

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

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

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

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

回應範例值

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

狀態碼: 404 - No response body

---

群發訊息

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	是	要發送的訊息內容

請求結構範例

{
  "contactIds"?: [ // [正向指定模式] 要發送訊息的 contact ID 列表 (非必填)
    string (uuid)
  ]
  "inboxId"?: string (uuid) // [反向排除/全部發送模式] Inbox ID，會發送給該 inbox 下的所有 contacts (非必填)
  "excludeContactIds"?: [ // [反向排除模式] 要排除的 contact ID 列表，需配合 inbox_id 使用 (非必填)
    string (uuid)
  ]
  "message": string // 要發送的訊息內容
}

請求範例值

{
  "contactIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "inboxId": "550e8400-e29b-41d4-a716-446655440000",
  "excludeContactIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "message": "這是一個範例訊息"
}

程式碼範例

Shell/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 並核對請求資料。

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);
  });

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)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "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 // 非必填
}

回應範例值

{
  "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
}

---