EngageAPI docsGet an API key

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 URLstringhttps://api.168-144-71-93.sslip.io
FormatJSON requests and responses, UTF-8
AuthAPI key in the Authorization header
VersioningPaths start with /v1. Fields may be added; existing ones will not change meaning within v1.

Quickstart

Five minutes from nothing to a delivered message.

  1. Connect a WhatsApp number in Settings → Numbers (new to this? read the Meta setup guide).
  2. Create an API key in Settings → Developers. It is shown once. Store it in an environment variable, never in code or a mobile app.
  3. Pick an approved template. Businesses start conversations with templates; see GET /v1/templates.
  4. 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

Anyone with the key can send WhatsApp messages as your business. Never put it in a web page, mobile app or public repository. If one leaks, revoke it in Settings → Developers.

Send a message

POST/v1/messages

Send exactly one of text or template.

tostring, requiredThe recipient with country code, e.g. 919811022113. Spaces, “+” and “00” are accepted.
fromstringA channel id (from /v1/channels) or the number. Optional when your key is tied to one number, or you have only one.
templateobjectname, language (default en_US) and variables (array, in order, for {{1}}, {{2}}…). The number of variables must match exactly.
textstring ≤ 4096Free text. Only allowed if the customer wrote to you in the last 24 hours.
namestringSaved on the contact if it is new.
opted_inbooleanAssert 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_refstring ≤ 64Your 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": "…" } } ] }
For large marketing sends to a list, use Campaigns in the app instead. It paces sending, skips people who opted out, and shows live progress and replies.

Check status

GET/v1/messages/{id}

Add ?by=client_ref to look a message up by your own reference.

queuedAccepted by us, waiting to be handed to WhatsApp.
sentWhatsApp accepted it.
deliveredReached the customer’s phone.
readThe customer opened it. Not guaranteed: people can turn read receipts off.
failedCould not be delivered. error says why (e.g. the number is not on WhatsApp).
Prefer webhooks to polling. Polling every message is slow and counts against your rate limit.

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.statuseventAn outbound message changed state: sent, delivered, read or failed.
message.receivedeventA customer sent you a message.
template.statuseventWhatsApp 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 Gone stops retries.
  • Delivery is at least once and not strictly in order. Use id to 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

Frameworks that parse JSON before you see it change the bytes (whitespace, key order), and the signature will not match. Capture the raw body first. Compare with a constant-time function, as above.

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_required unless you assert opted_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. …" } }
HTTPcodeMeaning
400invalid_requestThe body is malformed or a field is invalid. The message names the field.
400invalid_numberThe number is not a full international number (11–15 digits including country code).
400channel_requiredYour workspace has several numbers and the key is not tied to one. Pass "from".
401invalid_api_keyThe key is missing, wrong or revoked.
403contact_opted_outThe person opted out. Nothing can be sent until they opt in again.
403consent_requiredA marketing template to someone who has not opted in. Pass "opted_in": true only if you hold their consent.
403channel_not_allowedThis key is tied to a different number.
404channel_not_found"from" matches none of your numbers, or none is connected.
404template_not_foundNo template with that name and language on this number’s WhatsApp account.
404message_not_foundNo such message (or it belongs to a number this key cannot see).
409client_ref_conflictThat client_ref was already used for a different number.
422template_not_approvedThe template is pending, rejected or paused. Only approved templates can be sent.
422invalid_variablesThe number of variables does not match the template, or one is empty.
422window_closedA free-text message needs the customer to have written within 24 hours. Send a template instead.
422channel_inactiveThe number is deactivated in Settings.
429rate_limitedToo 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.
Questions or something unclear? See the guides, or contact support from the Help page. The machine-readable spec is at /docs/openapi.json.