查詢聯絡人列表
POST /v1/contact/list請求標頭、Base URL 與回應碼的說明,請參閱概覽。
請求參數
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
PageSize | Integer | 否 | 每頁數量,預設 20,最大 100 |
PageNumber | Integer | 否 | 頁碼,預設 1 |
Filter | Array<Object> | 否 | 篩選條件,結構見下方 |
CustomFieldFilter | Array<Object> | 否 | 按自訂欄位篩選,多個條件需同時符合 |
Filter 元素結構
| 欄位 | 類型 | 說明 |
|---|---|---|
FieldName | String | 篩選欄位,可用值見下表 |
Values | Array<String> | 篩選值 |
可用的 FieldName
| FieldName | Values 說明 | 範例 |
|---|---|---|
Tag | 標籤名稱,可多個 | ["VIP", "New"] |
List | 列表名稱,可多個 | ["Newsletter"] |
Channel | WhatsApp 頻道的電話號碼,可多個 | ["+85298765432"] |
Email | 電郵地址,可多個 | ["[email protected]"] |
Telephone | 聯絡人電話號碼,可多個 | ["+85261234567"] |
UpdateTime | RFC 3339 時間。1 個值表示「此時間或之後」,2 個值表示時間區間 | ["2026-01-01T00:00:00Z", "2026-12-31T23:59:59Z"] |
CustomFieldFilter 元素結構
| 欄位 | 類型 | 說明 |
|---|---|---|
FieldName | String | 自訂欄位名稱,需完全相符 |
Value | String | 欄位值,需完全相符 |
請求範例
bash
curl -X POST "https://api.chatbooster.ai/v1/contact/list" \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"PageSize": 20,
"PageNumber": 1,
"Filter": [
{ "FieldName": "Tag", "Values": ["VIP"] },
{ "FieldName": "UpdateTime", "Values": ["2026-01-01T00:00:00Z"] }
],
"CustomFieldFilter": [
{ "FieldName": "Company", "Value": "Example Ltd" }
]
}'回應
| 欄位 | 類型 | 說明 |
|---|---|---|
Code | Integer | 200 表示成功 |
Message | String | 狀態訊息 |
Data.Total | Integer | 符合條件的聯絡人總數 |
Data.Contacts | Array<Object> | 聯絡人列表 |
Contacts 元素結構
| 欄位 | 類型 | 說明 |
|---|---|---|
FirstName | String | 名字 |
LastName | String | 姓氏 |
Avatar | String | 頭像網址 |
Telephone | String | 電話號碼(含國際區號) |
Email | String | 電郵 |
Tags | Array<String> | 標籤名稱 |
Channels | Array<String> | 已訂閱頻道的電話號碼 |
ChannelNames | Array<String> | 已訂閱頻道的名稱,順序與 Channels 一一對應 |
CustomFields | Array<Object> | 自訂欄位(FieldName、Value),只回傳已設定值的欄位 |
json
{
"Code": 200,
"Message": "success",
"Data": {
"Total": 1,
"Contacts": [
{
"FirstName": "Peter",
"LastName": "Chan",
"Avatar": "",
"Telephone": "+85261234567",
"Email": "[email protected]",
"Tags": ["VIP"],
"Channels": ["+85298765432"],
"ChannelNames": ["My WhatsApp Channel"],
"CustomFields": [
{ "FieldName": "Company", "Value": "Example Ltd" }
]
}
]
}
}