Developers · Send notifications
Notifications API reference
Every field, response and error of the send endpoint.
On this page
Endpoint
POST https://api.example.com/api/app-notifications/sendHeaders
| Header | Value |
|---|---|
Content-Type | application/json |
x-app-id | The connected app’s App ID |
x-app-service-key | The connected app’s service key |
Body
| Field | Required | Description |
|---|---|---|
to | Yes | Recipient’s phone number with country code, digits only, e.g. 919876543210. |
category | Yes | TRANSACTIONAL or SYSTEM. PROMOTIONAL is refused: send marketing through campaigns. |
template_name | Yes | Name of an approved template in your workspace. |
language_code | No | Template language, default en_US. |
template_variables | If the body has variables | Array of strings in order, or an object keyed by variable name. |
header_variables | If the header has a variable | Array or object, like template_variables. |
header_media_url | No | Public https link for an image, video or document header. Defaults to the template’s approved sample. |
header_media_id | No | A WhatsApp media ID, instead of header_media_url. |
header_location | If the header is a location | { latitude, longitude, name?, address? } |
button_variables | If a button has a variable | Array of strings for the dynamic part of a website button. |
coupon_code | If there is a copy-code button | The code to copy. |
offer_expiration | For limited-time offers | Expiry as epoch milliseconds, seconds or an ISO date. |
cards | For carousels | [{ header_media?, body_variables?, button_variables? }] |
notification_type | No | Your own label, such as order_shipped. Shown in the notification logs. |
app_user_id | No | Your own user ID for the recipient, for your records. |
title, body | No | A short summary for the logs. Not sent to the customer. |
metadata | No | Any JSON object you want kept with the log entry. |
Responses
200 — sent
{ "success": true, "wa_message_id": "wamid.HBgM…", "log_id": "…"}502 — WhatsApp refused the message
{ "success": false, "error": "(#131008) Required parameter is missing — …", "log_id": "…"}| Status | Meaning | What to do |
|---|---|---|
| 200 | Accepted by WhatsApp | Keep wa_message_id if you want to match delivery events later. |
| 400 | A required field is missing or invalid | Fix the request; the error says which field. |
| 401 | Missing or invalid app credentials, or the app is inactive | Check the headers and that the app is active. |
| 502 | WhatsApp refused the message, or a template value is missing | Read error. Don’t retry until you have fixed the cause; see Errors and limits. |
| 5xx (other) | Temporary problem | Retry with a growing delay. |
Retries
A send is not deduplicated. If a request times out, check the notification logs before retrying, or the customer may get the message twice.
Check credentials
HTTP
GET https://api.example.com/health/authSame headers. Returns { "ok": true, "app_id": "…", "name": "…" }, or 401. Useful as a startup check in your backend.
Still stuck? Contact us with what you were doing and the exact message you saw.