Template messages
Conversation-based pricing is changing starting June 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.
Create new WABA template
POST https://hub.360dialog.io/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/waba_templates
The message template name field is limited to 512 characters. The message template content field is limited to 1024 characters.
Path Parameters
partner_id*
string
Your Partner Hub ID
Request Body
name*
string
category*
string
Allowed values: AUTHENTICATION, MARKETING, UTILITY
components*
array[object]
In addition, if Meta determines that a template has been miscategorized, its status will be set to REJECTED and you will receive a template status webhook indicating that it was rejected for miscategorization.
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. You can also 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:
You can also edit, retrieve or delete template messages from a specific account.
Edit WABA template
POST https://hub.360dialog.io/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/waba_templates
Update the WABA template and submit it to Facebook. Only components can be updated. Old companents are replaced with new components.
Request example
curl --request POST
--url https://hub.360dialog.io/api/v2/partners/partner_id/waba_accounts/waba_account_id/waba_templates/template_id
--header 'Authorization: '
--header 'Content-Type: application/json'
--data '{ "components": [ { "type": "BODY", "text": "nisi sun", "buttons": [ { "type": "Lorem", "text": "sit cillum officia dolor aute" } ], "format": "IMAGE", "example": { "header_text": [ "officia ad in aliquip" ], "body_text": [ "magna", "commodo" ], "footer_text": [ "in irure cillum commodo dolor", "commodo quis aliqua ad", "officia", "dolore ut", "sint quis" ] } }, { "type": "HEADER" }, { "type": "BUTTONS", "example": { "header_text": [ "do elit", "officia Lorem ", "id" ], "body_text": [ "non" ], "footer_text": [ "adipisicing", "occaecat reprehenderit ea sed aliqua", "ipsum", "s" ] }, "text": "Duis u", "format": "TEXT" } ] }'
Path Parameters
partner_id*
string
Your Partner Hub ID
template_id*
string
ID of the WABA template
Request Body
type*
string
Allowed values: BODY, FOOTER, HEADER, BUTTONS
text*
string
buttons*
array[object]
type / text / ur
example*
object
header_text / body_text / footer_text
format
string
Allowed values: TEXT, IMAGE, DOCUMENT, VIDEO
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 WABA templates
GET https://hub.360dialog.io/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/waba_templates
Request example
curl --request GET
--url https://hub.360dialog.io/api/v2/partners/partner_id/waba_accounts/waba_account_id/waba_templates
--header 'Authorization: '
--header 'Content-Type: application/json'
See Template Statuses
Path Parameters
partner_id*
string
Your Partner Hub ID
Query Parameters
filters
string
A JSON object of params and their expected values
limit
string
Objects limit to return in the response
offset
string
Show the results starting from an offset
sort
string
Use minus - symbol for descending sorting
Remove a WABA template
DELETE https://hub.360dialog.io/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/waba_templates/{template_id}
Request example
curl --request DELETE
--url https://hub.360dialog.io/api/v2/partners/partner_id/waba_accounts/waba_account_id/waba_templates/template_id
--header 'Authorization: '
--header 'Content-Type: application/json'
Path Parameters
partner_id*
string
Your Partner Hub ID
template_id*
string
ID of the template (can be fetched with the get WABA templates request)
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.
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:
AUTHENTICATIONMARKETINGUTILITY
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.
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.
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.
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.
You can see the exact payload of every status when received via webhook here.
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.
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:
From the Account Quality page, click on Rejected Message Templates.
Choose from the list of rejected templates and click Request Review.
Enter Appeal Reason and click Submit.
After submission, the request and the issue are moved to the In Review tab.
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
Send Template Message
POST https://waba.360dialog.io/v1/messages
There is no limit to the number of parameters allowed in a Message Template.
Request Body
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
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
Example 2 - Sending Media Template Message with Parameters
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:
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
If the WABA is registered in Cloud API
See how to send Template Messages using Cloud API hosting in the specific Meta documentation.
Send Template Message
POST https://waba-v2.360dialog.io/messages
Request Body
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
messaging_product
string
Required only for Cloud API.
Messaging service used for the request. Use "whatsapp".
A successful response includes an object with an identifier prefixed with wamid. Use the ID listed after wamid to track your message status.
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
Example 2 - Sending Media Template Message with Parameters
Example 3 - Template message with opt-out button
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. You can also subscribe to webhook events of this approval.
In addition, you will receive a webhook notification if you are subscribed to a phone number's webhook events whenever a 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, usebus_ticket_details. Remember that someone from Meta 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.
Any tiny detail can prevent a template from being approved. If you are creating duplicates or similar templates but are confused if one of them is approved and the other isn't, double check the small details that might differentiate the two. For example, if you duplicate an approved template or create a new one with similar content, please make sure that the language is the same for both. A simpler variation such as en_GB instead of en can cause the template rejection. It's important to also watch out for small word changes and different emojis.
BSPs have no control over Meta's decisions. All reviews and approvals are conducted by Meta's Trust and Safety team, hence they may not provide detailed information on why a specific message template was rejected, while a similar one with the same content was approved. However, please be assured that Meta's team thoroughly reviews every request. If you do not agree with their decision, you have the option to appeal it.
Template Examples
Deal Promotion
Get in touch
Appointment Reminder
Last updated
Was this helpful?