建立或更新聯絡人
POST /v2/contact/createOrUpdate請求標頭、Base URL 與回應碼的說明,請參閱概覽。
以 Telephone 判斷聯絡人是否存在:不存在則建立,已存在則更新。
請求參數
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
ChannelType | String | 是 | 頻道類型,目前只接受 "whatsapp" |
Telephone | String | 是 | 聯絡人電話號碼,需包含國際區號,例如 +85261234567 |
FirstName | String | 否 | 名字。建立聯絡人時如未提供,會改用 LastName;兩者皆未提供則使用電話號碼 |
LastName | String | 否 | 姓氏 |
Email | String | 否 | 電郵 |
Tags | Object | 否 | 新增或移除標籤,結構見下方 |
Lists | Object | 否 | 加入或移出列表,結構見下方 |
SubscribedChannels | Array<String> | 否 | 聯絡人訂閱的 WhatsApp 頻道 ID |
CustomFields | Array<Object> | 否 | 自訂欄位的值,結構見下方 |
Tags / Lists 結構
| 欄位 | 類型 | 說明 |
|---|---|---|
Operate | String | "add" 新增,或 "del" 移除 |
Values | Array<String> | 標籤或列表的名稱 |
CustomFields 元素結構
| 欄位 | 類型 | 說明 |
|---|---|---|
FieldName | String | 自訂欄位名稱 |
Value | String | 欄位值 |
標籤、列表與自訂欄位需先建立
接口按名稱比對,不會自動建立標籤、列表或自訂欄位。名稱不存在時,該項會被略過,並在 Message 中提示,其餘資料仍會照常儲存。
請求範例
bash
curl -X POST "https://api.chatbooster.ai/v2/contact/createOrUpdate" \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ChannelType": "whatsapp",
"FirstName": "Peter",
"LastName": "Chan",
"Telephone": "+85261234567",
"Email": "[email protected]",
"Tags": { "Operate": "add", "Values": ["VIP", "Newsletter"] },
"Lists": { "Operate": "add", "Values": ["會員"] },
"CustomFields": [
{ "FieldName": "Company", "Value": "Example Ltd" }
]
}'回應
| 欄位 | 類型 | 說明 |
|---|---|---|
Code | Integer | 200 表示成功 |
Message | String | 全部成功時為 "success";部分項目未處理時會列出原因,例如 "tag[VIP] not exist;" |
json
{
"Code": 200,
"Message": "success"
}請同時檢查 Message
即使 Code 為 200,Message 也可能提示部分標籤、列表、頻道或自訂欄位未能處理。