Segments

Note

https://api.whatbot.in/public/v1/segments — create, list and delete contact segments that mirror a list kept in your own system (a CRM saved view, a campaign list). Each one is a segment of “contacts with tag X”, keyed by a reference you own.

How it fits together

1. Tag the contacts on your list with POST /contacts/tag, e.g. crm_seg:hot-leads.
2. Upsert a segment for that tag with POST /segments, keyed by your own external_ref.
3. The segment appears under Contacts → Segments and can be picked as a broadcast audience. Because it filters on the tag, contacts you tag later join it automatically.

Create or update a segment

cURL

curl -X POST https://api.whatbot.in/public/v1/segments \
  -H "X-API-Key: wa_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Hot leads", "tag": "crm_seg:hot-leads", "external_ref": "crm_seg:hot-leads" }'

Field	Type	Required	Description
name	string	Yes	The segment’s name in Whatbot. 1–200 characters.
tag	string	Yes	The tag the segment matches: every contact carrying it is in the segment.
external_ref	string	Yes	Your stable key for this segment, up to 200 characters. Sending the same external_ref again updates the segment’s name and tag in place.

200

{ "id": "5c2e...", "external_ref": "crm_seg:hot-leads", "action": "created" }

action is created or updated.

List segments

cURL

curl https://api.whatbot.in/public/v1/segments -H "X-API-Key: wa_live_xxx"

200

{
  "items": [
    { "id": "5c2e...", "name": "Hot leads", "external_ref": "crm_seg:hot-leads", "created_at": "2026-09-20T08:11:02+00:00" }
  ],
  "count": 1
}

Only segments created through this API (those with an external_ref) are listed. Segments your team builds in the app are not.

Delete a segment

cURL

curl -X DELETE "https://api.whatbot.in/public/v1/segments?external_ref=crm_seg:hot-leads" \
  -H "X-API-Key: wa_live_xxx"

200

{ "deleted": 1, "external_ref": "crm_seg:hot-leads" }

deleted is 0 when nothing matched — deleting twice is safe. Deleting a segment leaves the contacts and their tags alone.

Errors

Status	Cause
401	Missing/invalid API key
422	A required field is missing or too long, or external_ref is missing on delete