POST /v1/wa/messages, with the same request signature. Zapster converts your payload into Meta’s Cloud API format automatically.
Before you start
- You need a connected WABA instance.
- Free messages (text, media, buttons) are only delivered inside the 24-hour conversation window, which opens when the customer messages your number. Outside the window, use a template approved by Meta.
- WABA instances do not send to groups. If you need groups, use an unofficial instance. See the comparison in WABA vs unofficial.
YOUR_API_TOKEN with your API token and YOUR_INSTANCE_ID with the WABA instance ID.
Free messages (text, media, and buttons) sent through an official instance are free until September 30, 2026. Starting October 1, 2026, Meta begins charging for them. Learn what changes in WhatsApp official (WABA) message pricing.
Plain text
Media (image, video, or document)
Send the media by public URL or base64 in themedia field. The type (image, video, document) is detected automatically from the file. For documents, you can set fileName to control the name shown in WhatsApp.
Interactive buttons
On WABA, buttons become Cloud API interactive messages and follow Meta’s rules: up to 3reply buttons, or exactly 1 url button, without mixing the two types. The call and copyable buttons do not exist in session messages (see Common errors). The full matrix is in Messages with buttons.
When you send media together with buttons, the media becomes the header of the interactive message (image, video, or document; audio is not supported). If you send media.caption and text together, caption takes priority and becomes the message body.
Quick reply buttons with an image
Link button (url) with an image
Remember: on WABA there can only be 1url button in the message, and it cannot be combined with reply buttons.
Template (outside the 24h window)
Templates must be created and approved with Meta before sending. Thetemplate field is mutually exclusive with text and media.
The
template object is a mirror of Meta’s format. Zapster only wraps name and language (which becomes { "code": ... }) and passes the components array exactly as you send it to the Cloud API, without reinterpreting it. So use the same format as Meta’s Cloud API template documentation.components describes the parts of the template that receive values at send time:
header: a header with media (image, video, or document) or with a text variable.body: the body, where the variables of the approved text go.button: the buttons that carry a dynamic value, such as thepayloadof a quick reply or the suffix of a URL.
{{1}}, {{2}}, filled by the order of the parameters array) or named ({{customer_name}}, filled by parameter_name). Each template uses one style or the other, never both at once. The values you send must match what the approved template expects.
Simple example (positional variable)
With header, positional variables, and buttons
This template has an image header, two positional variables in the body ({{1}} and {{2}}), and two buttons: a quick reply (with payload) and a dynamic URL (its text becomes the suffix appended to the template’s base URL). The button index follows the order it appears in the approved template.
Named variables
When the template was approved with named variables, each parameter carries aparameter_name in addition to type and text. The rest of the request (the recipient, the headers, the name, and the language) is the same as the examples above. Only the components content changes:
components (named variables)
Do not mix positional and named variables in the same template. Use
parameter_name only when the template was approved with named variables; otherwise, use the positional form (just type and text, in the order they appear).Message billing
The official channel (WABA) is paid, and the party that charges for messages is Meta, not Zapster. The free messages in this guide are free until September 30, 2026 and start being charged from October 1, 2026. Templates keep their own charge. To understand what changes in 2026, the dates, and how the price is set, see WhatsApp official (WABA) message pricing.Common errors
When the payload uses a feature the Cloud API does not support, Zapster rejects the request right away with a400 error explaining why. Nothing is silently dropped or adapted.
Next steps
- Messages with buttons for the full support matrix by connection type
- Send messages to a BSUID to reply to users with a hidden phone number (username / BSUID)
- WABA vs unofficial to choose the instance type
- Connecting a WABA instance