Message Templates

Message templates are used to initiate conversations with customers. Unlike other types of messages, message templates are the only type of message that can be sent to customers who have yet to initiate a conversation with you, or who have not sent you a message in an existing conversation thread within the last 24 hours.

Message templates must be approved before you can send them to customers. In addition, templates may be disabled automatically based on customer feedback. Once disabled, a message template cannot be sent to customers again until its quality rating has improved or it no longer violates our business or commerce policies.

Creation

You can use the WhatsApp Manager to manually create message templates and submit them for approval. Alternatively, you may use the WhatsApp Business Account - Message Templates endpoint to create them programmatically.

To access the WhatsApp Manager:

1. Go to the Apps Panel and select your app to load it in the App Dashboard.
2. Click the WhatsApp product in the menu on the left.
3. In the Get Started panel, scroll down to Step 5 and click see the Overview page.

Once you are in WhatsApp Manager > Overview:

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. Click the Create template button and fill out the form. Be sure to use the + Add variable button to insert placeholders for any variable content you will supply whenever you send the template.
4. Click Add Sample to add sample values to your template. This is optional, but highly recommended. See Samples.
5. Click Submit to submit your template for approval.

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

We highly recommend that you include a sample before submitting your template for approval. Samples allow you to supply sample media assets and sample text values for any media or text variables that your template requires. This makes it easier for us to visualize how your template will appear to customers.

In addition, if your submission is rejected and you decide to appeal, you will need to include a sample in your appeal anyway, so it's better to include one with your initial submission.

To include a sample with your submission, 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.

Common Rejection Reasons

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

• 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.
• 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.
• 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. A rejection notification that includes the rejection reason will appear in Account Quality on WhatsApp Manager and be sent via email. You may refer to the Account Quality 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. Please note that this check does not apply to OTP templates.

Editing

You can edit a template using the WhatsApp Manger 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 Message Templates

Once a message template has been approved you may begin sending it to customers. To send a message template, see Send Message Templates for Cloud API users, or Sending Message Templates for On-Premises API users.

Only templates with an Active status (e.g., Active - Quality Pending, Active - High Quality, etc.) can be sent to customers.

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 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 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. 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. 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.

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.

Quality Rating

Every message template has a quality rating based on usage and customer feedback. A message template's rating will appear in the WhatsApp Manager whenever it has an Active status, and will 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, 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.

We do not offer webhooks for message template feedback or quality rating changes, but we can send you a webhook notification if there is a change to a message template's status. Therefore, we recommend that you set up webhooks and listen for changes to template status and take appropriate actions before your template becomes paused or disabled. See Monitoring Status Changes.

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. 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.

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.

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

• WhatsApp Business Policy – Learn more about our business policies
• WhatsApp Commerce Policy – Learn more about our commerce policies
• Policy Enforcement – Learn more about how we enforce policy