Template Messages
Conversation-based pricing changed on June 1, 2023. From June 1, conversations are priced by the category of your message template (service, marketing, utility, or authentication).
Please see Meta's Official Pricing Change Documentation to see details about it.
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. In addition, templates may be disabled automatically based on customer feedback. Once disabled, a template cannot be sent in a template message until its quality rating has improved or it no longer violates Meta's business or commerce policies.
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 360dialog Hub
See our Template Message Management documentation.
In the API
You can use the WhatsApp Business Management API to create new message templates, media message templates, or interactive message templates.
Some important things to note:
Ensure that your templates meet Facebook's strict Message Template Guidelines.
We support create and delete for templates. Editing a template is not yet available.
The Create API call allows you to add a message template in a specific language.
The Delete API call allows you to delete all translations of a message template you specify by name.
When you create a message template, make sure to be consistent when providing translations.
If you don't do that, you might see a
structure unavailableerror and notifications won't be delivered.See the Why am I seeing 'structure unavailable' errors in my callback or my oncall pager group? FAQ for more information about this.
Every template has to be approved by Facebook.
You can use your template, as soon as its status changes to
approvedThis can take up to 48h. If your template is still in status
submittedafter two days, please contact Help and Support.You can include
allow_category_change=truein 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.
To create a message template, you have to use the request below:
Create a template
POST [base-url]/v1/configs/templates
Headers
D360-API-KEY
string
object {WABA Template}
name string optional
namespace string optional
category string optional
components array[object] optional
type string Allowed Values: BODY, HEADER, FOOTER, BUTTONS
format string Allowed Values: TEXT, IMAGE, DOCUMENT, VIDEO
text string optional
example string optional
buttons object optional
type string Allowed Values: PHONE_NUMBER, URL, QUICK_REPLY
text string required
url string optional
phone_number string optional
example string optional
language string optional
rejected_reason string optional
status string optional
The handle for examples has to be a valid URL to your media file.
More information about parameters, components, and buttons you can find here: Templates - WhatsApp Business API. More information about all supported languages you can find here: Supported Languages - WhatsApp Business API.
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.
Example: Create template (with HEADER-IMAGE + BODY + BUTTONS-URL + PHONE + FOOTER) Request URL: /v1/configs/templates
{
"name": "template_name_example",
"category": "UTILITY",
"components": [
{
"type": "BODY",
"text": "What do you want to do now?"
},
{
"type": "HEADER",
"format": "IMAGE",
"example": {
"header_handle": [
"https://url-to-media-file/media.file"
]
}
},
{
"type": "FOOTER",
"text": "your-footer-text"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "PHONE_NUMBER",
"text": "your-phone-button-text",
"phone_number": "+1(650) 555-1111"
},
{
"type": "URL",
"text": "your-url-button-text",
"url": "https://www.website.com/{{1}}",
"example": [
"https://www.website.com/dynamic-url-example"
]
}
]
}
],
"language": "en_US",
"allow_category_change": true
}You can use the WhatsApp Business Management API to get a list of your existing message templates.
Get template list
GET [base-url]/v1/configs/templates
Path Parameters
limit
integer
default: 1000
offset
integer
default: 0
sort
string
Allowed Values: id, name, status
Headers
D360-API-KEY
string
object
count integer optional
filters object optional
limit integer optional
offset integer optional
sort array[string] optional
total integer optional
waba_templates array[object] {WABA Template} optional
name string optional
namespace string optional
category string optional
components array[object] optional
type string ALLOWED VALUES: BODY, VALUE, FOOTER, BUTTONS required
format string ALLOWED VALUES: TEXT, IMAGE, DOCUMENT, VIDEO optional
text string optional
example string optional
buttons object optional
type string ALLOWED VALUES: PHONE_NUMBER, URL, QUICK_REPLY required
text string required
url string optional
phone_number string optional
example string optional
language string optional
rejected_reason string optional
status string optionalExample:
Response code:
{
"count": 3,
"filters": {
},
"limit": 1000,
"offset": 0,
"sort": [
"id"
],
"total": 3,
"waba_templates": [
{
"category": "UTILITY",
"components": [
{
"format": "TEXT",
"text": "Facebook Template Message",
"type": "HEADER"
},
{
"text": "Thank you for your request. \nAs Facebook closes the conversation after 24hours we cannot reach out to you anymore besides this template. \nIf you like to get in contact with us again and revoke the conversation please just click on one of the buttons and we get back to you.",
"type": "BODY"
},
{
"text": "Many thanks, your 360dialog team",
"type": "FOOTER"
},
{
"buttons": [
{
"text": "RESOLVED",
"type": "QUICK_REPLY"
},
{
"text": "NO",
"type": "QUICK_REPLY"
},
{
"text": "YES",
"type": "QUICK_REPLY"
}
],
"type": "BUTTONS"
}
],
"language": "en",
"name": "test_1",
"namespace": "xxxxxxxx_xxxx_xxxx_xxxx_xxxxxxxxxxxx",
"rejected_reason": "NONE",
"status": "APPROVED"
},
{
"category": "UTILITY",
"components": [
{
"text": "Thank you for reaching out to us. We are looking into your request and get back to you.",
"type": "BODY"
},
{
"text": "Feel free to get in contact",
"type": "FOOTER"
},
{
"buttons": [
{
"phone_number": "+49xxxxxxxxx",
"text": "Call number",
"type": "PHONE_NUMBER"
},
{
"text": "360dialog Website",
"type": "URL",
"url": "https://www.360dialog.com/de/whatsapp-business/"
}
],
"type": "BUTTONS"
}
],
"language": "en",
"name": "test_2",
"namespace": "xxxxxxxx_xxxx_xxxx_xxxx_xxxxxxxxxxxx",
"rejected_reason": "NONE",
"status": "APPROVED"
},
{
"category": "MARKETING",
"components": [
{
"text": "Hello {{1}}! This is a test message, setup with API version {{2}}",
"type": "BODY"
},
{
"buttons": [
{
"text": "Follow the link!",
"type": "URL",
"url": "https://www.360dialog.com/{{1}}"
}
],
"type": "BUTTONS"
},
{
"text": "This is the footer",
"type": "FOOTER"
}
],
"language": "en",
"name": "test_3",
"namespace": "xxxxxxxx_xxxx_xxxx_xxxx_xxxxxxxxxxxx",
"rejected_reason": "NONE",
"status": "APPROVED"
}
]
}You can use the WhatsApp Business Management API to delete your message templates by providing the message template name. Some things to keep in mind before deleting a message template:
If that message template name exists in multiple languages, all languages will be deleted.
Messages that have been sent but not delivered (e.g., if the customer's device is offline) will attempt to be delivered for 30 days.
If a message from an approved message template is sent 30 days after deletion, you will receive a "Structure Unavailable" error and the customer will not receive the message.
Once deleted, the name of an approved template cannot be used again for 30 days. Use a different name to create future templates.
Delete a template
DELETE [base-url]/v1/configs/templates/{template_name}
Path Parameters
template_name
string
Headers
D360-API-KEY
string
{
"meta": {
"developer_message": "template name=`<template_name>` was deleted",
"http_code": 200,
"success": true
}
}Template Categories
A template message can have three different categories:
UTILITYMARKETINGAUTHENTICATION
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.
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"
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.
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."
Authentication templates
Authentication templates enable businesses to authenticate users with one-time passcodes (usually 4-8 digit alphanumeric codes), potentially at multiple steps in the login process (e.g., account verification, account recovery, integrity challenges).
For a template to be classified as authentication, a business must:
Use WhatsApp’s preset authentication message templates, which include optional add-ons like security disclaimers and expiry warnings.
Configure a one-time password button (copy-code or one-tap)
Follow content restrictions: URLs, media, and emojis are not allowed for authentication template content or parameters. Additional length restrictions of 15 characters also apply to parameters.
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."
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.
Appeal
You 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. See our documentation for WABA Policy Enforcement.
Sending a Template Message
If the WABA is registered in On-premise API
Send a Template Message
POST https://waba.360dialog.io/v1/messages
There is no limit to the number of parameters allowed in a Message Template.
See Meta's Official Documentation to assemble your request's parameters.
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"
}
]
}
]
}
}If the WABA is registered in Cloud API
Send Template Messages
POST https://waba-v2.360dialog.io/messages
See Meta's Official Documentation to assemble your request's parameters.
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"}]
}]
}
}
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"}]
}]
}Best practices to get your Template Message approved
Here are some tips to get your templates through the review process:
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.
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. Examples
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.
Official Meta Developer Documentation
Cost of WhatsApp Conversations
Last updated
Was this helpful?