摘要

此 API 允许您在 Wati 中创建自定义联系人细分。您可以创建具有固定联系人列表的静态细分，或根据过滤条件自动更新的动态细分。这些细分随后可在下游工作流、广告系列和客户数据平台 (CDP) 流程中使用。

说明

使用 POST /api/v1/createCustomSegment 端点来创建自定义细分。

您可以创建：

使用联系人 ID 或过滤条件的静态细分
使用自动刷新过滤条件的动态细分

端点

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

身份验证

此端点使用 Bearer 令牌身份验证。

在请求中添加以下标头：

Authorization: Bearer YOUR_API_TOKEN

必需参数

参数	类型	描述
`name`	string	细分名称
`refreshType`	integer	细分类型。静态使用 `1`，动态使用 `2`

请求正文字段

字段	类型	必需	描述
`name`	string	是	细分名称
`refreshType`	integer	是	使用 `1` 表示静态，`2` 表示动态
`groups`	对象数组	有条件	用于过滤联系人的过滤条件组。当 `refreshType = 2` 时必需
`contactIds`	字符串数组	有条件	用于静态细分的联系人 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 错误请求

出现此错误的原因是：

缺少 name
refreshType 无效
创建动态细分时未提供 groups
创建静态细分时同时缺少 groups 和 contactIds
您的帐户未提供此功能
已达到活动细分限制

500 服务器内部错误

由于服务器内部问题而无法创建细分时出现此错误。

常见问题解答

概述

1. 创建自定义细分 API 有什么作用？

创建自定义细分 API 允许您在 Wati 中创建自定义联系人细分。您可以创建具有固定联系人列表的静态细分，或者根据过滤条件自动更新的动态细分。这些细分可用于工作流、广告系列和客户数据平台 (CDP) 流程。

2. 使用哪个端点来创建自定义细分？

使用以下端点来创建自定义细分：

POST /api/v1/createCustomSegment

3. 创建自定义细分 API 使用什么身份验证方法？

API 使用 Bearer 令牌身份验证。在请求中添加以下标头：

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. 创建细分成功时会返回什么响应？