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.
/v1/meWho 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.
/v1/messagesList messages
Every message the account has sent or received, newest first, with its delivery state. This is the endpoint to reconcile against.
Parameters
| Name | In | Type | |
|---|---|---|---|
limit | query | integer | default 50 |
offset | query | integer | default 0 |
curl -X GET https://chattil.com/v1/messages \
-H "X-API-Key: tt_your_key_here"/v1/templatesList templates
Reusable message bodies and their placeholders.
curl -X GET https://chattil.com/v1/templates \
-H "X-API-Key: tt_your_key_here"/v1/messagesSend 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
| Field | Type | |
|---|---|---|
to | string | required — Recipient in international format |
message | string | optional |
template_id | integer | optional |
media_url | string | optional |
region | string | optional |
variables | object | optional — 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."}'/v1/messages/bulkSend 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
| Field | Type | |
|---|---|---|
contact_ids | array of integer | optional |
group_id | integer | optional |
all_contacts | boolean | default False |
message | string | required |
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.
/v1/contactsList contacts
Paginated. Filter by group or search by name or number.
Parameters
| Name | In | Type | |
|---|---|---|---|
q | query | string | default |
limit | query | integer | default 50 |
offset | query | integer | default 0 |
curl -X GET https://chattil.com/v1/contacts \
-H "X-API-Key: tt_your_key_here"/v1/contacts/{contact_id}Get a contact
Parameters
| Name | In | Type | |
|---|---|---|---|
contact_id | path | integer | required |
curl -X GET https://chattil.com/v1/contacts/123 \
-H "X-API-Key: tt_your_key_here"/v1/groupsList 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"/v1/contactsCreate 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
| Field | Type | |
|---|---|---|
name | string | optional |
phone | string | required |
email | string | optional |
notes | string | optional |
region | string | optional |
curl -X POST https://chattil.com/v1/contacts \
-H "X-API-Key: tt_your_key_here" \
-H "Content-Type: application/json" \
-d '{"phone": "+233201234567"}'/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
| Name | In | Type | |
|---|---|---|---|
contact_id | path | integer | required |
curl -X DELETE https://chattil.com/v1/contacts/123 \
-H "X-API-Key: tt_your_key_here"Inbox
Threads of what customers actually said.
/v1/conversationsList conversations
One entry per person you have exchanged messages with, with unread counts and the last message.
Parameters
| Name | In | Type | |
|---|---|---|---|
limit | query | integer | default 50 |
offset | query | integer | default 0 |
curl -X GET https://chattil.com/v1/conversations \
-H "X-API-Key: tt_your_key_here"/v1/conversations/{conversation_id}/messagesList conversation messages
The full thread with one contact, oldest first.
Parameters
| Name | In | Type | |
|---|---|---|---|
conversation_id | path | integer | required |
limit | query | integer | default 50 |
offset | query | integer | default 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.
/v1/campaignsList campaigns
Parameters
| Name | In | Type | |
|---|---|---|---|
limit | query | integer | default 50 |
offset | query | integer | default 0 |
curl -X GET https://chattil.com/v1/campaigns \
-H "X-API-Key: tt_your_key_here"/v1/campaigns/{campaign_id}Get a campaign
Includes per-status counts, so progress can be shown without pulling every recipient.
Parameters
| Name | In | Type | |
|---|---|---|---|
campaign_id | path | integer | required |
curl -X GET https://chattil.com/v1/campaigns/123 \
-H "X-API-Key: tt_your_key_here"/v1/campaigns/{campaign_id}/recipientsList campaign recipients
Per-recipient delivery state. This is where to look to find out which specific sends failed and why.
Parameters
| Name | In | Type | |
|---|---|---|---|
campaign_id | path | integer | required |
status | query | string | optional |
limit | query | integer | default 50 |
offset | query | integer | default 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.
/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
| Name | In | Type | |
|---|---|---|---|
job_id | path | integer | required |
curl -X GET https://chattil.com/v1/jobs/123 \
-H "X-API-Key: tt_your_key_here"