Message Templates

A message template is required to start a business-initiated conversation. These conversations can be customer care messages or appointment reminders, payment or shipping updates, alerts, and more.


  • A Message template must be approved before it can be used to start a conversation. Learn more.
  • To start a business-initiated conversation a customer must have opted-in to receive messages from your business. Learn more.

Supported Template Categories

  • Marketing – Send promotional offers, product announcements, and more to increase awareness and engagement.
  • One-time passwords – Send codes that allow your customers to securely access their accounts.
  • Transactional - Send account updates, order updates, alerts, and more to share important information.


When sending a message template, you need to specify the language using the language field. Your business is responsible for all translations you wish to use.

Language Packs

Message templates are stored in language packs. A language pack is a bundle of message template elements for a particular language or locale. If a business supports at least one translation for a language or locale, a pack for that language or locale is created.

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

Language Policy Options

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

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
  • The number of parameters sent matches what is specified in the message template


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 defaults to the fallback_value.

If you need to specify currency and date in addition to the fallback_value, use the currency and date_time objects. This allows the client to optimally localize the data the best way possible, only defaulting to the fallback_value when they cannot localize the data.

The localizable_params options are shown in the table below:




type: String


Default text if localization fails. All of the localization parameters must have a fallback value. When specifying text, just the fallback value is required.


type: currency object


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


type: date_time object


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.



type: String


Currency code as defined in ISO 4217.


type: Integer


Amount multiplied by 1000.


    "type": "currency",
    "currency" : {
        "fallback_value": "$230.99",
        "code": "USD",
        "amount_1000": 230990

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.




type: DateTimeComponent

Required if unix_epoch is not present.

Date/time by component.


type: DateTimeUnixEpoch

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.




type: String


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


type: Integer


The year.


type: Integer


The month.


type: Integer


The day of month.


type: Integer


The hour.


type: Integer


The minute.


type: String


Type of calendar.


    "type": "date_time",
    "date_time" : {
        "fallback_value": "October 25, 2020",
        "day_of_week": "Saturday",
        "day_of_month": 25,
        "year": 2020,
        "month": 10,
        "hour": 12,
        "minute": 0


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



type: Integer


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

Next Steps

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.