Engage API documentation
The Engage API lets your own systems send WhatsApp messages through the numbers connected to your Engage workspace, and tells you what happened to them. Use it to send appointment reminders, report-ready alerts, order updates, one-time codes and anything else your software already knows about.
It is a plain JSON API over HTTPS. Everything you do through it also appears in the Engage Inbox and Messages page, tagged API, so your team sees the same picture.
| Base URL | string | https://api.168-144-71-93.sslip.io |
| Format | JSON requests and responses, UTF-8 | |
| Auth | API key in the Authorization header | |
| Versioning | Paths start with /v1. Fields may be added; existing ones will not change meaning within v1. |
Quickstart
Five minutes from nothing to a delivered message.
- Connect a WhatsApp number in Settings → Numbers (new to this? read the Meta setup guide).
- Create an API key in Settings → Developers. It is shown once. Store it in an environment variable, never in code or a mobile app.
- Pick an approved template. Businesses start conversations with templates; see
GET /v1/templates. - Send it:
curl -X POST https://api.168-144-71-93.sslip.io/v1/messages \
-H "Authorization: Bearer tfe_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"to": "919811022113",
"template": { "name": "appointment_reminder", "language": "en", "variables": ["Anish", "10 Oct, 9:30 AM"] },
"client_ref": "booking-4821"
}'You get 202 Accepted straight away. The message is queued, not yet delivered:
{
"id": "5f0c2c1e-9a3d-4e0e-8a53-3c0f7f6b2d11",
"status": "queued",
"type": "template",
"to": "919811022113",
"from": { "id": "a8264e0f-2fc5-482b-a258-9c6928fa9b69", "number": "+91 88005 80075" },
"client_ref": "booking-4821",
"error": null,
"created_at": "2026-10-12T09:41:07.512Z"
}Then it moves to sent, delivered and read, or failed. Get those changes pushed to you with webhooks, or look them up with GET /v1/messages/:id.
Authentication
Send your key as a bearer token on every request. X-API-Key: <key> also works.
Authorization: Bearer tfe_live_xxxxxxxxxxxxxxxx
- Keys start with
tfe_live_. We store only a hash, so a lost key cannot be recovered. Create a new one and revoke the old. - A key can be tied to one number. It can then only send from, list and read messages of that number.
- Revoking a key takes effect immediately. Create separate keys per system so you can revoke one without breaking the rest.
Keep keys on your server
Send a message
POST/v1/messages
Send exactly one of text or template.
| to | string, required | The recipient with country code, e.g. 919811022113. Spaces, “+” and “00” are accepted. |
| from | string | A channel id (from /v1/channels) or the number. Optional when your key is tied to one number, or you have only one. |
| template | object | name, language (default en_US) and variables (array, in order, for {{1}}, {{2}}…). The number of variables must match exactly. |
| text | string ≤ 4096 | Free text. Only allowed if the customer wrote to you in the last 24 hours. |
| name | string | Saved on the contact if it is new. |
| opted_in | boolean | Assert that you hold this person’s consent. Needed to send a marketing template to someone not yet opted in. The assertion is recorded with the name of your key. |
| client_ref | string ≤ 64 | Your own id for this message. Sending the same one again returns the first message instead of a second. See Idempotency. |
Responses: 202 accepted and queued; 200 with "idempotent_replay": true if this client_ref was already used; otherwise an error.
A free-text reply
curl -X POST https://api.168-144-71-93.sslip.io/v1/messages -H "Authorization: Bearer tfe_live_xxxxxxxxxxxxxxxx" -H "Content-Type: application/json" \
-d '{ "to": "919811022113", "text": "Your report is ready. Reply 1 to get it here." }'Send in bulk
POST/v1/messages/batch
Up to 100 messages per call. Each one is judged on its own, so one bad number does not stop the others. The response is 200 even if some are rejected, so always check each result.
// request
{ "messages": [ { "to": "919811022113", "template": { "name": "report_ready", "language": "en", "variables": ["Anish"] } },
{ "to": "12", "text": "hi" } ] }
// response
{ "accepted": 1, "rejected": 1, "results": [
{ "index": 0, "status": "accepted", "message": { "id": "…", "status": "queued", … } },
{ "index": 1, "status": "rejected", "error": { "code": "invalid_number", "message": "…" } } ] }Check status
GET/v1/messages/{id}
Add ?by=client_ref to look a message up by your own reference.
| queued | Accepted by us, waiting to be handed to WhatsApp. | |
| sent | WhatsApp accepted it. | |
| delivered | Reached the customer’s phone. | |
| read | The customer opened it. Not guaranteed: people can turn read receipts off. | |
| failed | Could not be delivered. error says why (e.g. the number is not on WhatsApp). |
Numbers and templates
GET/v1/channels
The numbers this key can use: { "data": [{ "id", "number", "name", "active" }] }.
GET/v1/templates
Approved templates you can send, with name, language, category (MARKETING, UTILITY…), variables (how many you must pass), the body text and the numbers it is available on. Create and submit templates in the app under Templates; WhatsApp reviews them first.
Webhooks
Webhooks push events to your server as they happen: delivery receipts, customer replies, template approvals. Add an endpoint in Settings → Webhooks. You can have one per number, or one for all numbers. Each endpoint has its own signing secret.
| message.status | event | An outbound message changed state: sent, delivered, read or failed. |
| message.received | event | A customer sent you a message. |
| template.status | event | WhatsApp approved, rejected or paused a template. |
The envelope
POST /your/endpoint
Content-Type: application/json
User-Agent: Engage-Webhooks/1.0
X-Engage-Event: message.status
X-Engage-Delivery: 3b1d… (unique per attempt series, per endpoint)
X-Engage-Signature: t=1760262067,v1=9c5e…
{
"id": "evt_8f1c…", (same for every endpoint that gets this event)
"type": "message.status",
"created_at": "2026-10-12T09:41:09.120Z",
"channel": { "id": "a8264e0f-…", "number": "+91 88005 80075" },
"data": {
"message": { "id": "5f0c2c1e-…", "wa_message_id": "wamid.HBg…", "client_ref": "booking-4821",
"to": "+919811022113", "status": "delivered", "error": null },
"conversation_id": "…"
}
}message.received
"data": {
"message": { "id": "…", "wa_message_id": "wamid.HBg…", "type": "text", "text": "Yes, 9:30 works", "timestamp": "2026-10-12T09:45:00.000Z" },
"contact": { "wa_id": "919811022113", "name": "Anish Kumar", "consent": "opted_in" },
"conversation_id": "…"
}template.status
"data": { "template": { "name": "report_ready", "language": "en", "status": "approved", "reason": null } }What your server must do
- Answer with any 2xx within 8 seconds. Acknowledge first, process afterwards.
- Otherwise we retry with growing gaps: after 30 s, 5 min, 30 min, 2 h and 6 h (6 attempts in all). Answering
410 Gonestops retries. - Delivery is at least once and not strictly in order. Use
idto ignore events you already handled, and compare timestamps before overwriting a newer status. - The endpoint must be HTTPS and publicly reachable. We do not follow redirects, and we do not call private or internal addresses.
- Endpoints that keep failing are disabled and you are notified in the app. You can inspect every attempt and resend from Settings → Webhooks.
Verify signatures
Anyone can POST to your URL, so check that each request really came from Engage. The signature header is t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of `${t}.${rawBody}` using your endpoint’s signing secret. Reject requests with an old t to stop replays.
import { createHmac, timingSafeEqual } from "node:crypto";
// IMPORTANT: use the raw request body, exactly as received. Do not parse and re-serialise it.
export function verify(secret, signatureHeader, rawBody, toleranceSec = 300) {
const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // too old: possible replay
const expected = createHmac("sha256", secret).update(t + "." + rawBody).digest();
const given = Buffer.from(parts.v1 ?? "", "hex");
return given.length === expected.length && timingSafeEqual(given, expected);
}
// Express: app.post("/hooks/engage", express.raw({ type: "application/json" }), (req, res) => {
// if (!verify(process.env.ENGAGE_WEBHOOK_SECRET, req.get("X-Engage-Signature") ?? "", req.body.toString()))
// return res.sendStatus(401);
// const event = JSON.parse(req.body.toString());
// res.sendStatus(200); // acknowledge fast, process after
// });Use the raw body
Consent and the 24-hour window
WhatsApp, not Engage, sets these rules, and the API enforces them so a mistake does not put your number at risk.
- Opt-in. You may message people who agreed to hear from you on WhatsApp. Marketing templates to anyone not recorded as opted in are refused with
consent_requiredunless you assertopted_in: true, which is recorded against your key. Only assert it if you really hold the consent. - Opt-out. If a customer replies STOP, they are marked opted out automatically and every send to them is refused with
contact_opted_out. - The 24-hour window. After a customer writes to you, you may send free text for 24 hours. Outside it, only approved templates.
- Templates are reviewed by WhatsApp and categorised (marketing, utility, authentication). Category affects both rules and what Meta charges you.
More in the compliance guide.
Idempotency
Networks fail and your code will retry. To make sure a retry never messages a customer twice, give each logical message a stable client_ref (or send an Idempotency-Key header: same effect). If we already have a message with that reference, you get it back with 200 and "idempotent_replay": true, and nothing new is sent. Use your own record id, such as booking-4821-reminder.
Rate limits
Each key may make 20 requests per second. Beyond that you get 429 with retry_after_ms; wait that long and retry. Batch calls count once, so use them to send many messages quickly. WhatsApp also limits how many different people a number may start conversations with per day (shown as “Daily limit” on each number in Settings); messages beyond it can come back as failed with WhatsApp’s reason in error.
Errors
Errors have a conventional HTTP status and a stable code to switch on. Do not parse the human-readable message.
HTTP/1.1 403 Forbidden
{ "error": { "code": "consent_required", "message": "Marketing templates need the contact to have opted in. …" } }| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_request | The body is malformed or a field is invalid. The message names the field. |
| 400 | invalid_number | The number is not a full international number (11–15 digits including country code). |
| 400 | channel_required | Your workspace has several numbers and the key is not tied to one. Pass "from". |
| 401 | invalid_api_key | The key is missing, wrong or revoked. |
| 403 | contact_opted_out | The person opted out. Nothing can be sent until they opt in again. |
| 403 | consent_required | A marketing template to someone who has not opted in. Pass "opted_in": true only if you hold their consent. |
| 403 | channel_not_allowed | This key is tied to a different number. |
| 404 | channel_not_found | "from" matches none of your numbers, or none is connected. |
| 404 | template_not_found | No template with that name and language on this number’s WhatsApp account. |
| 404 | message_not_found | No such message (or it belongs to a number this key cannot see). |
| 409 | client_ref_conflict | That client_ref was already used for a different number. |
| 422 | template_not_approved | The template is pending, rejected or paused. Only approved templates can be sent. |
| 422 | invalid_variables | The number of variables does not match the template, or one is empty. |
| 422 | window_closed | A free-text message needs the customer to have written within 24 hours. Send a template instead. |
| 422 | channel_inactive | The number is deactivated in Settings. |
| 429 | rate_limited | Too many requests. Wait retry_after_ms and try again. |
Retry 429 and 5xx. Do not retry other 4xx errors unchanged: they will fail the same way.
A message accepted with 202 can still end as failed later (for example, the number is not on WhatsApp). That arrives as a message.status event.
Going live checklist
- Your WhatsApp number is connected and shows Active in Settings → Numbers.
- The templates you need are Approved (check Templates).
- The API key lives in a secret manager or environment variable, on your server only.
- Every send carries a stable client_ref so retries are safe.
- Your webhook endpoint is HTTPS, verifies the signature, answers 2xx fast and ignores duplicate event ids.
- You handle failed statuses (tell a human, or fall back to SMS/email) and contact_opted_out (stop trying).
- You only message people who opted in, and you can show where and when they agreed.
- You back off on 429 and 5xx with increasing delays.
- You use separate keys per system, and know how to rotate them.