Codique

DevelopersNotifications API reference

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/send

Headers

HeaderValue
Content-Typeapplication/json
x-app-idThe connected app’s App ID
x-app-service-keyThe connected app’s service key

Body

FieldRequiredDescription
toYesRecipient’s phone number with country code, digits only, e.g. 919876543210.
categoryYesTRANSACTIONAL or SYSTEM. PROMOTIONAL is refused: send marketing through campaigns.
template_nameYesName of an approved template in your workspace.
language_codeNoTemplate language, default en_US.
template_variablesIf the body has variablesArray of strings in order, or an object keyed by variable name.
header_variablesIf the header has a variableArray or object, like template_variables.
header_media_urlNoPublic https link for an image, video or document header. Defaults to the template’s approved sample.
header_media_idNoA WhatsApp media ID, instead of header_media_url.
header_locationIf the header is a location{ latitude, longitude, name?, address? }
button_variablesIf a button has a variableArray of strings for the dynamic part of a website button.
coupon_codeIf there is a copy-code buttonThe code to copy.
offer_expirationFor limited-time offersExpiry as epoch milliseconds, seconds or an ISO date.
cardsFor carousels[{ header_media?, body_variables?, button_variables? }]
notification_typeNoYour own label, such as order_shipped. Shown in the notification logs.
app_user_idNoYour own user ID for the recipient, for your records.
title, bodyNoA short summary for the logs. Not sent to the customer.
metadataNoAny 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": "…"}
StatusMeaningWhat to do
200Accepted by WhatsAppKeep wa_message_id if you want to match delivery events later.
400A required field is missing or invalidFix the request; the error says which field.
401Missing or invalid app credentials, or the app is inactiveCheck the headers and that the app is active.
502WhatsApp refused the message, or a template value is missingRead error. Don’t retry until you have fixed the cause; see Errors and limits.
5xx (other)Temporary problemRetry 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/auth

Same 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.