Contacts

Keep your customer list in step with Chatbox AI. A contact is keyed on its phone number, and its opt-in state decides whether anything may message it.

Paths are relative to https://api.chatboxai.dev/api, so /v1/messages/template means https://api.chatboxai.dev/api/v1/messages/template. Every request needs an API key, see Authentication.

List contacts

GET/v1/contacts
Scopecontacts:readPaginated
Query parameterNotes
pageFrom 1.
pageSizeDefault 25, maximum 100.
tagOnly contacts carrying this tag.
searchName or phone.
optIntrue or false.
200 OK
{
  "items": [
    {
      "id": "clx8h2k9p0001",
      "phone": "+919999900000",
      "name": "Asha Menon",
      "tags": ["shopify", "repeat-buyer"],
      "attributes": { "shopifyCustomerId": "7712340099" },
      "optIn": true,
      "channel": "WHATSAPP",
      "lastSeen": "2026-10-17T09:51:11.002Z",
      "createdAt": "2026-03-02T06:12:40.119Z",
      "updatedAt": "2026-10-17T09:51:11.002Z"
    }
  ],
  "total": 1842,
  "page": 1,
  "pageSize": 25
}

Look up by phone

GET/v1/contacts/by-phone/{phone}
Scopecontacts:read

Exact lookup. 404 if there is nobody. URL-encode the + (so +919999900000 becomes %2B919999900000).

Get a contact

GET/v1/contacts/{id}
Scopecontacts:read

Returns one contact, in the same shape as an item in the list above.

Create or update

POST/v1/contacts
Scopecontacts:write

Create, or update whoever already has this phone number. Safe to call repeatedly: this is the endpoint a customer sync loop should use.

Request body
{
  "phone": "+919999900000",
  "name": "Asha Menon",
  "tags": ["shopify", "repeat-buyer"],
  "attributes": { "shopifyCustomerId": "7712340099" },
  "optIn": true
}

tags and attributes replace what is there. To add a tag without touching the others, use POST /v1/contacts/{id}/tags.

optIn: true is a claim that you collected consent. WhatsApp holds the business responsible for it, not us and not you. Set it from a real checkbox at your checkout, never by default.

Update a contact

PATCH/v1/contacts/{id}
Scopecontacts:write

Accepts name, tags, attributes, optIn.

There is deliberately no way to change a contact's phone number through this API. Moving a number reattaches somebody's entire chat history to a different person.

Add or remove tags

POSTDELETE/v1/contacts/{id}/tags
Scopecontacts:write
Request body
{ "tags": ["abandoned-cart"] }

POST adds to, and DELETE removes from, the existing tags.

Opt in or out

POST/v1/contacts/{id}/opt-in · /v1/contacts/{id}/opt-out
Scopecontacts:write

Both return the updated contact.

An opted-out contact cannot be messaged by anything: this API, the dashboard, or a broadcast.