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).
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. There are multiple ways to submit a Template Message for approval and manage your approved templates.
See our Template Message Management documentation.
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:
- 1.We support create and delete for templates. Editing a template is not yet available.
- 2.The Create API call allows you to add a message template in a specific language.
- 3.The Delete API call allows you to delete all translations of a message template you specify by name.
- 4.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 unavailable
error 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.
- 5.Every template has to be approved by Facebook.
- You can use your template, as soon as its status changes to
approved
- This can take up to 48h. If your template is still in status
submitted
after two days, please contact Help and Support. - You can 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.
To create a message template, you have to use the request below:
post
[base-url]
/v1/configs/templates
Create a template
Currently, you cannot edit message templates. Please use a test account when learning to use the WhatsApp Business Management API.
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.
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
[base-url]
/v1/configs/templates
Get template list
200
{
"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
[base-url]
/v1/configs/templates/{template_name}
Delete a template
More information on what is possible with templates can be found in the Facebook Template Message guide and the Facebook Template reference guide.
A template message can have three different categories:
UTILITY
MARKETING
AUTHENTICATION
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 |
|
Manage Opt-In on WhatApp
Effective on October 30, 2023 |
|
Feedback Surveys
Effective on October 30, 2023 |
|
Continue a conversation on WhatsApp Channel
Effective on October 30, 2023 |
|
Starting October 30, 2023, Meta will update its Template Guidelines by introducing three new Utility Template varieties:
- User-Requested Opt-In Management
- Feedback surveys related to previous transactions
- Continuing Cross-Channel Conversations
No development work is required. These changes will affect the approval processes for new templates, and existing marketing templates will be reclassified according to the new guidelines on October 30, 2023.
Businesses will receive notifications about category updates for approved marketing templates via email, Business Manager Banner Alert, and the
template_category_update
webhook will be transmitted. Businesses can also query the GET /templates endpoint for further details.
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 |
|
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.
See our Authentication Templates with One-Time-Password documentation for the specific requirements.
Definition | Examples |
---|---|
Provide an authentication code to the user |
|
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.
Template pacing has been valid for businesses in Brazil, Colombia, and Singapore since September 12, 2023. Applies to all businesses starting October 12, 2023.
It’s important to note that template pacing applies exclusively to marketing message templates. For campaigns with fewer recipients that do not reach their 'pace limit', their messages will not be subjected to pacing.
This 'pace limit' number is dynamically determined by Meta and may vary depending on the template or business.
Template pacing is a mechanism that allows time for customers to provide early feedback on newly created or unpaused marketing templates. This identifies and pauses marketing templates that have received poor feedback, giving the business time to adjust their contents before they are sent to too many customers, thereby reducing the likelihood of negative feedback impacting the business.
Newly created marketing templates, and paused marketing templates that become unpaused, are subject to pacing. When one of these templates is used in a messaging campaign, messages will be sent normally until an unspecified threshold is reached. Once this threshold is reached, subsequent messages using that template will be held to allow enough time for customer feedback.
If the feedback is positive and changes the template's quality rating to high quality, the held messages will be released and sent normally, along with any appropriate
message_template_quality_update
webhook event and message webhooks.If the feedback is negative and changes the template's quality to low quality:
- The template's
status
will be set toPAUSED
- A
message_template_status_update
will be sent with anevent
value ofpaused
- Each held message will be dropped and trigger a
messages
webhook with"status":"failed"
and"code":"132015"
(Cloud API) or"code":"2061"
( On-Premises API) - Admins of the WhatsApp Business Account owning business will be informed of the dropped messages by Meta Business Suite notification, WhatsApp Manager banner, and email.
If 30 minutes have elapsed since Meta started holding messages, but the template has not received enough feedback to change its quality to high or low, the held messages will be released normally along with any appropriate
messages
webhooks.
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.
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.
Buttons are optional interactive components that perform specific actions when tapped. Templates can have a mixture of up to 10 button components total, although there are limits to individual buttons of the same type as well as combination limits.
These limits are described below:
Examples of valid groupings | Examples of invalid groupings: |
---|---|
|
|
Buttons are defined within a single buttons component object, packed into a single
buttons
array. For example, this template uses a phone number button and a URL button:{
"type": "BUTTONS",
"buttons": [
{
"type": "PHONE_NUMBER",
"text": "Call",
"phone_number": "15550051310"
},
{
"type": "URL",
"text": "Shop Now",
"url": "https://www.luckyshrub.com/shop/"
}
]
}
If a template has more than three buttons, two buttons will appear in the delivered message and the remaining buttons will be replaced with a See all options button. Tapping the See all options button reveals the remaining buttons.

Phone number buttons call the specified business phone number when tapped by the app user. Templates are limited to one phone number button.
Syntax
{
"type": "PHONE_NUMBER",
"text": "<TEXT>",
"phone_number": "<PHONE_NUMBER>"
}
Properties
Placeholder | Description | Example Value |
---|---|---|
<PHONE_NUMBER> | Alphanumeric string. Business phone number to be (display phone number) called when the user taps the button. 20 characters maximum. | 15550051310 |
<TEXT> | Button label text. 25 characters maximum. | Call |
Example
{
"type": "PHONE_NUMBER",
"text": "Call",
"phone_number": "15550051310"
}
URL buttons load the specified URL in the device's default web browser when tapped by the app user. Templates are limited to two URL buttons.
Syntax
{
"type": "URL",
"text": "<TEXT>",
"url": "<URL>",
# Required if <URL> contains a variable
"example": [
"<EXAMPLE>"
]
}
Properties
Placeholder | Description | Example Value |
---|---|---|
<EXAMPLE> | URL of website. Supports 1 variable. If using a variable, add sample variable property to the end of the URL string. The URL loads in the device's default mobile web browser when the customer taps the button. 2000 characters maximum. | https://www.luckyshrub.com/shop?promo=summer2023 |
<TEXT> | Button label text. Supports 1 variable. If using a variable, must include the example property and a sample value. 25 characters maximum. | Shop Now |
<URL> | URL of website that loads in the device's default mobile web browser when the button is tapped by the app user. Supports 1 variable, appended to the end of the URL string. 2000 characters maximum. | https://www.luckyshrub.com/shop?promo={{1}} |
Example
{
"type": "URL",
"text": "Shop Now",
"url": "https://www.luckyshrub.com/shop?promo={{1}}",
"example": [
"summer2023"
]
}
An example request to create a marketing template with the following components:
- an image header with a sample value
- a text body with variables and sample values
- a text footer
- a phone number button
- a URL button
{
"name": "limited_time_offer_tuscan_getaway_2023",
"language": "en_US",
"category": "MARKETING",
"components": [
{
"type": "HEADER",
"format": "IMAGE",
"example": {
"header_handle": [
"4::aW..."
]
}
},
{
"type": "BODY",
"text": "Hi {{1}}! For a limited time only you can get our {{2}} for as low as {{3}}. Tap the Offer Details button for more information.",
"example": {
"body_text": [
[
"Pablo","Tuscan Getaway package","800"
]
]
}
},
{
"type": "FOOTER",
"text": "Offer valid until May 31, 2023"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "PHONE_NUMBER",
"text": "Call",
"phone_number": "15550051310"
},
{
"type": "URL",
"text": "Shop Now",
"url": "https://www.luckyshrub.com/shop?promo={{1}}",
"example": [
"summer2023"
]
}
]
}
]
}
Quick reply buttons are custom text-only buttons that immediately message you with the specified text string when tapped by the app user. A common use case-case is a button that allows your customer to easily opt-out of any marketing messages.
Templates are limited to 10 quick reply buttons. If using quick reply buttons with other buttons, buttons must be organized into two groups: quick reply buttons and non-quick reply buttons. If grouped incorrectly, the API will return an error indicating an invalid combination.
Examples of valid groupings:
- Quick Reply, Quick Reply
- Quick Reply, Quick Reply, URL, Phone
- URL, Phone, Quick Reply, Quick Reply
Examples of invalid groupings:
- Quick Reply, URL, Quick Reply
- URL, Quick Reply, URL
When using the Cloud API or On-Premises API to send a template that has multiple quick reply buttons, you can use the index property to designate the order in which buttons appear in the template message.
Syntax
{
"type": "QUICK_REPLY",
"text": "<TEXT>"
}
Properties
Placeholder | Description | Example Value |
---|---|---|
<TEXT> | Button label text. 25 characters maximum. | Unsubscribe |
Example
{
"type": "QUICK_REPLY",
"text": "Unsubscribe from Promos"
}
An example request to create a marketing template with the following components:
- a text header with a variable and sample value
- a text body with variables and sample values
- a text footer
- two quick-reply buttons
{
"name": "seasonal_promotion",
"language": "en_US",
"category": "MARKETING",
"components": [
{
"type": "HEADER",
"format": "TEXT",
"text": "Our {{1}} is on!",
"example": {
"header_text": [
"Summer Sale"
]
}
},
{
"type": "BODY",
"text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
"example": {
"body_text": [
[
"the end of August","25OFF","25%"
]
]
}
},
{
"type": "FOOTER",
"text": "Use the buttons below to manage your marketing subscriptions"
},
{
"type":"BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Unsubscribe from Promos"
},
{
"type":"QUICK_REPLY",
"text": "Unsubscribe from All"
}
]
}
]
}
Copy code buttons copy a text string (defined when the template is sent in a template message) to the device's clipboard when tapped by the app user. Templates are limited to one copy code button.
Syntax
{
"type": "COPY_CODE",
"example": "<EXAMPLE>"
}
Properties
Placeholder | Description | Example Value |
---|---|---|
<EXAMPLE> | String to be copied to device's clipboard when tapped by the app user. Maximum 15 characters. | 250FF |
Example
{
"type": "COPY_CODE",
"example": "250FF"
}
One-time password (OTP) buttons are a special type of URL button used with authentication templates. See Authentication Templates.
When sending messages with media such as images, videos, or audio files, it is important to ensure that they are not heavy, as processing heavy media files at once can cause delays in transmission and lead to issues with message delivery.
For this, we suggest uploading media beforehand using the
/media
endpoint and then utilizing the media_id
obtained from the response when sending messages. By following this approach, you can ensure that the media file is processed accurately without causing any delays or latencies during send-outs.
post
https://waba.360dialog.io
/v1/messages
Send a 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"
}
]
}
]
}
}
post
https://waba-v2.360dialog.io
/messages
Send Template Messages
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
}
},