Browse the docsAPI reference

Developers

API reference

16 endpoints. Every request needs X-API-Key; see Authentication.

Generated from the running application's own schema, so it cannot drift from what the API actually accepts.

Organization

Confirm a key and read what the account is entitled to.

GET/v1/me

Who am I

Confirms a key works and reports the account it belongs to, its plan, the message quota remaining today, and whether a WhatsApp number is currently connected. The cheapest call to make first.

curl -X GET https://chattil.com/v1/me \
  -H "X-API-Key: tt_your_key_here"

Messages

Send, and reconcile what happened to what you sent.

GET/v1/messages

List messages

Every message the account has sent or received, newest first, with its delivery state. This is the endpoint to reconcile against.

Parameters

NameInType
limitqueryintegerdefault 50
offsetqueryintegerdefault 0
curl -X GET https://chattil.com/v1/messages \
  -H "X-API-Key: tt_your_key_here"
GET/v1/templates

List templates

Reusable message bodies and their placeholders.

curl -X GET https://chattil.com/v1/templates \
  -H "X-API-Key: tt_your_key_here"
POST/v1/messages

Send a message

Sends one WhatsApp message to one number. Subject to the same quota, suppression list and warm-up cap as the dashboard — a number that has opted out is refused here too.

Body

FieldType
tostringrequired — Recipient in international format
messagestringoptional
template_idintegeroptional
media_urlstringoptional
regionstringoptional
variablesobjectoptional — Extra values for {placeholders} in the message or template. {name}, {phone}, {business_name} and {occupation} are filled automatically.
curl -X POST https://chattil.com/v1/messages \
  -H "X-API-Key: tt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "+233201234567", "message": "Hi {name}, your order is ready for pickup."}'
POST/v1/messages/bulk

Send to many

Queues a send to a group or a list of numbers and returns a job id immediately. Poll `GET /v1/jobs/{job_id}` for progress; the send is paced deliberately and does not complete within the request.

Body

FieldType
contact_idsarray of integeroptional
group_idintegeroptional
all_contactsbooleandefault False
messagestringrequired
curl -X POST https://chattil.com/v1/messages/bulk \
  -H "X-API-Key: tt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hi {name}, your order is ready for pickup."}'

Contacts

The people you can reach, and how they are grouped.

GET/v1/contacts

List contacts

Paginated. Filter by group or search by name or number.

Parameters

NameInType
qquerystringdefault
limitqueryintegerdefault 50
offsetqueryintegerdefault 0
curl -X GET https://chattil.com/v1/contacts \
  -H "X-API-Key: tt_your_key_here"
GET/v1/contacts/{contact_id}

Get a contact

Parameters

NameInType
contact_idpathintegerrequired
curl -X GET https://chattil.com/v1/contacts/123 \
  -H "X-API-Key: tt_your_key_here"
GET/v1/groups

List groups

Contact groups, with the number of members in each.

curl -X GET https://chattil.com/v1/groups \
  -H "X-API-Key: tt_your_key_here"
POST/v1/contacts

Create a contact

Numbers are normalised to E.164 on the way in, so any format your system stores is accepted. Creating a contact that already exists returns the existing one rather than a duplicate.

Body

FieldType
namestringoptional
phonestringrequired
emailstringoptional
notesstringoptional
regionstringoptional
curl -X POST https://chattil.com/v1/contacts \
  -H "X-API-Key: tt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+233201234567"}'
DELETE/v1/contacts/{contact_id}

Delete a contact

Removes the contact. It does not remove them from the suppression list — an opt-out survives deletion, deliberately.

Parameters

NameInType
contact_idpathintegerrequired
curl -X DELETE https://chattil.com/v1/contacts/123 \
  -H "X-API-Key: tt_your_key_here"

Inbox

Threads of what customers actually said.

GET/v1/conversations

List conversations

One entry per person you have exchanged messages with, with unread counts and the last message.

Parameters

NameInType
limitqueryintegerdefault 50
offsetqueryintegerdefault 0
curl -X GET https://chattil.com/v1/conversations \
  -H "X-API-Key: tt_your_key_here"
GET/v1/conversations/{conversation_id}/messages

List conversation messages

The full thread with one contact, oldest first.

Parameters

NameInType
conversation_idpathintegerrequired
limitqueryintegerdefault 50
offsetqueryintegerdefault 0
curl -X GET https://chattil.com/v1/conversations/123/messages \
  -H "X-API-Key: tt_your_key_here"

Campaigns

Planned sends, and per-recipient outcomes.

GET/v1/campaigns

List campaigns

Parameters

NameInType
limitqueryintegerdefault 50
offsetqueryintegerdefault 0
curl -X GET https://chattil.com/v1/campaigns \
  -H "X-API-Key: tt_your_key_here"
GET/v1/campaigns/{campaign_id}

Get a campaign

Includes per-status counts, so progress can be shown without pulling every recipient.

Parameters

NameInType
campaign_idpathintegerrequired
curl -X GET https://chattil.com/v1/campaigns/123 \
  -H "X-API-Key: tt_your_key_here"
GET/v1/campaigns/{campaign_id}/recipients

List campaign recipients

Per-recipient delivery state. This is where to look to find out which specific sends failed and why.

Parameters

NameInType
campaign_idpathintegerrequired
statusquerystringoptional
limitqueryintegerdefault 50
offsetqueryintegerdefault 0
curl -X GET https://chattil.com/v1/campaigns/123/recipients \
  -H "X-API-Key: tt_your_key_here"

Jobs

Progress of anything that does not finish inside a request.

GET/v1/jobs/{job_id}

Get a job

Progress of anything queued — a bulk send, an import, a group scrape. Poll this rather than assuming a bulk send finished.

Parameters

NameInType
job_idpathintegerrequired
curl -X GET https://chattil.com/v1/jobs/123 \
  -H "X-API-Key: tt_your_key_here"