Links

Template messages

Conversation-based pricing is changing starting June 1, 2023 and Message template categories will be updated on April 1, 2023. From June 1, conversations will be priced by the new category of your message template.
Please see Meta's Official Pricing Change Documentation to see details about it.
We are gradually updating our documentation and will share more details with Partners soon.
A message template is required for the Business to start a new conversation with User. This is required if there was no interaction between the accounts previously or if the last message sent by the User has more than 24h. See more information about this here.
Template messages must be submitted to Meta for approval before they are available to use. These messages are stored on a WABA level, so multiple phone numbers in the same WABA can use the same template messages.
Each WhatsApp Business Account can have up to 250 message templates. That means 250 message template names, and each of them can have multiple language translations. For example, a message template called hello_world translated into two languages counts as a single message template in regards to this limit.

Manage your Template Messages

There are multiple ways to submit a Template Message for approval and manage your approved templates.

In the Partner API

Use the following endpoint to submit new template for approval.
post
https://hub.360dialog.io/api/v2
/partners/{partner_id}/waba_accounts/{waba_account_id}/waba_templates
Create new WABA template

Template Variables

Any template that has one or more variables requires a sample in order to be submitted for review. You can add samples by including the example property in API request. From April 1, 2023, you will also be able to include allow_category_change=true in your API request to avoid template rejection due to miscategorization. Including this parameter and value will allow Meta to assign whatever category they determine to be appropriate.
For example:
{
"name": "sample",
"category": "UTILITY",
"components": [
{
"format": "TEXT",
"text": "New request",
"type": "HEADER"
},
{
"type": "BODY",
"text": "Hi {{1}}, thanks for getting in touch with {{2}}. We will process your request get back to you shortly",
"example": {
"body_text": [
[
"Emilia",
"360dialog"
]
]
}
},
{
"text": "WhatsApp Business API provided by 360dialog",
"type": "FOOTER"
}
],
"language": "es_ES"
}
You can also edit, retrieve or delete template messages from a specific account.
post
https://hub.360dialog.io/api/v2
/partners/{partner_id}/waba_accounts/{waba_account_id}/waba_templates
Edit WABA template
Edited templates will be submitted to Meta for approval once in a 24-hour window or up to 10 times in a 30-day window. See Meta's Template Editing rules.
get
https://hub.360dialog.io/api/v2
/partners/{partner_id}/waba_accounts/{waba_account_id}/waba_templates
Get WABA templates
delete
https://hub.360dialog.io/api/v2
/partners/{partner_id}/waba_accounts/{waba_account_id}/waba_templates/{template_id}
Remove a WABA template

In the 360dialog Hub

The Template Management UI in the 360dialog Hub supports both text and media templates and has the following functions:
  • Create and preview new template messages
  • Monitor current approval status of all your templates
  • Add different template Languages
  • Add variables to templates
  • Allow template category change
  • Copy, Edit and Delete templates
Edited templates will be submitted to Meta for approval once in a 24-hour window or up to 10 times in a 30-day window. The edited version will appear in the 360dialog hub with the "last sync" date, referencing to when it was last submitted.
You are able to access this UI by clicking in "Manage templates" under any WABA in your dashboard. You can create a new template by clicking in "+ Add template".
In order to add a variable, insert {{#}} at the given position, where # represents the variable index, which needs to start at {{1}}.
You can manage the template statuses in this same UI.
Draft
Pending
Approved
Rejected
Paused
Templates with a gray background are in draft mode and have not been submitted for review by Meta yet.
Pending Templates have a yellow background. Facebook is verifying the template request. Please wait until more information is given by Facebook.
Your Template has been approved by Facebook and may be used to send Template Messages to your clients.
This Template has been rejected.
This template is Paused from sending for a period of time. See Template Pausing.
You will receive a Hub Notification (as well as the client) when a template changes status.

Template Categories

A template message can have three different categories:
  • AUTHENTICATION
  • MARKETING
  • UTILITY

Utility templates

Utility templates relate to a specific, agreed-upon transaction and accomplish one of the following: Confirm, suspend, or change a transaction or subscription.
Any template that has a mix of utility and marketing content will be classified as a marketing template.
Definition
Examples
Confirm or suspend an existing transaction
  • "Your subscription has been renewed successfully!"
  • "Your flight has been rescheduled for tomorrow at 10 AM."
  • "Congratulations! Your purchase has been confirmed and will be shipped out shortly."
  • "Thank you for visiting the doctor, here is your treatment plan"
  • "Your order has been canceled; your refund will be processed in 7-10 days"
Change or update a transaction
  • "You have successfully checked in! Here’s your boarding pass for your flight"
  • "Your order has shipped! It will be delivered on Friday"
  • "Reminder: Your appointment is at 1pm on Tuesday"
  • "Your password was changed"
  • "Your profile was updated"
Account, billing, or payment notification
  • "Here is the monthly statement you requested"
  • "Your payment was accepted” / "Your payment failed"
  • Reminder: your payment is due on Tuesday"
  • "Here is your low-balance warning for account ending in -XXXX"
  • "Your pre-paid balance is low; click here to top up"

Authentication templates

By May 29, 2023, specific requirements will apply to authentication templates. We'll share more information on this topic soon.
Definition
Examples
Provide an authentication code to the user
  • "{{1}} is your verification code."
  • "{{1}} is your verification code. For your security, do not share this code."
  • "{{1}} is your verification code. This code expires in 15 minutes."

Marketing templates

Marketing templates are the most flexible – they do not relate to a specific, agreed-upon transaction and instead may relate to the business and/or its products/services. These templates may include promotions or offers; welcoming / closing messages; updates, invitations or recommendations; or requests to respond or complete a new transaction.
Any template that has a mix of utility and marketing content will be classified as a marketing template.
Definition
Examples
Promotions or offers
  • "If you buy 2 or more coffees, you’ll get $5 off!"
  • "Thanks for your order! Use code SAVE20 for 20% off your next order!
  • "Your pre-paid balance is low; click here to top up! Get a 10% bonus with code EXTRA10"
  • "Hey members join us tonight for this event"
Welcoming or closing messages
  • "This is Vinny’s Bakery and we are now on WhatsApp!"
  • "Hello, welcome to our profile on WhatsApp!"
  • "I'm sorry for the delay, my name is XX, how can I help you?"
  • "Thank you, have a good day"
  • "A question for you - how much time are you spending doing your hair?"
Updates, invitations, newsletters, or recommendations
  • "Our store has moved. Come and check us out!"
  • "We will be closed next Monday for the holiday"
  • "Good news! The product you saved is back in stock."
  • "Join us for our upcoming holiday gala!"
  • "Here are this month’s coupons – happy shopping!"
  • "We think you will love this – check out our new ice cream flavor"
Requests to respond or complete a new transaction
  • "Thank you for your order. We’d love your feedback. Please click here."
  • "Forgot something? We kept your items, click to check out"
  • "Your application is waiting for you. Click here to complete"
  • "You missed your recent appointment, tap here to rebook."

Template Statuses

Once a Template Message is created and approved, it can have the following statuses:
  • In-Review: Indicates that the template is still under review. The review process is done by Meta and it can take up to 24 hours.
  • Rejected: The template has been rejected during our review process or violates one or more of Meta's Policies.
  • Active - Quality pending: The message template has yet to receive quality feedback from customers. Message templates with this status can be sent to customers and will be monitored for rating. See Quality Rating.
  • Active - High Quality: The template has received little or 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 it is recommended 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.

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. 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 suspend 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 such attempts. You should only resume these campaigns once the template's status has been changed back to Active.
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 the status set back to Active.
Having Paused Templates won't impact the WABA from which the message template was sent, or cause the Messaging 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 WhatsApp Business Account may eventually be impacted. See WABA Policy Enforcement.

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 haven't suspended any automated messaging campaigns that relied on a paused template, they should start working again. However, we recommend that you hold any campaigns that rely on a template that has been paused until it is unpaused, because the API 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.

Webhook events for Template Status Change

A template status can change automatically, based on a review decision, appeal outcome, or a change to its quality rating. When a template status changes, you will be notified by WhatsApp Manager notification, email, and webhook notification. For that, we highly recommend that you subscribe to the template_category_update, which will notify you of the status changes to any of your templates. You must subscribe to each WhatsApp Business Account you'd like to get the updates. The webhook event is triggered every time a template message status is changed.
The field event will have waba_template_status_changed value set.
You will be able to identify which client (in client.id), WABA (in waba_account.id) and phone number (in setup_info.phone_number) is this template for. The new_status property shows the template status.
Example payload
{
"id": string,
"event": "waba_template_status_changed",
"data": {
"id": string,
"setup_info": {
"phone_number": string,
"phone_name": string
},
"client": {
"id": string,
"name": string,
"contact_info": {
"email": string
},
"partner_payload": null|string
},
"waba_account": {
"id": string,
"on_behalf_of_business_info": {
"id": string,
"name": string,
"type": string,
"status": string
},
"fb_account_status": string
},
"template": {
"id": string,
"external_id": string,
"name": string,
"new_status": string,
"language": string,
"rejected_reason": string
}
}
}

Appeals

Businesses can submit Template Appeals from the WhatsApp Business Manager. Meta's team reviews the case against the appealed violation and decides the outcome, which typically takes 24 to 48 hours. The appealed violation will either remain Unchanged, or be set as Reversed
If the WABA was created through Integrated Onboarding, the appeal review decision can be sent via the Business Manager. This is how to request a decision review:
  1. 1.
    From the Account Quality page, click on Rejected Message Templates.
  2. 2.
    Choose from the list of rejected templates and click Request Review.
  3. 3.
    Enter Appeal Reason and click Submit.
  4. 4.
    After submission, the request and the issue are moved to the In Review tab.
  5. 5.
    The appeal review decision will be sent via the Business Manager and typically takes 24 to 48 hours. The appealed violation will either remain Unchanged, or be set as Reversed.
If the WABA was created with OBO (On Behalf Of) our Support Team can assist with this request. Please file a support ticket through the 360dialog Hub and we will Appeal Templates for you.

Template Rejection due to Miscategorization

If your template is rejected due to miscategorization, you have the following options:
  • Appeal the rejection and explain your categorization decision.
  • Edit or create a template that doesn't contain mixed content. For example, if the template contains a delivery update (which we categorize as utility) and a discount code (which we categorize as marketing), remove the marketing content and categorize the template as utility.
  • Edit the Template category and submit the new category for Review through the WhatsApp Manager.
WABAs created using Integrated Onboarding can edit categories through WhatsApp Manager. If the WABA is on OBO (On Behalf Of) model, businesses will only be able to submit a new template.

Sending a Template Message

If the WABA is registered in On-premise API

post
https://waba.360dialog.io
/v1/messages
Send Template Message
It is only possible to send Templates with an Active status. A message template's status can change automatically from Active to Paused or Disabled based on feedback from customers. For this reason, we recommend that you monitor status changes to take appropriate actions whenever a message template that you rely upon becomes, or is in danger of becoming, paused or disabled.
Example 1 - Sending Basic Template Message
{
"to": "wa_id",
"type": "template",
"template": {
"namespace": "c8ae5f90_307a_ca4c_b8f6_d1e2a2573574",
"language": {
"policy": "deterministic",
"code": "en"
},
"name": "template_name"
}
}
Example 2 - Sending Media Template Message with Parameters
{
"to": "wa_id",
"type": "template",
"template": {
"namespace": "c8ae5f90_307a_ca4c_b8f6_d1e2a2573574",
"language": {
"policy": "deterministic",
"code": "en"
},
"name": "template_name",
"components": [{
"type": "header",
"parameters": [{
"type": "image",
"image": {
"link": "https://link-to-your-image.jpg"
}
}
]
}, {
"type": "body",
"parameters": [{
"type": "text",
"text": "John"
}, {
"type": "text",
"text": "1234abcd"
}
]
}
]
}
}

Adding a marketing opt-out button to your Template Message

WhatsApp provides a marketing opt-out button that can be added to any template message.
To use it, you will simply need to add the following to your template message sending:
{
"type":"FOOTER",
"text":"Not interested? Tap Stop promotions"
},
{
"type":"BUTTONS",
"buttons":[{"type":"QUICK_REPLY", "text": "Shop now"},
{"type":"QUICK_REPLY", "text": "Stop promotions"}]
}
Clients must take the necessary steps to store which clients have chosen to opt-out of receiving marketing templates and stop sending these messages to them.
There is no WhatsApp or 360dialog feature to collect this information.
Not doing so will negatively impact your block rate and quality score.
Using this button will help you:
  • Reduce block rate: You’ll have a lower risk of campaign stoppages as a result. A high block rate may cause a campaign to be suspended or the quality rating of your phone number to decline. Giving customers the option to opt out instead of blocking your business ensures that campaigns can run uninterrupted.
  • Allow faster scaling: Your business may encounter quality issues as you scale your marketing outreach on WhatsApp. This usually happens when customers block certain templates. Allowing customers to opt out of marketing messages may reduce your block rate, which may help you increase your messaging limits faster.
  • Give customers options for how they want to hear from you: By letting customers opt out of marketing messages, you’ll keep your ability to contact them with critical information such as transactional and customer care messages.
  • Obtain better insights into customer preferences: Currently, your business can’t see which customers have blocked you. With the opt-out button, you will be able to see who has opted out of your marketing messages. This can help you learn from and improve your campaigns.

Example 3 - Template message with opt-out button

{
"name": "promotional_message",
"language": "en_US",
"category": "MARKETING",
"components": [{
"type":"BODY",
"text":"Hi {{1}}, get an extra 10% off every order above $300.",
"example":{"body_text":[["Sonia"]]}
},
{
"type":"HEADER",
"format":"TEXT",
"text": "Bonus Tuesday starts now!"
},
{
"type":"FOOTER",
"text":"Not interested? Tap Stop promotions"
},
{
"type":"BUTTONS",
"buttons":[{"type":"QUICK_REPLY", "text": "Shop now"},
{"type":"QUICK_REPLY", "text": "Stop promotions"}]
}]
}

If the WABA is registered in Cloud API

post
https://waba-v2.360dialog.io
/messages
Send Template Message
It is only possible to send Templates with an Active status. A message template's status can change automatically from Active to Paused or Disabled based on feedback from customers. For this reason, we recommend that you monitor status changes to take appropriate actions whenever a message template that you rely upon becomes, or is in danger of becoming, paused or disabled.
Any variables can be added with the Localizable Parameters. See the documentation on how to use it here.
Example 1 - Sending Basic Template Message
{
"messaging_product": "whatsapp",
"to": "wa_id",
"type": "template",
"template": {
"namespace": "c8ae5f90_307a_ca4c_b8f6_d1e2a2573574",
"language": {
"policy": "deterministic",
"code": "en"
},
"name": "template_name"
}
}
Example 2 - Sending Media Template Message with Parameters
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "template",
"template": {
"name": "TEMPLATE_NAME",
"language": {
"code": "LANGUAGE_AND_LOCALE_CODE"
},
"components": [
{
"type": "BODY",
"parameters": [
{
"type": "TEXT",
"text": "text-string"
},
{
"type": "CURRENCY",
"currency": {
"fallback_value": "VALUE",
"code": "USD",
"amount_1000": NUMBER
}
},
{
"type": "DATE_TIME",
"date_time": {
"fallback_value": "DATE"
}
}
]
}
]
}
}
Example 3 - Template message with opt-out button
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "template",
"template": {
"name": "promotional_message",
"language": "en_US",
"category": "PROMOTIONAL",
"components": [{
"type":"BODY",
"text":"Hi {{1}}, get an extra 10% off every order above $300.",
"example":{"body_text":[["Maria"]]}
},
{
"type":"HEADER",
"format":"TEXT",
"text": "Bonus Tuesday starts now!"
},
{
"type":"FOOTER",
"text":"Not interested? Tap Stop promotions"
},
{
"type":"BUTTONS",
"buttons":[{"type":"QUICK_REPLY", "text": "Shop now"},
{"type":"QUICK_REPLY", "text": "Stop promotions"}]
}]
}
}

Best Practices for a high-quality opt-out experience

We recommend that you continue to optimize the user experience when designing your opt-out flow.
Here are some tips for creating a high-quality opt-out experience:
  • Honor all opt-out requests: It is important that your business takes the necessary steps to stop sending marketing messages to customers who have opted out. Otherwise, you’ll create a negative experience for your customers, which may impact your block rate and quality score. Also, you should stop sending marketing messages to these customers from all of your WhatsApp phone numbers.
  • Send a confirmation reply to customers who request to opt out to:
    • Include an option for customers to opt back in. This is helpful for people who change their minds or who have accidentally tapped the marketing opt-out button.
    • Ask customers for feedback on why they’ve opted out or what types of content they prefer to receive instead. This can help your business improve marketing messages and audience targeting.
  • Identify messages to add the marketing opt-out button to: Adding a marketing opt-out button to every message may be repetitive and even encourage customers to opt out. We see opt out works best when included in the following types of messages:
    • The first message a customer receives from your business.
    • The first message after a longer period without marketing messages.
    • Messages that are sent to unengaged customers.

Best practices to get your Template Message approved

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 the WhatsApp Manager and WhatsApp will send an email to your Business Manager admins. In addition, you will receive a webhook notification if you are subscribed to message template status changes. See Get webhook notifications for Quality Rating.
If the Template Message is approved, its status will be set to Active - Quality pending and you can start sending it to customers.
See below some tips for increasing the chances of getting your Template Messages approved:
Clarity: be specific and clear. The reviewers may not know a customer’s business and need more clarity.
Avoid spam promotion: You should avoid using language or tactics that are designed solely to promote a product or service, without providing any real value or benefit to the user. It's important to be mindful of several activities that could fall under this category, such as upselling, cold-calling, or using language that may sound overly promotional.
Spelling: check for spelling and grammatical errors and use appropriate formatting (e.g., double curly brackets for parameters). Name: make your message template name clear. Instead of using a name like template_014, use bus_ticket_details. Remember that someone from Facebook will be reviewing your templates. Providing more clarity gives reviewers context around how the template will be used. Create context: if you need to write a message template to re-open the 24-hour window, we would suggest starting with some mention of the previous conversation thread. Make sure it's easy to navigate and understand, and that it provides a positive user experience. Choose an appropriate category: don’t forget to use the correct message template type. Choosing the correct one will increase the chances of getting your templates approved and will provide more information to WhatsApp during the approval process. See Template Categories. Header (optional): you can add a title or choose which type of media you'll use for this header. Image, PDF and Video is supported. Location Header will be available soon.

Examples

Deal Promotion
Get in touch
Appointment Reminder