Engage REST API

1. 1

   Make sure API access is on

   The API and webhooks come with the Pulse and Orbit plans. On Spark, buy the API keys & webhooks add-on from Billing. You also need a WhatsApp number connected under Channels.

2. 2

   Create an API key

   Go to Channels → your number → API tab → New API key (admins and owners only).

   • Name it after the integration that will use it.
   • Tick only the scopes it needs.
   • Copy the key now. It is shown once; we store only a hash. Lost it? Revoke and create a new one.

   A key is bound to one WhatsApp number. It can only see that number’s contacts, conversations and messages, and messages are sent from that number. Keep it on your server — never in a browser or mobile app.
3. 3

   Verify the key

   Call GET /me. A valid key returns its account, channel and scopes.

   bash

   curl https://engage.scale360x.com/api/v1/me \
     -H "Authorization: Bearer engage_live_xxx"

   response

   {
     "data": {
       "account": { "id": "…", "name": "Acme Inc" },
       "key": { "id": "…", "scopes": ["messages:send", "contacts:write"] }
     }
   }

   A 401 means the key is wrong, revoked or expired.

4. 4

   Add a contact (optional)

   Not required — sending a message creates the contact for you. Create one first when you want a name, email, company or tags on it. Phone numbers must be E.164 with a leading +.

   bash

   curl -X POST https://engage.scale360x.com/api/v1/contacts \
     -H "Authorization: Bearer engage_live_xxx" \
     -H "Content-Type: application/json" \
     -d '{ "phone": "+919876543210", "name": "Jane Doe", "tags": ["lead"] }'

   It is find-or-create by phone: 201 for a new contact, 200 if it already existed.

5. 5

   Send your first message

   Needs the messages:send scope.

   bash

   curl -X POST https://engage.scale360x.com/api/v1/messages \
     -H "Authorization: Bearer engage_live_xxx" \
     -H "Content-Type: application/json" \
     -d '{ "to": "+919876543210", "type": "text", "text": "Hi 👋" }'

   WhatsApp only allows free-form text, images and documents within 24 hours of the customer’s last message. To start a conversation, or after the window closes, send an approved template (see Messages).
6. 6

   Read conversations and replies

   List conversations with conversations:read, then fetch a conversation’s messages with messages:read — each has its direction and delivery status.

   bash

   curl "https://engage.scale360x.com/api/v1/conversations?status=open&limit=20" \
     -H "Authorization: Bearer engage_live_xxx"
   
   curl https://engage.scale360x.com/api/v1/conversations/<conversation_id>/messages \
     -H "Authorization: Bearer engage_live_xxx"

7. 7

   Launch a broadcast (optional)

   Send an approved template to up to 1,000 recipients per request. Needs broadcasts:send.

   bash

   curl -X POST https://engage.scale360x.com/api/v1/broadcasts \
     -H "Authorization: Bearer engage_live_xxx" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "July promo",
       "template_name": "promo_july",
       "template_language": "en_US",
       "recipients": [
         { "to": "+919876543210", "params": ["Jane"] },
         { "to": "+919876543211" }
       ]
     }'

   You get 202 immediately; poll GET /broadcasts/{id} for delivery progress.

8. 8

   Receive events with a webhook

   Instead of polling, register an HTTPS endpoint (webhooks:manage). Save the secret from the response — it is shown once — and verify every signature.

   bash

   curl -X POST https://engage.scale360x.com/api/v1/webhooks \
     -H "Authorization: Bearer engage_live_xxx" \
     -H "Content-Type: application/json" \
     -d '{ "url": "https://example.com/hooks/engage", "events": ["message.received", "message.status_updated"] }'

A key with no scopes can still call GET /me.

GET /api/v1/contacts?limit=50
→ { "data": [ … ], "meta": { "next_cursor": "eyJ…" } }

GET /api/v1/contacts?limit=50&cursor=eyJ…
→ { "data": [ … ], "meta": { "next_cursor": null } }   // last page

limit defaults to 50 (max 100). Pass the cursor back unchanged; null means you are done.

Events

Delivery payload

{
  "id": "8f3c…",                       // unique per delivery — dedupe on this
  "event": "message.received",
  "occurred_at": "2026-07-01T12:00:00.000Z",
  "account_id": "…",
  "data": {
    "conversation_id": "…",
    "contact_id": "…",
    "whatsapp_message_id": "wamid.…",
    "content_type": "text",
    "text": "Hi 👋"
  }
}

message.status_updated data: whatsapp_message_id, conversation_id, status. conversation.created data: conversation_id, contact_id. Headers: X-Engage-Event, X-Engage-Webhook-Id, X-Engage-Signature.

Verify the signature

import crypto from 'node:crypto'

export function verify(header, rawBody, secret) {
  const m = header.match(/t=(\d+),v1=([0-9a-f]+)/)
  if (!m) return false
  const [, t, v1] = m
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false // replay guard
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  const a = Buffer.from(expected), b = Buffer.from(v1)
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Delivery rules