Developer guide
The KiliChat API lets your own systems, like an online store, a CRM or a website form, send WhatsApp messages and keep contacts up to date. Webhooks tell those systems when something happens, like a customer sending a message.
This section is for developers. If you're not technical, share this page with whoever looks after your website or software.
What can I do with the API?
- Send a text message or an approved template to a customer.
- Check a message's delivery status.
- Add or update contacts, their fields and tags, and opt them in or out.
- Add a contact to a sequence.
- Get told about new messages, delivery updates, new contacts and opt-outs through webhooks.
How does it work?
Everything belongs to one WhatsApp number. An API key made for a number can only see and send for that number. Keys and webhooks are managed by admins in KiliChat → API & webhooks (in the left sidebar under Manage, for the chosen number).
Basics
| Base URL | https://app.kilichat.com/api/v1 |
| Authentication | Authorization: Bearer <key>, or an X-API-Key: <key> header. Keys start with kc_. See API keys. |
| Format | JSON in, JSON out. Send Content-Type: application/json. |
| Phone numbers | Full number with country code. Spaces, + and dashes are ignored, so +91 98765 43210 is read as 919876543210. 8 to 15 digits. |
| Rate limit | 120 requests a minute per key. See Rate limits and retries. |
Endpoints
| Method and path | What it does | Guide |
|---|---|---|
GET /number | The number this key belongs to | Send messages |
GET /templates | Approved templates | Send messages |
POST /messages | Send text or a template | Send messages |
GET /messages/:id | One message and its status | Send messages |
GET /contacts/:phone | Look up a contact | Contacts and sequences |
POST /contacts | Add or update a contact | Contacts and sequences |
GET /sequences | List sequences | Contacts and sequences |
POST /sequences/:id/enroll | Add a contact to a sequence | Contacts and sequences |
Quick example
curl -X POST https://app.kilichat.com/api/v1/messages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "919876543210", "template": {"name": "order_update", "variables": ["Priya", "#1042"]}}'What do errors look like?
Errors come back with a 4xx or 5xx status and a JSON body:
{ "error": "This API key isn't valid or has been revoked" }| Status | Meaning |
|---|---|
400 | The request is missing something or a value is wrong. The error names the field, like to: Use the full number with country code, like 919876543210. |
401 | No key, or the key is wrong or revoked. |
404 | No such message, contact, template or sequence on this number. |
422 | WhatsApp's rules don't allow it. The body has a code, like window_closed, opted_out or blocked, or the template isn't approved, or the sequence is off. |
429 | Too many requests. Wait for the number of seconds in the Retry-After header. |
502 | WhatsApp refused the message. The message is still returned, with "status": "failed" and Meta's reason in error. |
500 | Something went wrong on our side. Try again, and tell us if it keeps happening. |
The 24-hour rule
WhatsApp only allows free text within 24 hours of the customer's last message. Outside that window, send an approved template. See Message templates.