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.

Creating Message Templates

You can use the WhatsApp Business Management API to create new message templates.

You cannot currently edit message templates. Please use a test account when learning to use the WhatsApp Business Management API.

Request

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'

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

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

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

Retrieving Message Templates

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.

Request

curl -i -X GET \
'https://graph.facebook.com/v3.3/your-whatasapp-business-account-id/message_templates?limit=3&access_token=your-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.

Deleting 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 (e.g., if the customer's device is offline) will attempt to be delivered for 30 days.
  • 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/v3.3/your-whatsapp-business-account-id/message_templates' \
  -d 'name=hello_world_template' \
  -d 'access_token=your-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.