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.You can 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/v3.3/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/v3.3/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'
Note: File handles can be generated using the Resumable Upload API.
curl -X POST \ 'https://graph.facebook.com/v3.3/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 | Required | Description |
---|---|---|
| Yes | The type of message template .
Values: |
| Yes | The parts of the message template |
| Yes | The name of the message template |
| Yes | The access token for interacting with the API |
| Yes | The language of the message template |
components
parameterName | Required | Description |
---|---|---|
| Yes | Values: |
| Optional | Only applies to the |
| Optional | Text of the message being sent |
| Optional | Provides an example of possible data for your template |
| Optional | Only applies to the |
BUTTONS
component typeName | Required | Description |
---|---|---|
| Yes | Values: |
| Yes | 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. Please note that the limit
parameter is optional.
curl -i -X GET \ 'https://graph.facebook.com/v3.3/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/v8.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/v3.3/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.