Template messages

Last update: 6 hours ago by Irais Aguirre

Template messages are pre-approved, reusable message templates with variable placeholders, and are the only way to start a conversation with a customer.

Integration summary
Endpoint: POST https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging
Token: messaging token, in the Authorization: Bearer {{wa-msg-api-token}} header (how to generate it)
Common fields: from, to (phone number or BSUID) and type (details)
Response: the same for every message (see response) About template messages:

Templates are messages that can contain text and media (image, document, video).
You can replace variables (placeholders) in a template to personalize a message.
Templates are the only way to start a conversation with your customer.
Templates must be approved by WhatsApp before you can use them. Please contact our Operations team for guidance through the approval process.

All template messages are sent with POST /v1/messaging; headers, common fields and the response are in HTTP connection.

In this section:

Text, currency and date: Text, currency and date-time parameters that are substituted in the header and body components of the template.
Media and location: Image, document, video and location parameters for the header component of the template.
Buttons: Templates with buttons: quick reply, one-time password, call and open URL.
WhatsApp Flows: Templates that open a WhatsApp Flow.
Carousel: Carousel templates with scrollable cards.
Coupons and limited-time offers: Templates with coupon codes and limited-time offers.

General structure

The type field must be "template". The from and to fields are described in Common fields.

Name	Description	Type	Requirements
template	Object containing the template properties.	Object	Required

Template object

Name	Description	Type	Requirements
language	Template locale. Example: es_ES, es_MX, es_US	String	Required
name	Template name.	String	Required
components	Array of objects containing the template configuration.	Array	Optional

Components object

Name	Description	Type	Requirements
type	Component type. Possible values: header: the template header. body: the template body. button: action buttons for the template. footer: the template footer. carousel: a single text message accompanied by a set of up to 10 carousel cards in a horizontally scrollable view. limited_time_offer: lets you display expiration dates and countdown timers for offer codes.	String	Required
subtype	quick_reply: a previously created quick reply button that lets the customer send back a predefined message. url: a previously created button that lets the customer visit the URL built by appending the text parameter to the predefined URL prefix in the template. catalog: a previously created catalog button that lets the customer get back a full product catalog. copy_code: coupon-code copy button. flow: button that opens a WhatsApp Flow. voice_call: button that starts a WhatsApp voice call to the business. call_permission_request: button that asks the user to grant call permission. mpm: multi-product message button. spm: single-product message button. order_details: button for order details (Payments Brazil). order_status: button for order status (Payments Brazil). payment_request: button for payment request (Payments Brazil).	String	Required when used with the button type.
index	Index for payload-type parameters.	Integer	Optional Used with the button type. Possible index values: 0, 1, 2
parameters	Array of template parameter types. Possible values: text currency date_time image document video location payload action coupon_code limited_time_offer gif	Array	Optional (required for `limited_time_offer` components)

Parameter types by component type

Parameter type	header	body	button
text	Yes	Yes	Yes (URL/OTP)
currency	Yes	Yes	No
date_time	Yes	Yes	No
image	Yes	No	No
document	Yes	No	No
video	Yes	No	No
location	Yes	No	No
payload	No	No	Yes
action	No	No	Yes
coupon_code	No	No	Yes

WABA ID (server-derived)

The target WhatsApp Business Account (WABA) for a template send is not read from the request body. It is derived from the Authorization: Bearer {token} header: the messaging token is bound to one WABA at issue time, and that WABA is used for every send under the token.

You don't need to send wba_id / waba_id in the message body. Any such field is ignored for routing.
To send from a different WABA, generate a new messaging token for that WABA.
Admin endpoints (template management, groups, etc.) still take {{waba_id}} in the URL path because an admin token may belong to a user who manages multiple WABAs.

Call permission request

Text, currency and date