# Sending Template Messages

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](/docs/resources/templates.md#template-statuses). 

Currently, it is possible to send the following template types:

* [Text-based message templates](/docs/messaging/overview.md#send-text-messages): 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](/docs/messaging/media.md): When sending messages with media such as images, videos, or audio files, see our Media documentation to find details. 
* [Interactive message templates](/docs/messaging/message-types/interactive.md): Interactive message templates expand the content beyond the standard message template and media messages template types to include interactive buttons. 
* [Multi-Product Message templates](/docs/resources/templates/multi-product-templates.md): Showcase products to customers directly from a template message. 
* [Location-based message templates](/docs/messaging/message-types/contacts.md): Send location-based message templates. 
* [Authentication templates ](/docs/resources/authentication-messages.md)with one-time password buttons: Specific Authentication Templates to authenticate and validate OTPs directly from WhatsApp.

## API Reference

<mark style="color:green;">`POST`</mark> `https://waba-v2.360dialog.io/messages`

#### Request Body

<table><thead><tr><th width="356">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>to<mark style="color:red;">*</mark></td><td>string</td><td>Recipient wa_id</td></tr><tr><td>type<mark style="color:red;">*</mark></td><td>string</td><td>Message type</td></tr><tr><td>language<mark style="color:red;">*</mark></td><td>string</td><td>Template language</td></tr><tr><td>policy<mark style="color:red;">*</mark></td><td>string</td><td>Delivery policy</td></tr><tr><td>code<mark style="color:red;">*</mark></td><td>string</td><td>Language code</td></tr><tr><td>name<mark style="color:red;">*</mark></td><td>string</td><td>Template name</td></tr><tr><td>messaging_product<mark style="color:red;">*</mark></td><td>string</td><td><strong>Required  for Cloud API.</strong><br>Messaging service used for the request. Use <code>"whatsapp"</code>.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}
A successful response includes an object with an identifier prefixed with `wamid`. Use the ID listed after `wamid` to track message status.

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

{% endtab %}
{% endtabs %}

## Delivery Sequence of Multiple Messages&#x20;

When sending a series of messages, the order in which messages are delivered is not guaranteed to match the order of API requests. To ensure the sequence of message delivery, confirm receipt of a delivered status in a Messages Webhook before sending the next message in a sequence. See [Webhooks and events.](/docs/messaging/webhook/webhook-reference.md)

## Template Pacing&#x20;

{% hint style="info" %}
**Starting April 30, 2024, template pacing applies to both marketing and utility templates**.

For Marketing Templates 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.
{% endhint %}

Template pacing is a mechanism that allows time for customers to provide early [feedback](broken://pages/-MjnHcIHSKX291K243SB#quality-rating) on newly created or unpaused marketing or utility templates. This identifies and pauses 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.

Template pacing is valid for **utility and marketing** templates. Newly created templates, [paused templates that are unpaused](/docs/resources/templates.md#template-pausing), and templates that may have been created previously but don’t have a `GREEN` quality rating are potentially subject to pacing. [Template quality history ](/docs/resources/templates.md#template-statuses)— for example, low quality resulting in a template pause — is one of the primary reasons for template pacing and other templates may get paced.

When a template is paced, 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. Once Meta receives a good quality signal, subsequent messages using that template will be scaled to the entire target audience. If they receive a bad quality signal, subsequent messages using that template will be dropped, giving the business the opportunity to adjust content, targeting, etc.

#### Utility Template Pacing <a href="#utility-template-pacing" id="utility-template-pacing"></a>

Utility templates are subject to pacing only if  the number had a utility [template paused.](/docs/resources/templates.md#template-pausing) Once a utility template has been paused, newly created templates, paused templates that are unpaused, and templates that may have been created previously but don’t have `GREEN` quality rating are potentially subject to pacing for the next 7 days.

#### API Behaviour

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. &#x20;

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`](https://docs.360dialog.com/partner/integration/webhook-events-and-notifications#message-template-updates) will send the quality update and the [`messages`](/docs/messaging/webhook/webhook-reference.md#messaging-webhooks-associated-with-messaging-api) 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` ](/docs/messaging/webhook/webhook-reference.md#template-held-for-pacing)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"`&#x20;
* A  [`message_template_quality_update`](/docs/messaging/webhook/webhook-reference.md#message-status-updates) 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](/docs/resources/templates.md#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. ](/docs/messaging/webhook/webhook-reference.md#messaging-webhooks-associated-with-messaging-api)

appropriate `messages` webhooks. See [Webhooks and events.](broken://pages/fpiZM6bgn9YcWqPSatjX#messaging-webhook-associated-with-messaging-api)&#x20;

## Per-User Marketing Template Message Limits

{% hint style="warning" %}
This limit is not active in these countries: European Economic Area, United Kingdom, Japan, South Korea
{% endhint %}

WhatsApp may limit the number of marketing template messages a person receives from any business in a given period of time, starting with delivering fewer marketing conversations to those users who are less likely to engage with them. In most WhatsApp markets, this is determined based on a number of factors, including a dynamic view of an individual’s marketing message read rate, and is not related to a specific business.

For individuals with United States phone numbers (numbers composed of a +1 dialing code and a US area code), where WhatsApp is growing quickly but at an earlier stage, WhatsApp will not deliver any marketing template messages to focus on building the consumer experience.

#### Why it's important <a href="#why-it-s-important" id="why-it-s-important"></a>

WhatsApp has found that per-user marketing template limits maximize message engagement and improve the user experience, measured through improvements in user read rates and sentiment. This limit helps WhatsApp users find business messaging more valuable and feel less like they receive too many business messages.

#### How this Applies <a href="#how-this-applies-to-your-business" id="how-this-applies-to-your-business"></a>

The limit only applies to[ marketing template messages](/docs/resources/templates.md#marketing-templates) that would normally open a [new marketing conversation. ](/docs/get-started/pricing/free-vs-billed-messaging.md)If a marketing conversation is already open between business and a WhatsApp user, marketing template messages sent to the user will not be affected. Further marketing template messages can only be sent in an open marketing conversation if the person responds to any message.

Example:

* The first marketing template message is delivered and opens a new [24-hour marketing conversation ](https://app.gitbook.com/o/-M4UA2Des2wa1sGak_JB/s/-M4sMxKjL6eJRvZn6jeG-887967055/~/edit/~/changes/2393/get-started/pricing/free-vs-billed-messaging)customer service window. The per-user marketing template message limit applies.
* A second marketing template message can be sent in an existing conversation.
* Each time a WhatsApp user responds in an existing conversation window, the ability is granted to send one additional marketing template message. Unlimited [free-form](https://app.gitbook.com/o/-M4UA2Des2wa1sGak_JB/s/-M4sMxKjL6eJRvZn6jeG-887967055/~/edit/~/changes/2393/get-started/pricing/free-vs-billed-messaging) messages. may also be sent.

#### What to watch for: `131049` Error Code <a href="#how-we-notify-via-error-code" id="how-we-notify-via-error-code"></a>

If a marketing template message is not delivered to a given user due to the limit, Cloud API will return error code `131049` with the description *“This message was not delivered to maintain a healthy ecosystem engagement.”*  See error code: `131049` in [Error Messages.](https://docs.360dialog.com/docs/support/api-error-message-list#other-meta-messaging-errors)

When this error is received avoid immediately resending the template message to the same user, as it will only result in another error response. Instead, wait at least 24 hours before attempting a resend.

This error does not affect ability to send marketing messages to other users.

### Experiments <a href="#experiments" id="experiments"></a>

Meta's ongoing experiment on the WhatsApp Business Platform is focused on evaluating how marketing messages impact consumer experience and engagement. As part of this experiment, **approximately 1% of WhatsApp consumers will not receive marketing messages.**

Businesses will not be charged for undelivered messages. While there is no guaranteed timeframe for how long a number may be part of the experiment, we do not recommend retrying to send marketing messages to consumers with experimentation error codes unless there is an active conversation open. See [Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/experiments?content_id=4j0t9YFqVY0Mq3p) on Meta's Official Documentation.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.360dialog.com/docs/resources/templates/sending-template-messages.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.