Sending Template Messages

Sending a Template Message

It is only possible to send Templates with Active status. A message template status can change automatically from Active to Paused or Disabled based on feedback from customers. See Template Statuses.

Currently, you can send the following template types:

• Text-based message templates: To send a text-based message template, make a POST call to the endpoint below and attach a text message object.

• Media-based message templates: When sending messages with media such as images, videos, or audio files, see our Media documentation to find details.

• Interactive message templates: Interactive message templates expand the content you can send recipients beyond the standard message template and media messages template types to include interactive buttons.

• Multi-Product Message templates: Showcase your products to customers directly from a template message.

• Location-based message templates: Send location-based message templates.

• Authentication templates with one-time password buttons: Specific Authentication Templates to authenticate and validate OTPs directly from WhatsApp.

API Reference

POST https://waba-v2.360dialog.io/messages

Request Body

Name	Type	Description
to*	string	Recipient wa_id
type*	string	Message type
language*	string	Template language
policy*	string	Delivery policy
code*	string	Language code
name*	string	Template name
messaging_product*	string	Required for Cloud API. Messaging service used for the request. Use "whatsapp".

200

A successful response includes an object with an identifier prefixed with wamid. Use the ID listed after wamid to track your message status.

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

[will be deprecated] If the WABA is registered in On-premise API

As announced in November 2023, Meta is transitioning to a fully Cloud-hosted WhatsApp Business Platform and will stop supporting On-Premise API in October 2025.

Starting from On-Premise client v2.53, all new feature updates will be exclusively delivered to Cloud API. While the On-Premise API client will receive quarterly releases, they will focus solely on bug fixes and security patches. From May 15, 2024, 360dialog will not allow for new numbers to be onboarded with On-Premise API. We will continue supporting already registered On-Premise API throughout 2024, but we strongly recommend to start changing the hosting type of numbers to Cloud as soon as possible. Learn here how to integrate with Cloud API.

POST https://waba.360dialog.io/v1/messages

There is no limit to the number of parameters allowed in a Message Template.

Request Body

Name	Type	Description
to	string	Recipient wa_id
type	string	Message type
namespace	string	Template namespace
language	string	Template language
policy	string	Delivery policy
code	string	Language code
name	string	Template name

200

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

Delivery Sequence of Multiple Messages

When sending a series of messages, the order in which messages are delivered is not guaranteed to match the order of your API requests. If you need to ensure the sequence of message delivery, confirm receipt of a delivered status in a messages webhook before sending the next message in your message sequence. See Webhooks and events.

Template Pacing for Marketing Messages

Template pacing applies exclusively to marketing message templates. For campaigns with fewer recipients that do not reach their 'pace limit', their messages will not be subjected to pacing. This 'pace limit' number is dynamically determined by Meta and may vary depending on the template or business.

Template pacing is a mechanism that allows time for customers to provide early feedback on newly created or unpaused marketing templates. This identifies and pauses marketing templates that have received poor feedback, giving the business time to adjust their contents before they are sent to too many customers, thereby reducing the likelihood of negative feedback impacting the business.

Newly created marketing templates, and paused marketing templates that become unpaused, are subject to pacing. When one of these templates is used in a messaging campaign, messages will be sent normally until an unspecified threshold is reached. Once this threshold is reached, subsequent messages using that template will be held to allow enough time for customer feedback.

The immediate response from the messages endpoint will indicate if the message was sent (accepted) or held (held_for_quality_assessment) with the message_status property in the message object.

If the feedback is positive and changes the template's quality rating to high quality, the held messages will be released and sent normally which will trigger the sent and delivered webhooks. The message_template_quality_update will send the quality update and the messages webhook will send the sent and delivered updates.

If the feedback is negative and changes the template's quality to low quality:

• The template's status will be set to PAUSED

• A message_template_quality_update will be sent with an event value of paused

• Each held message will be dropped and trigger a messages webhook with "status":"failed" and "code":"132015" (Cloud API users) or "code":"2061" ( On-Premises API users)

• A message_template_quality_update webhook will be triggered with the quality change

• Admins of the WhatsApp Business Account owning business will be informed of the dropped messages by Meta Business Suite notification, WhatsApp Manager banner, and email

See Template Pausing to learn how to unpause a template that has been paused due to pacing.

Note that Meta has internal guardrails in place to ensure that we evaluate and make a pacing decision within a reasonable time to avoid impact on time sensitive campaigns. The goal is that even if paced, campaign messages with highest throughput still get delivered within an hour (99 percentile).

Thus, if Meta internal guardrails are reached before a template has received enough feedback to change its quality to high or low, the held messages will be released normally along with any appropriate messages webhooks. See Webhooks and events.

Per-User Marketing Template Message Limits

This feature is only valid for businesses in India. It will launch globally by April 1st, 2024.

Meta implemented a policy to limit the number of marketing conversations a user receives from any business over a specific timeframe, starting with a small number of conversations that are less likely to be read.

Note that the limit is determined based on the number of marketing template messages that person has already received from any business, and is not related to your business specifically.

The limit only applies to marketing template messages that would normally open a new marketing conversation. If a marketing conversation is already open between you and a WhatsApp user, marketing template messages sent to the user will not be affected.

If a marketing template message is not delivered to a given user due to the limit, the API will return a Message Undeliverable error code. Note, however, that this error code cover a wide range of issues that can result in non-delivery of a message, and for privacy reasons, Meta does not disclose if in fact the message was not delivered due to the limit. See error code: 131026 in Error Messages.

If you do receive one this error code and suspect it is due to the limit, avoid immediately resending the template message, as it will only result in another error response. Instead, retry in increasing larger time increments until the message is delivered, since the limit may be in effect for differing periods of time.