Summary

This API allows you to create custom contact segments in Wati. You can create either a static segment with a fixed list of contacts or a dynamic segment that automatically updates based on filtering conditions. These segments can then be used in downstream workflows, campaigns, and customer data platform (CDP) processes.

Instructions

Use the POST /api/v1/createCustomSegment endpoint to create a custom segment.

You can create:

Static segments using contact IDs or filters
Dynamic segments using filtering conditions that automatically refresh

Endpoint

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

Authentication

This endpoint uses Bearer token authentication.

Add the following header to your request:

Authorization: Bearer YOUR_API_TOKEN

Required parameters

Parameter	Type	Description
`name`	string	Name of the segment
`refreshType`	integer	Segment type. Use `1` for Static and `2` for Dynamic

Request body fields

Field	Type	Required	Description
`name`	string	Yes	Name of the segment
`refreshType`	integer	Yes	Use `1` for Static or `2` for Dynamic
`groups`	array of objects	Conditional	Filtering condition groups used to filter contacts. Required when `refreshType = 2`
`contactIds`	array of strings	Conditional	List of contact IDs used in a static segment
`useUploadedContact`	boolean	No	Enables uploaded contacts logic for downstream CDP segment APIs. Defaults to `false`

Understanding segment types

Static segment

A static segment contains a fixed set of contacts.

For static segments (refreshType = 1), you must provide either:

contactIds
groups

Dynamic segment

A dynamic segment automatically updates based on filtering conditions.

For dynamic segments (refreshType = 2), you must provide:

groups

Understanding groups and conditions

The groups field contains filtering rules used to identify contacts.
Each group contains a conditions array.

Each condition includes:

Field	Description
`attribute`	Contact field or custom attribute such as `name` or `phone`
`operator`	Comparison operator such as `==`
`value`	Value used for comparison

Example request

Create a static segment using contact IDs

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

Create a dynamic segment using filters

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

Example cURL request

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

Successful response

A successful request returns a 200 response.

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

Field	Description
`result`	Returns `true` when the segment is created successfully
`info`	Contains details of the created segment

Error responses

400 Bad Request

This error occurs when:

name is missing
refreshType is invalid
A dynamic segment is created without groups
A static segment is missing both groups and contactIds
The feature is not available for your account
The active segment limit has been reached

500 Internal Server Error

This error occurs when the server fails to create the segment due to an internal issue.

Frequently Asked Questions (FAQs)

Overview

1. What does the Create Custom Segment API do?

The Create Custom Segment API allows you to create custom contact segments in Wati. You can create static segments with a fixed list of contacts or dynamic segments that automatically update based on filtering conditions. These segments can be used in workflows, campaigns, and customer data platform (CDP) processes.

2. Which endpoint is used to create a custom segment?

Use the following endpoint to create a custom segment:

POST /api/v1/createCustomSegment

3. What authentication method does the Create Custom Segment API use?

The API uses Bearer token authentication. Add the following header to your request:

Authorization: Bearer YOUR_API_TOKEN

Segment types and fields

4. What types of segments can be created using this API?

The API supports:

Static segments using contact IDs or filters
Dynamic segments using filtering conditions that automatically refresh

5. What is the difference between static and dynamic segments?

A static segment contains a fixed set of contacts and uses refreshType = 1.

A dynamic segment automatically updates based on filtering conditions and uses refreshType = 2.

6. Which fields are required to create a custom segment?

The following fields are required:

name — Name of the segment
refreshType — Use 1 for Static or 2 for Dynamic

For dynamic segments, the groups field is required.

For static segments, you must provide either:

contactIds
groups

Groups and conditions

7. What does the `groups` field contain?

The groups field contains filtering rules used to identify contacts. Each group contains a conditions array.

Each condition includes:

attribute — Contact field or custom attribute such as name or phone
operator — Comparison operator such as ==
value — Value used for comparison

Request and response examples

8. How do you create a static or dynamic segment?

Example static segment request:

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

Example dynamic segment request:

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

9. What response is returned when a segment is created successfully?