WhatsApp Business API

Quick start

1. Connect WhatsApp. In the panel go to CPaaS › WhatsApp and connect your number with Facebook (about 5 minutes).
2. Get an approved template. Templates › New template. Meta usually approves within minutes. Business-initiated messages must use a template.
3. Create an API key. WhatsApp › API Documentation › Create key. It starts with sghwa_ and is shown once.
4. Send your first message with the request below, then check its status or set a webhook.

Authentication

Send your API key in the Authorization header as a Bearer token (or in X-API-Key). Keys belong to your panel account; you can have up to 5 active keys and revoke any of them in the panel.

Authorization: Bearer sghwa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Numbers, limits & idempotency

Phone numbers

Use the full international number, digits only: 919876543210. Spaces, + and dashes are removed; a 10-digit Indian mobile (starting 6-9) gets 91 added automatically.

Rate limit

Up to 50 requests per second per API key. Above that you get 429 rate_limited with Retry-After: 1. For large sends use bulk (1,000 recipients per request). WhatsApp's own throughput and daily limits (by number tier) also apply.

Your reference (ref)

Add "ref": "order-1043" (max 100 characters) to any send. It is returned in every status, in webhooks, and you can look a message up by it.

Idempotency (safe retries)

If a network error leaves you unsure whether a request worked, retry it with the same Idempotency-Key header. Within 24 hours the same key returns the original result ("duplicate": true) instead of sending again.

Idempotency-Key: order-1043-shipped

The 24-hour rule & pricing

WhatsApp has two kinds of outgoing messages:

Check whether the window is open with GET contact (windowOpen, windowClosesAt). Sending a session message after the window closed returns 409 window_closed.

Each accepted message is charged from your WhatsApp wallet at your price for its category (or covered by your monthly plan). If WhatsApp does not deliver a message, or Meta does not bill it, the amount is returned automatically. See balance.

Send a template

{"ok": true, "messageId": 1045, "status": "queued", "ref": "order-1043"}

Send an OTP

Create an Authentication template in the panel (Templates › New template › Authentication). Meta fixes the wording ("123456 is your verification code") and adds a Copy code button. Send the code as the only variable:

Coupon, limited-time offer & carousel templates

Create these in the panel (Templates › Rich templates). Each has default values saved with it - the coupon code, how long the offer runs, and every card's image / video and link value - so a normal send or bulk request needs only the usual variables. To change them for one message, add:

Send text & media (session messages)

Within the 24-hour window you can reply freely. Set type and the matching object:

Media links must be public https URLs - or upload the file first with POST media.

Buttons, lists and link buttons

Set "type": "interactive" and an interactive object. When the customer taps a button or list row, you receive a message.inbound webhook with replyId = the id you set.

Optional for all: header (text, 60), footer (60). body is required (1024). Ids must be unique and must not look like p12 or b1.x.0 (reserved for our chatbot and catalog).

Bulk send / campaigns

Send one template to up to 1,000 recipients per request, each with their own variables. The batch becomes a campaign you can watch live in the panel (delivered, read, clicked, replied, failure reasons, retarget). Invalid, duplicate and opted-out numbers are reported in rejected and the rest are sent.

The wallet must cover all accepted messages up front (402 insufficient_balance otherwise). Larger lists: send several requests, or upload Excel / CSV in the panel (no limit).

{
  "ok": true, "campaignId": 88, "status": "queued", "scheduledAt": null,
  "accepted": 2, "rejectedCount": 1,
  "messages": [
    {"index": 0, "to": "919876543210", "messageId": 2101, "ref": "inv-1"},
    {"index": 1, "to": "919812345678", "messageId": 2102, "ref": "inv-2"}
  ],
  "rejected": [{"index": 2, "to": "12345", "error": "bad_number"}]
}

Meta-compatible API

Send exactly the JSON of Meta's Cloud API POST /{phone-number-id}/messages - any message type Meta supports (template with any components, text, image, video, audio, document, sticker, location, contacts, interactive including flows and catalogs). We check billing, opt-outs (templates) and the 24-hour window (session messages), send it to WhatsApp straight away and return Meta's own response with the real wamid - plus sgh_message_id for our status API.

• Your reference: Meta's biz_opaque_callback_data is stored as ref and comes back in our webhooks.
• Errors use Meta's format ({"error": {"message", "code", ...}}) so existing error handling keeps working.
• Several numbers? Pass ?phone_number_id= (from the panel); default is your default number.

{
  "messaging_product": "whatsapp",
  "contacts": [{"input": "919876543210", "wa_id": "919876543210"}],
  "messages": [{"id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgS..."}],
  "sgh_message_id": 1046
}

Message status

Look up by id (our messageId), by ref (your reference - latest match), or up to 100 at once with ids=1045,1046,1047 (returns messages[]). For real-time updates prefer webhooks.

{
  "ok": true, "messageId": 1045, "toNumber": "919876543210", "messageType": "template",
  "templateName": "order_update", "campaignId": null, "status": "read",
  "errorCode": null, "errorText": null, "clientRef": "order-1043",
  "createdAt": "2026-10-06T12:01:41", "sentAt": "2026-10-06T12:01:43",
  "deliveredAt": "2026-10-06T12:01:44", "readAt": "2026-10-06T12:05:10",
  "repliedAt": null, "clickedAt": null, "failedAt": null,
  "pricingCategory": "utility", "fallbackStatus": null
}

List messages

Status lifecycle

Extra timestamps: repliedAt (customer replied), clickedAt (tracked link clicked). Statuses never go backwards.

Templates

Your approved templates with what each needs: variables (body values), headerType (NONE, TEXT, IMAGE, VIDEO, DOCUMENT), headerVariable, buttonVariables and Meta's raw components. Create and edit templates in the panel (Meta reviews them).

Upload media

Returns a public https link you can use in templates (header.media) and session messages (media.link). JPG / PNG up to 5 MB, MP4 / 3GP 16 MB, PDF / Office / TXT 100 MB. The file content is checked against its type.

{"ok": true, "link": "https://www.smsgatewayhub.com/cpaas/media/202610/7f3c...e1.pdf", "fileName": "invoice.pdf", "size": 48211}

Contact & 24-hour window

Everything we know about a customer: name, tags, attributes (e.g. form answers), assigned agent and department, opt-out and block state - and windowOpen / windowClosesAt to decide between a session message and a template.

{
  "ok": true, "number": "919876543210", "known": true, "name": "Ravi Kumar",
  "email": null, "conversationStatus": "open", "assignedTo": "Priya",
  "department": "Sales", "tags": ["lead", "interested"], "attributes": {"city": "Indore"},
  "blocked": false, "optedOut": false,
  "windowOpen": true, "windowClosesAt": "2026-10-07T09:42:23",
  "lastInboundAt": "2026-10-06T09:42:23", "firstSeenAt": "2026-10-05T21:25:36"
}

Opt-outs

Customers who reply STOP / UNSUBSCRIBE are added automatically. Templates to opted-out numbers are refused (409 opted_out) and skipped in bulk. Sync your own unsubscribe list with op: add. 500 per page.

Balance

{"ok": true, "billingActive": true, "mode": "per_message", "currency": "INR", "balance": 2450.75, "planName": null, "planValidTill": null}

mode: per_message (charged per message from balance), plan (monthly plan, valid till planValidTill) or free.

Webhooks: setup & security

In the panel open WhatsApp › Automation › Webhooks, enter your https URL, choose the events and save. You get a signing secret once. We POST JSON to your URL; reply with any 2xx within 10 seconds. Failed deliveries are retried 6 times with growing gaps (2, 4, 8, 16, 32, 64 minutes). Use Send test to receive a test.ping.

Always verify the signature before trusting the data, compare in constant time, and process events idempotently (the same event can arrive twice after a retry).

Events & payloads

{
  "event": "message.status", "timestamp": "2026-10-06T12:01:44",
  "data": {
    "messageId": 1045, "to": "919876543210", "ref": "order-1043",
    "campaignId": null, "status": "delivered", "at": "2026-10-06T12:01:44",
    "errorCode": null, "errorText": null,
    "wamid": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgS..."
  }
}

{
  "event": "flow.submitted", "timestamp": "2026-10-06T12:20:05",
  "data": {"contactId": 77, "from": "919876543210", "flowId": 4,
           "fields": {"name": "Ravi", "email": "ravi@example.com", "interested_in": "WhatsApp API"}}
}

{
  "event": "message.inbound", "timestamp": "2026-10-06T12:10:02",
  "data": {
    "from": "919876543210", "name": "Ravi", "type": "interactive",
    "text": "Looks good", "replyId": "yes", "mediaId": null,
    "wamid": "wamid.HBgMOTE5...", "contactId": 77,
    "receivedAt": "2026-10-06T12:10:01", "adReferral": null
  }
}

{"event": "payment.paid", "timestamp": "...",
 "data": {"payId": 31, "number": "919876543210", "amount": 999.00, "note": "Order #1043"}}

{"event": "ai.handoff", "timestamp": "...",
 "data": {"contactId": 77, "from": "919876543210", "question": "I want a refund"}}

type in message.inbound: text, image, video, audio, document, sticker, location, contacts, button, interactive. Media can be viewed in the panel inbox.

Error codes

WhatsApp (Meta) errors

When WhatsApp itself refuses or fails a message, its code appears in errorCode / errorText (status API and webhooks). The common ones:

Best practices & go-live checklist

• Use webhooks, not polling, for statuses and replies. Verify the signature; answer 2xx fast and process in the background.
• Store our messageId and your ref together; use Idempotency-Key on every send you might retry.
• Only message people who opted in, honour STOP immediately (we do it for you), and keep marketing relevant - quality rating decides your daily limit.
• Check windowOpen before session messages; outside the window always use a template.
• OTPs: Authentication template, code as the only variable, short expiry.
• Large sends: bulk in batches of 1,000 or a scheduled campaign; watch the campaign page for failure reasons and retarget non-readers.
• Media: host on fast https or use upload; keep images under 1 MB for quick delivery.
• Security: keys only on servers, one key per system, revoke unused keys.

Postman & OpenAPI

Changelog