Send a pre-approved WhatsApp template message to a contact. Use this endpoint to
initiate a conversation outside the 24-hour customer service window — for example,
notifications, marketing campaigns, or re-engagement messages. To reply within an
active 24-hour session, use sendSessionMessage instead.
Behavior:
- The
template_namemust reference a template that has been approved by WhatsApp.
Requests referencing pending or rejected templates return 400. parametersare positional: the order in the array must match the placeholder
order in the approved template body (e.g., {{1}}, {{2}}, …).broadcast_nameis used for grouping and analytics in WATI dashboards; it does
not affect message delivery.channel_numberroutes the message through a specific WhatsApp Business Account
when the tenant has multiple WABAs connected.- A 200 response means the message was accepted by WATI, not delivered yet.
- To detect delivery failures, listen to the Template Message Failed webhook.
- To detect successful delivery, listen to the Delivered, Read, or Reply
webhooks. - Marketing-category templates are subject to per-tenant daily limits; once the
limit is reached, subsequent calls return 400 until the next window. - The endpoint returns 400 when the tenant is in offline mode or when the
trial-plan broadcast quota is exhausted.
Permissions
For API access tokens and OIDC tokens, satisfy at least one of: api, wati_integration:write, messagetemplate:write. API access tokens may satisfy a listed scope through the configured scope hierarchy; OIDC tokens are checked against their scope claims. Legacy JWT authentication does not use this scope check. Authentication, role, tenant, and applicable feature or plan checks still apply. For HTTP 403, check the credential type, applicable scopes, roles, and workspace access; 403 does not always mean a missing scope. Authentication/authorization failures do not guarantee a JSON response body.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
400Request was rejected. Common causes: template name not found or not approved, missing/extra parameters, daily marketing-broadcast limit reached, tenant in offline mode, or invalid WhatsApp number.
401Missing or invalid bearer token.
403The authenticated request is forbidden. Authorization failed. Check the Permissions section for the credential-specific scope rules, and check roles and workspace access. The response may have no body; do not require a JSON error envelope.

