WhatsApp Business Platform

Templates

Templates are used in template messages to open marketing, utility, and authentication conversations with customers. Unlike other message types, template messages are the only type of message that can be sent to customers who have yet to message you, or who have not sent you a message in the last 24 hours.

Templates must be approved (have a status of APPROVED) before they can be sent in template messages. Note that templates may be paused or disabled automatically based on customer feedback, engagement, or for violations of our business or commerce policies. This document describes what to do in these situations.

Creation

Use the Business Management API to create templates. See Create and Manage Templates to learn how. Alternatively, you can use the WhatsApp Manager to manually create templates.

Approval Process

Once you have created your template you can submit it for approval. It can take up to 24 hours for an approval decision to be made. Once a decision has been made, a notification will appear in your WhatsApp Manager and we will send an email to your Business Manager admins. In addition, we will send a webhook notification if you are subscribed to message template status changes. See Monitoring Status Changes.

If your message template is approved, it's status will be set to Active - Quality pending and you can begin sending it to customers. If it is rejected, you can edit it and resubmit for approval, or appeal the decision.

Samples

If your template uses variables you must include sample variable values (media assets, text strings, etc.) with your submission. This makes it easier for us to visualize how your template will appear to customers.

To include a sample with your submission in the WhatsApp Manager, first create your template, adding any variables that it requires, then click the Add Sample button. The preview pane will render any sample media assets or sample text values you provide.


If using our APIs to create templates, include the examples property for each template component object in your request that uses a variable.

Common Rejection Reasons

Submissions are commonly rejected for the following reasons, so make sure you avoid these mistakes.

Parameter Formatting

  • Variable parameters are missing or have mismatched curly braces. The correct format is {{1}}.
  • Variable parameters contain special characters such as a #, $, or %.
  • Variable parameters are not sequential. For example, {{1}}, {{2}}, {{4}}, {{5}} are defined but {{3}} does not exist.
  • Template contains too many variable parameters relative to the message length. You need to decrease the number of variable parameters or increase the message length.
  • The message template cannot end with a parameter.

Content and Policy Violations

  • The message template contains content that violates WhatsApp’s Commerce Policy: When you offer goods or services for sale, we consider all messages and media related to your goods or services, including any descriptions, prices, fees, taxes and/or any required legal disclosures, to constitute transactions. Transactions must comply with the WhatsApp Commerce Policy.
  • The message template contains content that violates the WhatsApps Business Policy: Do not request sensitive identifiers from users. For example, do not ask people to share full length individual payment card numbers, financial account numbers, National Identification numbers, or other sensitive identifiers. This also includes not requesting documents from users that might contain sensitive identifiers. Requesting partial identifiers (ex: last 4 digits of their Social Security number) is OK.
  • The content contains potentially abusive or threatening content, such as threatening a customer with legal action or threatening to publicly shame them.

Character Limits and Text Format

  • The body component will have different character limits depending on the format and tag of the template. The number of emojis allowed in the body component may also be limited.

Duplication

  • The message template is a duplicate of an existing template. If a template is submitted with the same wording in the body and footer of an existing template, the duplicate template will be rejected.

Rejection Notification

A rejection notification that includes the rejection reason will appear in Business Support Home. You can view rejections in the Business Support Home by navigating to Account Overview > View my accounts (button) > (your Meta Business Account) > (your WABA) > Rejected message templates. Rejection info will also be sent via email.

You can refer to the Business Support Home notification to see the name and language of the existing template with the same content as the rejected duplicate template. You may also choose to edit the template and resubmit.

Note: This check does not apply to templates categorized as AUTHENTICATION.

Editing

You can edit a template using the WhatsApp Manager or the Message Template endpoint. Note that if you edit a message template and resubmit it for approval, its status will be set to In Review and it can't be sent to customers until its status has been set to Active.

Sending Templates

Once a template has been approved (its status is set to ACTIVE) you may begin sending it to customers. To send a template using Cloud API, see Send Template Messages. To send a template using On-Premises API, see Sending Template Messages.

Note that a message template's status can change automatically from ACTIVE to PAUSED or DISABLED based on customer feedback and engagement. For this reason, we recommend that you monitor status changes and take appropriate actions whenever a message template that you rely upon becomes, or is in danger of becoming, paused or disabled.

Statuses

Templates can have the following statuses.

  • In-Review: Indicates that the template is still under review. Review can take up to 24 hours.
  • Rejected: The template has been rejected during our review process or violates one or more of our policies. See Appeals.
  • Active - Quality pending: The message template has yet to receive quality feedback or read-rate information from customers. Message templates with this status can be sent to customers. See Quality Rating.
  • Active - High Quality: The template has received little to no negative customer feedback. Message templates with this status can be sent to customers. See Quality Rating.
  • Active - Medium Quality: The template has received negative feedback from multiple customers, or low read-rates, but may soon become paused or disabled. Message templates with this status can be sent to customers. See Quality Rating.
  • Active - Low Quality: The template has received negative feedback from multiple customers, or low read-rates. Message templates with this status can be sent to customers but are in danger of being paused or disabled soon, so we recommend that you address the issues that customers are reporting. See Quality Rating.
  • Paused: The template has been paused due to recurring negative feedback from customers, or low read-rates. Message templates with this status cannot be sent to customers. See Template Pausing.
  • Disabled: The template has been disabled due to recurring negative feedback from customers. Message templates with this status cannot be sent to customers.
  • Appeal Requested: Indicates that an appeal has been requested. See Appeals.

You can view a template's status by going to WhatsApp Manager > Overview, mousing over the suitcase icon (Account tools) and clicking Message templates. If you have multiple WhatsApp Business Accounts, select the account whose template statuses you want to view from the list of accounts in the dropdown menu in the top-right corner.

Template Pacing

Starting April 30, 2024, template pacing applies to both marketing and utility templates.

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

Template pacing is valid for marketing and utility templates. Newly created templates, paused templates that are unpaused, and templates that may have been created previously but don’t have a GREEN quality rating are potentially subject to pacing. Template quality history — for example, low quality resulting in a template pause — is one of the primary reasons for template pacing and you may see other templates 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 we receive a good quality signal, subsequent messages using that template will be scaled to the entire target audience. If we receive a bad quality signal, subsequent messages using that template will be dropped, giving you the opportunity to adjust content, targeting, etc.

Utility Template Pacing

Utility templates are subject to pacing only if you have had a utility template paused. 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 Behavior

The immediate response from the messages endpoint will indicate if the message was sent or held with the new message_status property in the messages object. This response will be available on all versions of the API.

  • Cloud API will always include a message_status property that will have a value of accepted for messages that are processed, and held_for_quality_assessment for messages that are held. Messages that are accepted will trigger the sent and delivered webhooks when they are actually sent (this is the same behavior that existed before pacing). A full example response can be found in the Cloud API docs.
  • On-Premises API will include a message_status property with a value of ”Message has been held because quality assessment is pending” if the message is held. Messages that are sent will not include the property. A full example response can be found in the On-Premises API docs.

If the feedback is positive and changes the template's quality rating to high quality, the held messages will be released and sent normally. 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_status_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 we have 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. Our goal is that even if paced, campaign messages with highest throughput still get delivered within an hour (99 percentile).

Thus, if our 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.

Monitoring Status Changes

A template's status can change automatically, based on a review decision, appeal outcome, or a change to its quality rating. When a template's status changes, you will be notified by WhatsApp Manager notification, email, and webhook notification.

Since you can only send customers message templates with an Active status, we highly recommend that you subscribe to the message_template_status_update webhook field, which will notify you of any status changes to any of your templates. See Webhooks Setup to learn how to subscribe to this field, and Message Template Updates for sample webhook payloads.

If you have set up webhooks and see that a given message template is dropping in quality, go to WhatsApp Manager > Message templates and mouseover the message template in question. A tooltip should appear and display information about the nature of the problem. Based on this information, you may wish to edit the template and submit it for re-approval, use a different template, or change your app's business logic. If you do edit the message template and it is reapproved, its quality rating will gradually improve as long as it is being sent to customers and not receiving frequent negative feedback or low read-rates.

Quality Rating

Every message template has a quality rating based on usage, customer feedback and engagement. A message template's rating will appear in the WhatsApp Manager whenever it has an Active status, and will be displayed after a hyphen in the message template's status:

  • Active - Quality pending (highlighted in green)
  • Active - High quality (highlighted in green)
  • Active - Medium quality (highlighted in yellow)
  • Active - Low quality (highlighted in red)

Approved message templates start out with a Quality pending rating. If a message template continuously receives negative feedback or low engagement, it will eventually cause a change in the template status. As long as a message template has an Active status, regardless of the quality rating, it can be sent to customers. However, once a message template's status changes to any other status, it cannot be sent to customers until it becomes active again.

You can be notified of changes to a template's quality rating by subscribing to the message_template_quality_update field.

See Message Template Quality Update for a sample webhook payload.

Template Pausing

If a message template reaches the lowest quality rating (a status of Active - Low quality), it will automatically be paused for a period of time to protect the quality rating of phone numbers that have used the template. Pausing durations are as follows:

  • 1st Instance: Paused for 3 hours
  • 2nd Instance: Paused for 6 hours
  • 3rd Instance: Disabled

When a message template is paused (status of Paused) it can't be sent to customers, so you should halt any automated messaging campaigns that rely on that template. Although you won't be charged for attempting to send a paused message template to a customer, and the attempt won't count against your messaging limit, the API will reject these attempts anyway. You should only resume these campaigns when the template's status has been set to Active again.

You may wish to edit a paused template if you feel that editing its content will reduce the amount of negative feedback it may receive and increase user engagement. Keep in mind, however, that once you edit a message template and resubmit it for approval, its status will change to In Review and it can't be sent to customers again until it has been re-approved and its status set to Active.

You may also wish to make changes to your business logic (targeting, delivery parameters, etc.) if you feel it is contributing to negative feedback or low engagement.

Pausing will initially not impact the business phone number from which the message template was sent, or cause the phone number's message limit to decrease. Other high quality message templates can continue to be sent from the phone number. However, if a business consistently sends message templates that reach a Low quality status, the phone number may eventually be impacted.

Pause Notifications

When a message template has been paused we will notify you by WhatsApp Manager notification, email, and webhook if you are subscribed to message template change webhooks. See Monitoring Status Changes for webhook setup information and Examples - Template Paused for a sample webhook payload.

Unpausing

A template will unpause on its own after satisfying the pause duration outlined above. Once unpaused, the template's status will be set to Active and you may begin sending it to customers again. If you didn't halt any automated messaging campaigns that relied on a paused template, they should start working again. However, we recommend that you halt any campaigns that rely on a template that has been paused until it is unpaused, because our APIs will reject your requests anyway.

The template's quality rating will also be reset to a value based on the most recent customer feedback the template has received.

Similar to pause notifications, we will notify you by WhatsApp Manager notification, email, and webhook once the template's status has been set to Active.

Applies to businesses in Brazil, Colombia, and Singapore, starting September 12, 2023. Applies to all businesses starting October 12, 2023.

With the introduction of Template Pacing, we’re also introducing the ability to unpause any paused template through:

Note that templates paused during Template Pacing must be manually unpaused (API or WhatsApp Manager) before they can be used again.

Appeals

If your submission is rejected you may file an appeal. Note that appeals must include a sample. If an approved template has become disabled, you may also edit it and resubmit it for approval.

In the WhatsApp Manager:

  1. Mouseover the suitcase icon (Account tools) and click Message templates.
  2. If you have multiple WhatsApp Business Accounts, use the dropdown menu in the top-right corner to select the account whose templates you want to manage.
  3. Find the message template that you would like to edit and click it.
  4. Edit the template's contents.
  5. Click the Add Sample button and add sample variable values and images.
  6. Click Submit.

The appeal will be reviewed and a decision made within 24 hours.

Learn More