A message template is required for any business-initiated messages sent using the WhatsApp Business Platform. These templates can be created using the Business Management API or the WhatsApp Business Manager.
The number of templates a WhatsApp Business Account can have is determined by its parent business. If a parent business is unverified, each of its WhatsApp Business Accounts is limited to 250 templates. However, if the parent business is verified and at least one of its WhatsApp Business Accounts has a business phone number with an approved display name, each of its WhatsApp Business Accounts can have up to 6,000 templates.
This document explains how to create, retrieve, edit, and delete message templates.
You will need:
You can add a message template in a specific language when creating a template. These templates count against your limit. Be consistent when providing translations. See the Why am I seeing 'structure unavailable' errors in my callback? help center article for more information.
You can create text message templates, media message templates, or interactive message templates.
To help us during the review and approval process, you can include example data. This can help us understand what kind of message you plan to send and showcase the customer experience. For example, you could include an image that could represent a customer's profile picture to personalize the experience. Make sure these are examples and do not include any confidential or personal information.
To create a text message template, send a POST
request to the /{whatsapp-business-account-ID}/message_templates
endpoint and include the name
, category
, language
, components
with type
set to BODY
and text
set to the content for message, name
, and language
fields.
Valid values for category
are: TRANSACTIONAL
, MARKETING
, OTP
.
Add another type
array in components
for the media you are including in the template. The array will include a type
set to HEADER
, format
set to the media type, and can include optional information for text and examples.
The following example creates a template with an image that customers can use to ask help to resolve an issue.
Formatted for readability.
curl -X POST "https://graph.facebook.com/v15.0
/{whatsapp-business-account-ID}/message_templates
?name={template-name}
&language=en_US
&category=TRANSACTIONAL,
&components=[{
type:BODY,
text:{message-text}
},
{
type:HEADER,
format:IMAGE,
example:{header_handle:[{uploaded-image-file-url}]}
}],
&access_token={system-user-access-token}"
The following example creates a template with a button that customers can use to call a business' phone number for help resolving an issue.
Formatted for readability.
curl -X POST "https://graph.facebook.com/v15.0
/{whatsapp-business-account-ID}/message_templates
?name={template-name}
&language=en_US
&category=TRANSACTIONAL,
&components: [{
type:BODY,
text:body-text {{1}} {{2}} {{3}},
example:{body_text:[[body-example-1,body-example-2,body-example-3]]}
},
{
type:HEADER,
format:TEXT,
text:{header-text} {{1}},
example:{ header_text:[{header-text}] }
},
{
type:FOOTER,
text:{footer-text}
},
{
type:BUTTONS,
buttons:[{type:PHONE_NUMBER,text:{phone-button-text},phone_number:+1(650) 555-1111}],
},
{
type:URL,
text:{url-button-text},
url:https://www.website.com/{{1}},
example:[https://www.website.com/dynamic-url-example]
}]
&access_token={system-user-access-token}"
On success, a JSON object containing the message template ID is returned:
{ "id": "{message-template-id}" }
For a complete list of parameters, visit the
WhatsAppBusinessAccount/message_templates Reference
.
We recommend that you add an opt-out button to your marketing templates. This will give users an option to opt out of your marketing messages without having to block your business. As a result, you may be able to scale messaging volume faster on WhatsApp. Please refer to this article for further details on the benefits of the marketing opt-out button and guidance on when to add it.
The following POST
request demonstrates how to incorporate this button into your message templates.
curl -X POST "https://graph.facebook.com/v14.0/{whatsapp-business-account-ID}/message_templates { "name": "promotional_message", "language": "en_US", "category": "TRANSACTIONAL", "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"}] }] }
On success, a JSON object with the message template id is returned:
{ "id": "{message-template-id}" }
Your business must take the necessary steps to stop sending marketing messages to customers who have chosen to opt-out of receiving them. Not doing so will negatively impact your block rate and quality score.
When a message template is returned, the response will include all its translations (if any). Message templates are grouped by the name
field. You can use the limit
parameter to define the number of items returned. This limit applies to the maximum number of message template names that may be returned, not the maximum number of objects.
To get a list of a business' message templates, send a GET
request to the /{whatsapp-business-account-ID}/message_templates
endpoint. In this example request we are limiting the number of templates returned to 3.
curl -i -X GET "https://graph.facebook.com/v15.0
/{whatsapp-business-account-ID}/message_templates
?limit=3
&access_token={system-user-access-token}"
On success, a JSON object is returned:
{ "data": [ { "name": "hello_world", "components": [{ "type": "BODY", "text": "Hello, {{1}}" }], "language": "en_US", "status": "APPROVED", "category": "TRANSACTIONAL", "id": "409119052980796" }, { "name": "case_opened", "components": [{ "type": "BODY", "text": "Seu caso {{1}} foi aberto. Entraremos em contato em breve." }], "language": "pt_BR", "status": "APPROVED", "category": "TRANSACTIONAL", "id": "718173718589371" }, { "name": "case_opened", "components": [{ "type": "BODY", "text": "Your case {{1}} was opened. We will get in touch soon." }], "language": "en_US", "status": "APPROVED", "category": "TRANSACTIONAL", "id": "755551981307120" } ], "paging": { "cursors": { "before": "MAZDZD", "after": "MjQZD" } }
The message template namespace is required to send messages using the message templates.
To get the namespace for a template, send a GET
request to the /{whatsapp-business-account-ID}
endpoint and include the message_template_namespace
field.
curl -i -X GET "https://graph.facebook.com/v15.0
/{whatsapp-business-account-ID}
?fields=message_template_namespace
&access_token={system-user-access-token}"
On success, a JSON object with the WhatsApp Business Account ID and namespace is returned:
{ "id": "1972385232742141", "message_template_namespace": "12abcdefghijk_34lmnop" }
You can edit a message template by sending a POST
request to the /{message_template-id}
endpoint. Editing a template replaces its old contents entirely, so include any components you wish to preserve as well as components you wish to update using the components
parameter.
Notes:
curl -X POST "https://graph.facebook.com/v15.0
/{message-template-id}
&components=[{
type:BODY,
text:{original-or-edited-message-text}
},
{
type:HEADER,
format:IMAGE,
example:{header_handle:[{original-or-new-uploaded-image-file-url}]}
}],
&access_token={system-user-access-token}"
On success, a JSON object is returned:
{ "success": true }
You can delete a message template by providing the message template name. Some things to keep in mind before deleting a message template:
To delete a template, send a DELETE
request to the /{whatsapp-business-account-ID}/message_templates
endpoint and include the name
parameter set to the template name to be deleted.
curl -X DELETE "https://graph.facebook.com/v15.0
/{whatsapp-business-account-ID}/message_templates
?name=hello_world_template
&access_token={system-access-token}"
On success, a JSON object is returned:
{ "success": true }