摘要

此 API 可讓您在 Wati 中建立自訂聯絡人細分。您可以建立包含固定聯絡人清單的靜態細分，或根據篩選條件自動更新的動態細分。這些細分可用於下游工作流程、行銷活動和客戶資料平台 (CDP) 處理程序。

操作說明

使用 POST /api/v1/createCustomSegment 端點來建立自訂細分。

您可以建立：

使用聯絡人 ID 或篩選條件的靜態細分
使用自動重新整理的篩選條件的動態細分

端點

POST https://{WATI_API_ENDPOINT}/api/v1/createCustomSegment

驗證

此端點使用 Bearer token 驗證。

請將以下標頭新增至您的要求：

Authorization: Bearer YOUR_API_TOKEN

必要參數

參數	類型	說明
`name`	string	細分的名稱
`refreshType`	integer	細分類型。靜態請使用 `1`，動態請使用 `2`

要求內文欄位

欄位	類型	必要	說明
`name`	string	是	細分的名稱
`refreshType`	integer	是	靜態請使用 `1`，動態請使用 `2`
`groups`	array of objects	條件式	用於篩選聯絡人的篩選條件群組。當 `refreshType = 2` 時必要
`contactIds`	array of strings	條件式	用於靜態細分中的聯絡人 ID 清單
`useUploadedContact`	boolean	否	啟用上傳聯絡人邏輯，以便用於下游 CDP 細分 API。預設為 `false`

了解細分類型

靜態細分

靜態細分包含固定的聯絡人群。

對於靜態細分 (refreshType = 1)，您必須提供其中一項：

contactIds
groups

動態細分

動態細分會根據篩選條件自動更新。

對於動態細分 (refreshType = 2)，您必須提供：

groups

了解群組和條件

groups 欄位包含用於識別聯絡人的篩選規則。
每個群組都包含一個 conditions 陣列。

每個條件包含：

欄位	說明
`attribute`	聯絡人欄位或自訂屬性，例如 `name` 或 `phone`
`operator`	比較運算子，例如 `==`
`value`	用於比較的數值

範例要求

使用聯絡人 ID 建立靜態細分

{
  "name": "VIP Customers",
  "refreshType": 1,
  "contactIds": [
    "12345",
    "67890"
  ]
}

使用篩選條件建立動態細分

{
  "name": "Customers from India",
  "refreshType": 2,
  "groups": [
    {
      "conditions": [
        {
          "attribute": "country",
          "operator": "==",
          "value": "India"
        }
      ]
    }
  ]
}

範例 cURL 要求

curl --request POST \
     --url https://wati_api_endpoint/api/v1/createCustomSegment \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "refreshType": 1,
  "useUploadedContact": false
}
'

成功回應

成功的要求會傳回 200 回應。

{
  "result": true,
  "info": {
    "id": "segment_id",
    "name": "Customers from India"
  }
}

欄位	說明
`result`	成功建立細分時傳回 `true`
`info`	包含已建立細分的詳細資料

錯誤回應

400 Bad Request

發生此錯誤的原因如下：

缺少 name
refreshType 無效
建立動態細分時未提供 groups
建立靜態細分時未提供 groups 和 contactIds
您的帳戶未使用此功能
已達到作用中細分上限

500 Internal Server Error

伺服器因內部問題無法建立細分時，會發生此錯誤。

常見問題 (FAQ)

概觀

1. 建立自訂細分 API 的功能為何？

建立自訂細分 API 可讓您在 Wati 中建立自訂聯絡人細分。您可以建立包含固定聯絡人清單的靜態細分，或根據篩選條件自動更新的動態細分。這些細分可用於工作流程、行銷活動和客戶資料平台 (CDP) 處理程序。

2. 使用哪個端點來建立自訂細分？

請使用以下端點來建立自訂細分：

POST /api/v1/createCustomSegment

3. 建立自訂細分 API 使用何種驗證方法？

API 使用 Bearer token 驗證。請將以下標頭新增至您的要求：

Authorization: Bearer YOUR_API_TOKEN

細分類型和欄位

4. 使用此 API 可以建立哪些類型的細分？

API 支援：

使用聯絡人 ID 或篩選條件的靜態細分
使用自動重新整理的篩選條件的動態細分

5. 靜態細分和動態細分有何差異？

靜態細分包含固定的聯絡人群，並使用 refreshType = 1。

動態細分會根據篩選條件自動更新，並使用 refreshType = 2。

6. 建立自訂細分需要哪些欄位？

以下欄位為必要欄位：

name — 細分的名稱
refreshType — 靜態請使用 1，動態請使用 2

對於動態細分，需要 groups 欄位。

對於靜態細分，您必須提供以下其中一項：

contactIds
groups

群組和條件

7. groups 欄位包含什麼？

groups 欄位包含用於識別聯絡人的篩選規則。每個群組包含一個 conditions 陣列。

每個條件包含：

attribute — 聯絡人欄位或自訂屬性，例如 name 或 phone
operator — 比較運算子，例如 ==
value — 用於比較的數值

要求和回應範例

8. 如何建立靜態或動態細分？

範例靜態細分要求：

{
  "name": "VIP Customers",
  "refreshType": 1,
  "contactIds": [
    "12345",
    "67890"
  ]
}

範例動態細分要求：

{
  "name": "Customers from India",
  "refreshType": 2,
  "groups": [
    {
      "conditions": [
        {
          "attribute": "country",
          "operator": "==",
          "value": "India"
        }
      ]
    }
  ]
}

9. 成功建立細分時會傳回什麼回應？