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.
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. There are multiple ways to submit a Template Message for approval and manage your approved templates.
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
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
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.
You will receive a Hub Notification (as well as the client) when a template changes status.
A template message can have three different categories:
AUTHENTICATIONMARKETINGUTILITY
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 |
|
Change or update a transaction |
|
Account, billing, or payment notification |
|
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 |
|
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 |
|
Welcoming or closing messages |
|
Updates, invitations, newsletters, or recommendations |
|
Requests to respond or complete a new transaction |
|
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.
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.
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.
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.{
"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
}
}
}
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.From the Account Quality page, click on Rejected Message Templates.
- 2.Choose from the list of rejected templates and click Request Review.
- 3.Enter Appeal Reason and click Submit.
- 4.After submission, the request and the issue are moved to the In Review tab.
- 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.
If your template is rejected due to miscategorization, you have the following options:
- 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.
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"
}
]
}
]
}
}
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.
{
"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"}]
}]
}
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"}]
}]
}
}
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.
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. Deal Promotion
Get in touch
Appointment Reminder
