Create, Retrieve, and Delete Message Templates

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.

WhatsApp Business Account message templates

Some important things to note:

  1. We support create and delete. 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.

Create Message Templates

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.

Message Template Request

curl -X POST \ 
'https://graph.facebook.com/v12.0/{whatsapp-business-account-ID}/message_templates' \
  -d 'category=ISSUE_RESOLUTION' \
  -d 'components=[{
       "type":"BODY", "text":"message-text"
     }]' \
  -d 'name=hello_world_template' \
  -d 'access_token=access-token' \
  -d 'language=en_US'
To find the ID of a WhatsApp Business Account (WABA), go to Business Manager > Business Settings > Accounts > WhatsApp Business Accounts. Find the WABA you want to use and click on it. A panel will open up with information about the account, including the ID.

Media Message Template Request

curl -X POST \ 
'https://graph.facebook.com/v12.0/{whatsapp-business-account-ID}/message_templates' \
  -d 'category=ISSUE_RESOLUTION' \
  -d 'components=[{
       "type":"BODY", "text":"message-text"
     }, 
     {
       "type":"HEADER", "format":"IMAGE", "example":{
         "header_handle":["file-handle"]
       }
     }]' \
  -d 'name=hello_world_template' \
  -d 'access_token=access-token' \
  -d 'language=en_US'

File handles can be generated using the Resumable Upload API.

Interactive Message Template Request

curl -X POST \ 
'https://graph.facebook.com/v12.0/{whatsapp-business-account-ID}/message_templates' \
  -d 'category=ISSUE_RESOLUTION' \
  -d '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-example"]
       }
     },
     {
       "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"]
     }]' \
  -d 'name=hello_world_template' \
  -d 'access_token=access-token' \
  -d 'language=en_US'

Parameters

NameDescription

category

Required.

The type of message template.

Values: ACCOUNT_UPDATE, PAYMENT_UPDATE, PERSONAL_FINANCE_UPDATE, SHIPPING_UPDATE, RESERVATION_UPDATE, ISSUE_RESOLUTION, APPOINTMENT_UPDATE, TRANSPORTATION_UPDATE, TICKET_UPDATE, ALERT_UPDATE, AUTO_REPLY

components

Required.

The parts of the message template.

name

Required.

The name of the message template.

access_token

Required.

The access token for interacting with the API.

language

Required.

The language of the message template

The components Parameter
NameDescription

type

Required.

Values: BODY, HEADER, FOOTER. and BUTTONS


The character limit of the BODY component is 1024 characters, while the character limits of the HEADER and FOOTER components is 60 characters each.

format

Optional.

Only applies to the HEADER type.
Values: TEXT, IMAGE, DOCUMENT, VIDEO

text

Optional.

Text of the message being sent.

example

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.


If you decide to provide variables and examples, please provide the same number of variables and examples.

buttons

Optional. Only applies to the BUTTONS type.

The parameters related to the button.

The BUTTONS Component Type
NameDescription

type

Required.

Values: PHONE_NUMBER, URL, and QUICK_REPLY

text

Required.

The text to be displayed on the button

url

Optional.

The URL that will be visited on clicking the button
Variables can be used to create dynamic links

phone_number

Optional.

The phone number that will be called on clicking the button

example

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.

Response

{
  "id": "952305634918767"
}

You can then use the returned id in a GET call to obtain information about this message template.

Supported Languages

The following are the supported languages for message templates.

LanguageCode

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

Retrieve Message Templates

You can use the WhatsApp Business Management API to get a list of your existing message templates. The limit parameter is optional.

Request

curl -i -X GET \
'https://graph.facebook.com/v12.0/{whatsapp-business-account-ID}/message_templates?limit=3&access_token=access-token'

Response

{
  "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"
    }
  }

Pagination

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:

  1. When a message template is returned, we always include all its translations (if any). Message templates are grouped by the name field.
  2. The Graph API 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.

Retrieve the Message Template Namespace

The message template namespace is required to send messages using the message templates in the WhatsApp business account.

Request

curl -i -X GET "https://graph.facebook.com/v12.0/{whatsapp-business-account-ID}?fields=message_template_namespace&access_token=system-user-access-token"

Response

{
    "id": "1972385232742141",
    "message_template_namespace": "12abcdefghijk_34lmnop" 
}

Delete Message Templates

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 will attempt to be delivered for 30 days. An example of this is when the customer's device is offline.
  • 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.

Request

curl -X DELETE \
'https://graph.facebook.com/v12.0/{whatsapp-business-account-ID}/message_templates' \
  -d 'name=hello_world_template' \
  -d 'access_token=access-token' 

Response

{
  "success": true
}

Reference

For a list of all possible values for each field, refer to the Graph API reference of the message_templates endpoint.

FAQ

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:

  • Contains potentially abusive content such as abusive language or spam-like content
  • Contains promotional content
  • Does not match the select tag type
  • Formatted incorrectly

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.