文件

API v2 聯絡人與潛在客戶

列出聯絡人與潛在客戶、以外部 ID 建立或更新單一聯絡人，並為代理程式批次匯入聯絡人。

Contact payloads expose customAttributes; write requests accept customAttributes.plan and other JSON keys such as customAttributes.seats.

聯絡人會將你自己穩定的終端使用者 ID，與姓名、電子郵件地址及電話號碼建立關聯。潛在客戶則是代理程式擷取的唯讀提交紀錄。本頁的每個端點都需要 Authorization: Bearer YOUR_API_KEY，以及對 {agentId} 的存取權限。

嵌入式聊天中已簽署的身分聲明，請見身分驗證。共用的驗證與驗證錯誤，請見錯誤目錄。

聯絡人物件

欄位類型備註
idstring聯絡人 UUID。
externalIdstring你自己穩定的終端使用者 ID。
namestring 或 null聯絡人姓名。
emailstring 或 null聯絡人電子郵件地址。
phonestring 或 null聯絡人電話號碼。
createdAtinteger 或 nullUnix 時間戳記（秒）。
updatedAtinteger 或 nullUnix 時間戳記（秒）。
lastSeenAtinteger 或 nullUnix 時間戳記（秒）。

列出聯絡人

路徑：/api/v2/agents/{agentId}/contacts

GET /api/v2/agents/{agentId}/contacts

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

查詢參數是否必填限制
limit否1 到 100 之間的整數，預設為 20。
cursor否前一頁回傳的不透明游標。請原封不動地重複使用。
search否經過修剪、不區分大小寫的子字串搜尋（ILIKE），涵蓋外部 ID、電子郵件、姓名與電話號碼。百分號（%）會被去除，但底線（_）不會被跳脫，會作為單一字元萬用字元使用——例如 acct_1 也會比對到 acctX1。修剪後為空字串時會被忽略。
curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/contacts?search=alice&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

成功：200 OK

{
  "data": [
    {
      "id": "f9878f31-c2b3-469f-a82e-26e996e67721",
      "externalId": "customer_123",
      "name": "Alice Example",
      "email": "[email protected]",
      "phone": "+1 555 0100",
      "customAttributes": { "plan": "pro", "seats": 4 },
      "createdAt": 1784332800,
      "updatedAt": 1784332800,
      "lastSeenAt": null
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

無效的 limit 或 cursor 會回傳 400 VALIDATION_INVALID_BODY。

潛在客戶物件

欄位類型備註
idstring潛在客戶 UUID。
namestring 或 null提交的姓名。
emailstring 或 null提交的電子郵件地址。
phonestring 或 null提交的電話號碼。
conversationIdstring 或 null當此潛在客戶連結到某個對話時，為該對話的公開參考 ID。
createdAtintegerUnix 時間戳記（秒）。

列出潛在客戶

路徑：/api/v2/agents/{agentId}/leads

GET /api/v2/agents/{agentId}/leads

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

查詢參數是否必填限制
limit否1 到 100 之間的整數，預設為 20。
cursor否前一頁回傳的不透明游標。請原封不動地重複使用。
createdAfter否帶有 Z 或 UTC 偏移量的 ISO 8601 日期時間。下限為包含邊界。
createdBefore否帶有 Z 或 UTC 偏移量的 ISO 8601 日期時間。上限為包含邊界。

當兩個日期篩選條件同時存在時，以時間點比較，createdAfter 必須小於或等於 createdBefore。兩者相等時仍屬有效。

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/leads?createdAfter=2026-07-18T08:00:00Z&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

成功：200 OK

{
  "data": [
    {
      "id": "ad47f673-6bfb-43a0-a296-d79c84870a32",
      "name": "Alice Example",
      "email": "[email protected]",
      "phone": "+1 555 0100",
      "conversationId": "a1b2c3d4e5f6g7h8",
      "createdAt": 1784361600
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

潛在客戶依提交時間由新到舊排序。無效的 limit、cursor、日期時間，或顛倒的日期範圍，都會回傳 400 VALIDATION_INVALID_BODY。

建立或更新單一聯絡人

POST /api/v2/agents/{agentId}/contacts

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

此端點會依 {agentId, externalId} 這組配對執行 upsert（建立或更新）。當已有相符的聯絡人時，僅會更新請求中提供的個人資料欄位。省略的欄位會保留其已儲存的值；明確傳入 null 或空字串則會清除該欄位。

主體欄位是否必填類型與限制
externalId是字串，經過修剪，1 到 255 個字元。
name否字串，修剪後最多 255 個字元，或為 null。
email否有效的電子郵件地址，修剪後最多 320 個字元、空字串，或為 null。
phone否字串，修剪後最多 50 個字元、空字串，或為 null。
curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"externalId":"customer_123","name":"Alice Example","email":"[email protected]","customAttributes":{"plan":"pro","seats":4}}'

成功：無論是新增或因衝突而更新，皆回傳 201 Created。聯絡人物件以裸物件回傳。

{
  "id": "f9878f31-c2b3-469f-a82e-26e996e67721",
  "externalId": "customer_123",
  "name": "Alice Example",
  "email": "[email protected]",
  "phone": null,
  "customAttributes": { "plan": "pro", "seats": 4 },
  "createdAt": 1784332800,
  "updatedAt": 1784332800,
  "lastSeenAt": null
}

無效的主體會連同驗證詳情回傳 400 VALIDATION_INVALID_BODY。

匯入聯絡人

路徑：/api/v2/agents/{agentId}/contacts/import

POST /api/v2/agents/{agentId}/contacts/import

身分驗證：具備 {agentId} 存取權限的 Bearer API 金鑰。

此請求使用 snake_case 欄位名稱。rows 必須包含 1 到 1,000 筆項目。

資料列欄位是否必填類型與限制
external_id是字串，經過修剪，1 到 255 個字元。
name否字串，修剪後最多 255 個字元，或為 null。
email否有效的電子郵件地址，修剪後最多 320 個字元、空字串，或為 null。
phone否字串，修剪後最多 50 個字元，或為 null；空字串同樣會被接受並儲存為 null。

同一請求內會依 external_id 去除重複項目，以最後出現的一筆為準。與單筆聯絡人的部分更新不同，匯入操作會為每一筆保留下來的資料列建構完整的個人資料欄位，因此發生衝突時，省略、null 或空字串的個人資料值都會儲存為 null。

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/contacts/import' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"rows":[{"external_id":"customer_123","name":"Alice Example","email":"[email protected]","phone":"+1 555 0100","customAttributes":{"plan":"pro"}},{"external_id":"customer_456","name":"Bob Example","email":"[email protected]","phone":null}]}'

成功：200 OK

{
  "processed": 2,
  "skipped": 0
}

processed 是已完成 upsert 的不重複外部 ID 數量。skipped 是從提交批次中移除的重複資料列數量。無效的主體——包括空批次與超過 1,000 筆的批次——都會回傳 400 VALIDATION_INVALID_BODY。

參考文件