Skip to main content

Segments

A segment is a saved audience: a set of rules (tags, stage, workspaces, inactivity) that picks WhatsApp contacts when a broadcast runs. Build audiences from your own systems, then target them with the Broadcasts API. Segments are dynamic: the contacts are worked out each time a broadcast uses the segment, not when you create it.

Conventions

Send your key in the x-api-key header and bodies as JSON with Content-Type: application/json. Requests without a valid key get 401 { "message": "Unauthorized" }; other errors look like { "error": "message" }. The workspace goes in the request (workspace: { "id" } in the body, or ?workspaceId= when listing). Lists are plain arrays, paged with page (default 1) and limit (default 10, max 100; higher values are reduced to 100): keep increasing page until you get fewer results than your limit. Segments can't be updated through the API: delete the segment and create a new one, or edit it in the app. See REST API for your API host and key.

Endpoints

The segment object​

Attributes
idstring
The segment id. Use it in segments when you create a broadcast.
namestring
The segment name
typestring
contact
criteriaobject

The audience rules. Only returned when type is contact. See how a segment picks contacts.

workspaceobject
The workspace the segment belongs to: { id, title }. A broadcast can only use segments from its own workspace.
createdAt, updatedAtstring
Timestamps

Criteria fields with no value are left out of the response.

The segment object
{
  "id": "Sg4mN7qRt2",
  "name": "VIP customers, inactive 30 days",
  "type": "contact",
  "criteria": {
    "workspaces": [
      { "id": "Wq3nT8vYp1", "title": "Downtown Studio" }
    ],
    "contactStage": "Customer",
    "tags": ["vip"],
    "exclusionTags": ["unsubscribed"],
    "numberOfDaysLastActivity": 30
  },
  "workspace": {
    "id": "Wq3nT8vYp1",
    "title": "Downtown Studio"
  },
  "createdAt": "2026-10-14T09:30:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}

How a segment picks contacts​

When a broadcast runs, a segment selects contacts in your account that:

  • are on the WhatsApp channel,
  • are in one of criteria.workspaces (if you set none, contacts from every workspace in your account are included),
  • have the stage criteria.contactStage, if set,
  • have all of criteria.tags, if set,
  • have none of criteria.exclusionTags, if set,
  • had their last activity at least criteria.numberOfDaysLastActivity days ago, if set. Use this to re-engage inactive contacts.

The segment's own workspace doesn't limit the contacts. Set criteria.workspaces to do that.

List segments​

GET/v1/segments
Query parameters
workspaceIdstring
Only segments that belong to this workspace. Must be a workspace in your account.
searchTextstring
Matches part of the segment name. Not case sensitive.
pageintegerdefault 1
limitintegerdefault 10
Max 100. Higher values are reduced to 100.

200 OK: a JSON array of segments. Deleted segments aren't included. When it has fewer than limit items, it's the last page.

Errors
StatusBodyWhen
404{ "error": "Invalid Workspace Id" }workspaceId isn't in your account
500{ "error": "Could not retrieve Segments" }The request could not be completed. Retry.
Request
curl "https://api.whauto.chat/v1/segments?workspaceId=Wq3nT8vYp1&page=1&limit=50" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"
Response 200
[
  {
    "id": "Sg4mN7qRt2",
    "name": "VIP customers, inactive 30 days",
    "type": "contact",
    "criteria": {
      "workspaces": [{ "id": "Wq3nT8vYp1", "title": "Downtown Studio" }],
      "contactStage": "Customer",
      "tags": ["vip"],
      "exclusionTags": ["unsubscribed"],
      "numberOfDaysLastActivity": 30
    },
    "workspace": { "id": "Wq3nT8vYp1", "title": "Downtown Studio" },
    "createdAt": "2026-10-14T09:30:00.000Z",
    "updatedAt": "2026-10-14T09:30:00.000Z"
  }
]

Create a segment​

POST/v1/segments
Body parameters
namestringrequired
The segment name
typestringrequired
Use contact
workspaceobjectrequired

The workspace the segment belongs to

criteriaobjectrequired

The audience rules. Send {} for no rules, which selects every WhatsApp contact in your account.

200 OK: the new segment.

Errors
StatusBodyWhen
400{ "error": "Invalid parameters" }name, type or workspace.id is missing
404{ "error": "Invalid Workspace" }workspace.id isn't in your account
404{ "error": "Invalid Workspaces: Ab12Cd34Ef" }An id in criteria.workspaces isn't in your account. Nothing is created; the body lists the bad ids.
500{ "error": "Could not create Segment" }The request could not be completed, including when criteria is missing. Retry.
Request
curl -X POST https://api.whauto.chat/v1/segments \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP customers, inactive 30 days",
    "type": "contact",
    "workspace": { "id": "Wq3nT8vYp1" },
    "criteria": {
      "workspaces": [{ "id": "Wq3nT8vYp1" }],
      "contactStage": "Customer",
      "tags": ["vip"],
      "exclusionTags": ["unsubscribed"],
      "numberOfDaysLastActivity": 30
    }
  }'
Response 200
{
  "id": "Sg4mN7qRt2",
  "name": "VIP customers, inactive 30 days",
  "type": "contact",
  "criteria": {
    "workspaces": [{ "id": "Wq3nT8vYp1", "title": "Downtown Studio" }],
    "contactStage": "Customer",
    "tags": ["vip"],
    "exclusionTags": ["unsubscribed"],
    "numberOfDaysLastActivity": 30
  },
  "workspace": { "id": "Wq3nT8vYp1", "title": "Downtown Studio" },
  "createdAt": "2026-10-14T09:30:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}

Get a segment​

GET/v1/segments/{id}
Path parameters
idstringrequired
Segment id

200 OK: the segment.

Errors
StatusBodyWhen
404{ "error": "Segment not found" }The segment isn't in your account, or was deleted
500{ "error": "Could not retrieve Segment" }The request could not be completed. Retry.
Request
curl "https://api.whauto.chat/v1/segments/Sg4mN7qRt2" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"
Response 200
{
  "id": "Sg4mN7qRt2",
  "name": "VIP customers, inactive 30 days",
  "type": "contact",
  "criteria": {
    "workspaces": [{ "id": "Wq3nT8vYp1", "title": "Downtown Studio" }],
    "contactStage": "Customer",
    "tags": ["vip"],
    "exclusionTags": ["unsubscribed"],
    "numberOfDaysLastActivity": 30
  },
  "workspace": { "id": "Wq3nT8vYp1", "title": "Downtown Studio" },
  "createdAt": "2026-10-14T09:30:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}

Delete a segment​

DEL/v1/segments/{id}
Path parameters
idstringrequired
Segment id

A deleted segment no longer appears in lists, can't be read, and can't be used in new broadcasts.

Errors
StatusBodyWhen
404{ "error": "Segment not found" }The segment isn't in your account
500{ "error": "Could not delete Segment" }The request could not be completed. Retry.
Request
curl -X DELETE https://api.whauto.chat/v1/segments/Sg4mN7qRt2 \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"
Response 200
{ "success": true }