For any notifications sent using the WhatsApp Business Platform, a message template is required. These templates can be created either in the Business Management API or through the WhatsApp Business Manager's.
This document explains how to create, retrieve, and delete message templates.
You will need:
whatsapp_business_management
permissionYou can create text message templates, media message templates, or interactive message templates.
To help us during the review and approval proces, 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.
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/v13.0
/{whatsapp-business-account-ID}/message_templates
?name={template-name}
&language=en_US
&category=ISSUE_RESOLUTION,
&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/v13.0
/{whatsapp-business-account-ID}/message_templates
?name={template-name}
&language=en_US
&category=ISSUE_RESOLUTION,
&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}" }
Name | Description | ||||
---|---|---|---|---|---|
| Required. A system user access token for interacting with the API. | ||||
| Required. The type of message template. Supported Values include:
| ||||
| Required. The parts of the message template | ||||
| Optional. Only applies to the The parameters related to the button. | ||||
| Optional. Provides a button example of possible data for your template | ||||
| Optional. The phone number that will be called on clicking the button | ||||
| Required. The text to be displayed on the button | ||||
| Required. Type of button. Supported values include:
| ||||
| Optional. The URL that will be visited on clicking the button. Variables can be used to create dynamic links. If you decide to provide variables and examples, please provide the same number of variables and examples | ||||
| Optional. Provides a component example of possible data for your template. | ||||
| Optional. Only applies to the
| ||||
| Optional. Text of the message being sent. | ||||
| Required. The character limit of the
|
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/v13.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": "ISSUE_RESOLUTION", "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": "TICKET_UPDATE", "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": "TICKET_UPDATE", "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/v13.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 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/v13.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 }