Message Templates

WhatsApp message templates are specific message formats that businesses use to send out notifications or customer care messages to people that have opted in to notifications. Messages can include appointment reminders, shipping information, issue resolution or payment updates.

This document contains reference information about message templates. For a guide on how to create and send a template, see Sending Message Templates. For all parameters that can be used in a message template, see Messages, Message Template.

Supported Template Categories

Translations

WhatsApp does not do any translations for your business. All message template translations must be entered by you in same format described here. The element name is the same for all translations.

When sending a message template from the WhatsApp Business API, you need to specify the language you would like the message template to display by using the language field.

If you are planning to support more than one language, you need to provide translations for all supported languages for all elements.

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

Georgian

ka

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

Kinyarwanda

rw_RW

Korean

ko

Kyrgyz (Kyrgyzstan)

ky_KG

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

Language Packs

Message templates are stored in the form of language packs. A language pack is basically a bundle of message template elements for a particular language/locale. If a business contains at least one translation for a language/locale, they are considered to support that, and a pack for that language/locale is created.

A message template namespace is a bundle of language packs for a particular business.

Language Policy Options

The default language policy option is deterministic —we used to offer the fallback option, but it has been deprecated.

If a message template is sent with the language: policy field set to deterministic, WhatsApp delivers the message template in exactly the language and locale asked for. The device queries the server for a language pack of that particular language.

This is how the process works:

Step 1: You send a message template like the following:

{ 
  "namespace": "business_a_namespace" 
  "element_name": "hello_world", 
  "language": {
      "policy": "deterministic",
      "code": "en"
  }
  "localizable_params": [ 
      { "default": "1234" }
  ], 
}

Step 2: When this message is delivered to the device, the device does the following:

  • Policy/Code Check - Given "policy": "deterministic" and "code": "en", is there a cached en pack on the device?
    • If yes, move to Element Check.
    • If not, can the en pack be found on the server?
      • If yes, update local cache and go to Element Check.
      • If not, log the failure, the server returns a structure_unavailable error via a Webhook, and no messages are rendered on the device.

  • Element Check - Does the "element": "hello_world" element exist?
    • If yes, unpack the parameters and render the message on the device.
    • If not:
      • If the language pack is from the local cache, download the latest en pack from the server and repeat Element Check.
      • If the language pack was recently downloaded from the server, log the failure, the server returns a structure_unavailable error via a Webhook, and no messages are rendered on the device.

The device language/locale settings are completely ignored.

A problem that can arise when using the deterministic policy is if what you're requesting doesn't exist. Make sure:

  • The namespace is correct,
  • The element name is correct,
  • The language/locale translation exists for that element, and
  • That the number of parameters sent matches what is specified in the message template.

Localization

Message templates provide localization support out-of-the-box by localizing the message according to the device locale settings.

Localizable Parameters

Templates have parameters that are dynamically incorporated into the message. For the example used in this document, the message template looks like this:

"You made a purchase for {{1}} using a credit card ending in {{2}}."

For "namespace": "cdb2df51_9816_c754_c5a4_64cdabdcad3e" with "element_name": "purchase_with_credit_card", the first value you list replaces the {{1}} variable in the template message and the second value you list replaces the {{2}} variable.

The number of parameters passed into the payload must match the number of parameters in the template object. If not, you get a callback informing you that there was an issue displaying the message template.

Some of these parameters (e.g., date_time or currency) are localizable so that they are displayed appropriately based on the customer's language and locale preferences. If the device is unsuccessful in localizing a parameter, it falls back to the value that is provided as the "default" value.

The localizable_params options are shown in the table below:

Parameters

NameDescription

default

type: String

Required.

Default text if localization fails. All of the localization parameters must have a default value. The default value is all that is needed when you are specifying text.

currency

type: currency object

Optional.

If the currency object is used, it contains required parameters currency_code and amount_1000.

date_time

type: date_time object

Optional.

If the date_time object is used, further definition of the date and time is required. See the example below for two of the options.

The currency Object

The Whatsapp Business API client attempts to format the currency based on the specified localization.

NameDescription

currency_code

type: String

Required.

Currency code as defined in ISO 4217.

amount_1000

type: Integer

Required.

Amount multiplied by 1000.

The date_time Object

The Whatsapp Business API client attempts to format the date/time based on the specified localization. The supported date and time formats include:

  • Component Time — The time is assembled from components (i.e., day of the week, month, hour, etc.) The time specified will be the same, regardless of the time zone the client is in.
  • Unix Time — The time to be displayed is dependent on the time zone the client is in.

HSMDateTime

NameDescription

component

type: HSMDateTimeComponent

Required if unix_epoch is not present.

Date/time by component.

unix_epoch

type: HSMDateTimeUnixEpoch

Required if component is not present.

Date/time by Unix epoch.

At least one of the following fields is required: component or unix_epoch. If used, only one of them can be present.

HSMDateTimeComponent

NameDescription

day_of_week

type: String

Optional.

If different from the value derived from the date (if specified), use the derived value. Both strings and numbers are accepted.
Options: "MONDAY", 1, "TUESDAY", 2, "WEDNESDAY", 3, "THURSDAY", 4, "FRIDAY", 5, "SATURDAY", 6, "SUNDAY", 7

year

type: Integer

Optional.

The year.

month

type: Integer

Optional.

The month.

day_of_month

type: Integer

Optional.

The day of month.

hour

type: Integer

Optional.

The hour.

minute

type: Integer

Optional.

The minute.

calendar

type: String

Optional.

Type of calendar.
Options: GREGORIAN, SOLAR_HIJRI

HSMDateTimeUnixEpoch

HSMDateTimeUnixEpoch will be deprecated. HSMDateTimeComponent will be the default going forward. Please make changes to your code to avoid issues.

NameDescription

timestamp

type: Integer

Required.

Epoch timestamp in seconds. This field is planned to be deprecated.

Example

To specify currency and date in addition to the default, when applicable, use the currency and date_time objects. This allows the client to attempt to localize this data the best way possible and fallback to the default option only if they cannot localize the data.

Using the currency and date_time objects for appropriate parameters is highly recommended to enable an optimal localized experience for your customers.