For any notifications sent using the WhatsApp Business API, a message template is required. Those templates can be created either in the Business Manager's user interface (https://business.facebook.com/wa/manage/message-templates/?business_id=
your-business-id
) or through the WhatsApp Business Management API.
Some important things to note:
structure unavailable
error and notifications won't be delivered.Use the WhatsApp Business Management API to create new message templates, media message templates, or interactive message templates.
You cannot currently edit message templates. Please use a test account when learning to use the WhatsApp Business Management API.
curl -X POST \
'https://graph.facebook.com/v10.0
/your-whatsapp-business-account-id/message_templates' \
-d 'category=ISSUE_RESOLUTION' \
-d 'components=[{"type":"BODY", "text":"your-message-text"}]' \
-d 'name=hello_world_template' \
-d 'access_token=your-access-token' \
-d 'language=en_US'
curl -X POST \
'https://graph.facebook.com/v10.0
/your-whatsapp-business-account-id/message_templates' \
-d 'category=ISSUE_RESOLUTION' \
-d 'components=[{"type":"BODY", "text":"your-message-text"}, {"type":"HEADER", "format":"IMAGE", "example": {"header_handle":["your-file-handle"]}}]' \
-d 'name=hello_world_template' \
-d 'access_token=your-access-token' \
-d 'language=en_US'
File handles can be generated using the Resumable Upload API.
curl -X POST \
'https://graph.facebook.com/v10.0
/your-whatsapp-business-account-id/message_templates' \
-d 'category=ISSUE_RESOLUTION' \
-d 'components: [{"type":"BODY","text":"your-body-text {{1}} {{2}} {{3}}","example":{"body_text":[["your-body-example-1","your-body-example-2","your-body-example-3"]]}},{"type":"HEADER","format":"TEXT","text":"your-header-text {{1}}","example":{"header_text":["your-header-example"]}},{"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"]}]}]' \
-d 'name=hello_world_template' \
-d 'access_token=your-access-token' \
-d 'language=en_US'
Name | Description |
---|---|
| Required. The type of message template. Values: |
| Required. The parts of the message template. |
| Required. The name of the message template. |
| Required. The access token for interacting with the API. |
| Required. The language of the message template |
components
ParameterName | Description |
---|---|
| Required. Values: The character limit of the |
| Optional. Only applies to the |
| Optional. Text of the message being sent. |
| Optional. Provides an example of possible data for your template. This helps us during the review and approval process, so we can understand what kind of message you plan to send. Make sure these are examples and do not include any confidential or personal information. |
| Optional. Only applies to the The parameters related to the button. |
BUTTONS
Component TypeName | Description |
---|---|
| Required. Values: |
| Required. The text to be displayed on the button |
| Optional. The URL that will be visited on clicking the button |
| Optional. The phone number that will be called on clicking the button |
| Optional. Provides an example of possible data for your template |
{ "id": "952305634918767" }
You can then use the returned id
in a GET
call to obtain information about this message template.
The following are the supported languages for message templates.
Language | Code |
---|---|
Afrikaans | af |
Albanian | sq |
Arabic | ar |
Azerbaijani | az |
Bengali | bn |
Bulgarian | bg |
Catalan | ca |
Chinese (CHN) | zh_CN |
Chinese (HKG) | zh_HK |
Chinese (TAI) | zh_TW |
Croatian | hr |
Czech | cs |
Danish | da |
Dutch | nl |
English | en |
English (UK) | en_GB |
English (US) | en_US |
Estonian | et |
Filipino | fil |
Finnish | fi |
French | fr |
German | de |
Greek | el |
Gujarati | gu |
Hausa | ha |
Hebrew | he |
Hindi | hi |
Hungarian | hu |
Indonesian | id |
Irish | ga |
Italian | it |
Japanese | ja |
Kannada | kn |
Kazakh | kk |
Korean | ko |
Lao | lo |
Latvian | lv |
Lithuanian | lt |
Macedonian | mk |
Malay | ms |
Malayalam | ml |
Marathi | mr |
Norwegian | nb |
Persian | fa |
Polish | pl |
Portuguese (BR) | pt_BR |
Portuguese (POR) | pt_PT |
Punjabi | pa |
Romanian | ro |
Russian | ru |
Serbian | sr |
Slovak | sk |
Slovenian | sl |
Spanish | es |
Spanish (ARG) | es_AR |
Spanish (SPA) | es_ES |
Spanish (MEX) | es_MX |
Swahili | sw |
Swedish | sv |
Tamil | ta |
Telugu | te |
Thai | th |
Turkish | tr |
Ukrainian | uk |
Urdu | ur |
Uzbek | uz |
Vietnamese | vi |
Zulu | zu |
You can use the WhatsApp Business Management API to get a list of your existing message templates. The limit
parameter is optional.
curl -i -X GET \
'https://graph.facebook.com/v10.0
/your-whatasapp-business-account-id/message_templates?limit=3&access_token=your-access-token'
{ "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" } }
Looping through all the message templates from a WhatsApp Business Account may require more than one API call. The mechanism for this pagination is described in the Graph API documentation and uses the paging
field in the response. For message templates, there are a few differences:
name
field. limit
parameter defines the maximum number of objects returned in a single API call. For message templates, the difference is this limit applies to the maximum number of message template names that may be returned, not the maximum number of objects. If a message template has translations, the number of objects will be larger, as every translation is included in the API response. The message template namespace is required to send messages using the message templates in the WhatsApp business account.
curl -i -X GET "https://graph.facebook.com/v10.0
/your-whatsapp-business-account-id?fields=message_template_namespace&access_token=your-system-user-access-token"
{ "id": "1972385232742141", "message_template_namespace": "12abcdefghijk_34lmnop" }
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:
curl -X DELETE \
'https://graph.facebook.com/v10.0
/your-whatsapp-business-account-id/message_templates' \
-d 'name=hello_world_template' \
-d 'access_token=your-access-token'
{ "success": true }
For a list of all possible values for each field, refer to the Graph API reference of the message_templates
endpoint.
Yes, when sending a message template, if it failed to display on the receiving end, you will receive a "failed" status callback with "structure unavailable" in the error object indicating that the message could not be displayed. Depending on the recipient, you may also receive a "delivered" status callback which simply indicates that the message was delivered to the recipient after which the recipient failed to display the message.
Yes, message templates support all WhatsApp messaging characters and formatting including emojis, bolding, italics, etc. For emojis, you will need to use the emoji character (copy/paste) rather than its unicode equivalent.
There is no limit to the number of parameters allowed in a message template.
Using media in message templates is not currently supported, but is in development.
The maximum is 250 message templates per WhatsApp business account.
Reasons a message template might be rejected include:
Note: that the fallback
language policy is deprecated beginning with v2.27.8
and the deterministic
language policy is now the default policy.
If you create a translation in a new language you need to translate all the elements you use into that language. Otherwise, you might get "structure unavailable" errors since recipient's phone can't find an element it expects for the language it's in. These structure unavailable errors are seen when sending template messages using fallback policy.
If creating language translations is not an option for you at this moment, You can use deterministic policy to avoid these errors.
It is currently 7 days. If a cache has not been updated for longer than 7 days, it will pull the latest language pack from the server regardless of whether the element already exists in the pack or not.
A link will only be rendered as clickable if the recipient has already saved your business number as contact or you have an Official Business Account.
The device will first load from cache, and if an element exists, it will unpack the message using that message template. So instead of modifying message templates, it's safest to simply add a new one with a different element name. That will guarantee that the language pack gets re-downloaded when it can't find that element. Storage costs of message templates are negligible so there's no absolute need to delete message templates.
See Sending Message Templates — Language for more information.