跳轉到內容

查詢聯絡人列表 ​

POST /v1/contact/list

請求標頭、Base URL 與回應碼的說明,請參閱概覽。

請求參數 ​

欄位類型必填說明
PageSizeInteger否每頁數量,預設 20,最大 100
PageNumberInteger否頁碼,預設 1
FilterArray<Object>否篩選條件,結構見下方
CustomFieldFilterArray<Object>否按自訂欄位篩選,多個條件需同時符合

Filter 元素結構

欄位類型說明
FieldNameString篩選欄位,可用值見下表
ValuesArray<String>篩選值

可用的 FieldName

FieldNameValues 說明範例
Tag標籤名稱,可多個["VIP", "New"]
List列表名稱,可多個["Newsletter"]
ChannelWhatsApp 頻道的電話號碼,可多個["+85298765432"]
Email電郵地址,可多個["[email protected]"]
Telephone聯絡人電話號碼,可多個["+85261234567"]
UpdateTimeRFC 3339 時間。1 個值表示「此時間或之後」,2 個值表示時間區間["2026-01-01T00:00:00Z", "2026-12-31T23:59:59Z"]

CustomFieldFilter 元素結構

欄位類型說明
FieldNameString自訂欄位名稱,需完全相符
ValueString欄位值,需完全相符

請求範例 ​

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" }
    ]
  }'

回應 ​

欄位類型說明
CodeInteger200 表示成功
MessageString狀態訊息
Data.TotalInteger符合條件的聯絡人總數
Data.ContactsArray<Object>聯絡人列表

Contacts 元素結構

欄位類型說明
FirstNameString名字
LastNameString姓氏
AvatarString頭像網址
TelephoneString電話號碼(含國際區號)
EmailString電郵
TagsArray<String>標籤名稱
ChannelsArray<String>已訂閱頻道的電話號碼
ChannelNamesArray<String>已訂閱頻道的名稱,順序與 Channels 一一對應
CustomFieldsArray<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" }
        ]
      }
    ]
  }
}