Skip to main content
This guide shows how to send messages through an official (WABA) instance. The endpoint is the same as for unofficial instances, POST /v1/wa/messages, with the same request signature. Zapster converts your payload into Meta’s Cloud API format automatically.

Before you start

  1. You need a connected WABA instance.
  2. 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.
  3. WABA instances do not send to groups. If you need groups, use an unofficial instance. See the comparison in WABA vs unofficial.
In every example below, replace 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 the media 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.
To send a video or document, just change the URL. Example of a document with a file name:

Interactive buttons

On WABA, buttons become Cloud API interactive messages and follow Meta’s rules: up to 3 reply 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

Remember: on WABA there can only be 1 url 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. The template 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 the payload of a quick reply or the suffix of a URL.
Template variables can be positional ({{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 a parameter_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 a 400 error explaining why. Nothing is silently dropped or adapted.

Next steps