Sending Message Templates

/v1/messages

Use the messages endpoint to send message templates to your customers. Message templates can be created on the WhatsApp Manager —see Creating Message Templates.

This document covers:

Prerequisites

Make sure that you have completed the actions in the Messages — Prerequisites documentation.

Request

Recommended: Using the template Message Template Type

POST /v1/messages
{
  "to": "recipient_wa_id",
  "ttl": "P4D" | "3600" | 3600, # The "ttl" field will be deprecated in v2.35.
  "type": "template",
  "template": {
        "namespace": "your-namespace",
        "name": "your-template-name",
        "language": {
            "code": "your-language-and-locale-code",
            "policy": "deterministic"
        },
        "components": [{
            "type": "body",
            "parameters": [
                {
                    "type": "text",
                    "text": "your-text-string"
                },
                {
                    "type": "currency",
                    "currency": {
                        "fallback_value": "$100.99",
                        "code": "USD",
                        "amount_1000": 100990
                    }
                },
                {
                    "type": "date_time",
                    "date_time" : {
                        "fallback_value": "February 25, 1977",
                        "day_of_week": 5,
                        "day_of_month": 25,
                        "year": 1977,
                        "month": 2,
                        "hour": 15,
                        "minute": 33
                    }
                },
                {
                "type": "date_time",
                    "date_time" : {
                    "fallback_value": "February 25, 1977",
                    "timestamp": 1485470276
                    }
                }
            ]
        }]
    }
}

Using the hsm Message Template Type

The hsm parameter contains a namespace and an element_name pair that identify a template and the values to apply to variables in that template. Deprecation of the hsm message template type is planned for a future version.

The following code provides an example of sending a message template. This example uses the purchase_with_credit_card element name within the cdb2df51_9816_c754_c5a4_64cdabdcad3e namespace —the namespace and element_name parameters must match up or the message fails to send.

POST /v1/messages
  
{
    "to": "whatsapp_id",
    "ttl": "P1D" | "86400" | 86400,
    "type": "hsm",
  
    "hsm": { 
        "namespace": "cdb2df51_9816_c754_c5a4_64cdabdcad3e",
        "element_name": "purchase_with_credit_card", 
        "language": {
            "policy": "deterministic",
            "code": "en_US"
        },
        "localizable_params": [ 
            { "default": "$10" }, 
            { "default": "1234" } 
        ]
    }  
}

The resulting message received by the customer looks like this:

You made a purchase for $10 using a credit card ending in 1234.

As you can see from looking at the localizable parameters and the message the client received, the template used the default value of 10 as the amount of the purchase and the default value of 1234 as the last numbers of the account.

Parameters

Name Description

type

Required for message templates.

The type of message being sent.
Options:

  • text - Default
  • image
  • audio
  • document
  • template - Use this to send a media template message
  • hsm

to

Required.

The WhatsApp ID to whom the message is being sent.

ttl
To be deprecated in v2.35

Optional.

As of v2.21.3 — Time To Live (TTL) duration.
Default: 7 days
Other options: The minimum and maximum supported durations are 1 to 30 days (both inclusive).


Accepts both a string in the ISO-8601 duration format as well as just seconds. Durations must be specified in exact multiple of days; any values that are in between are automatically rounded to the nearest day. See the ttl object section for more information.

recipient_type

Optional.

Value: individual

template

Required for template messages.

Contains all the template information.

hsm

Required for message templates.

The containing element for the message content. Indicates that the message is highly structured. Parameters contained within provide the structure.

The ttl Object

Beginning with v2.21.3, the ttl object provides the ability to set an expiration duration for messages (i.e., Time To Live). Businesses can use this to ensure that messages are delivered in a given time window. Currently, TTLs are only supported for message templates.

If the message is not delivered to the customer before the expiration period the message expires and is not delivered. You get a failed callback notification with error code 410 when a sent message expires (such as the example below), but there isn't a delivery receipt because messages that expire are not delivered.

The ttl parameter will be deprecated with v2.35 in 2021. Be prepared to stop using this parameter to avoid any unexpected errors with its functionality after launch of v2.35.

Example failed Callback Notification

"statuses": [
    {
        "errors": [
            {
                "code": 410,
                "title": "Message expired"
            }
        ],
        "id": "gBGGFmkiWVVPAgmurVK0Oo_-o60",
        "recipient_id": "16695551234",
        "status": "failed",
        "timestamp": "1538520126"
    }
]

The template Object

NameDescription

namespace

Required.

Namespace of the template.


Beginning with v2.27.8, this must be the namespace associated with the WhatsApp business account that owns the phone number associated with the current WhatsApp Business API client or the message fails to send.

name

Required.

Name of the template.

language

Required.

Specifies the language the template may be rendered in. Only the deterministic language policy works with media template messages. See the Language section for more information.

components

Optional.

Array containing the parameters of the message.

The components Object

NameDescription

type

Required.

Describes the component type.
Values: header, body, footer

parameters

Optional.

Array containing the content of the message.

The parameters Object

NameDescription

type

Required.

Describes the parameter type.
Values: text, currency, date_time, image, document, video


The media types (image, document and video) follow the same format as those used in standard media messages, see the Media documentation for more information. Only PDF documents are currently supported for media message templates.


For more information about currency and date_time, see the Localizable Parameters section. The currency and date_time parameters for template messages uses fallback_value in place of default. See the Request sample above for an example.

The hsm Object

Deprecation of the hsm object is planned for a future version.

Name Description

namespace

Required.

The namespace to be used. Beginning with v2.2.7, if the namespace does not match up to the element_name, the message fails to send.

element_name

Required.

The element name that indicates which template to use within the namespace. Beginning with v2.2.7, if the element_name does not match up to the namespace, the message fails to send.

language

Required.

Allows for the specification of a deterministic language. See the Language section for more information.


This field used to allow for a fallback option, but this has been deprecated with v2.27.8.

localizable_params

Required.

This field is an array of values to apply to variables in the template. See the Localizable Parameters section for more information.

Language

The language parameter sets the language policy for a message template.

Parameters

Name Description

policy

Required.

Default: deterministic
The language policy the message should follow. The fallback option was deprecated with v2.27.8.

code

Required.

The code of the language or locale to use. Accepts both language and language_locale formats (e.g., en and en_US).

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

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.

Localizable Parameters

When sending a message template, the hsm object is required. To define message templates, specify a namespace and an element_name pair that identify a template. 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 hsm 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. For more information on localizable parameters, read the Localization documentation.

Parameters

NameDescription

default

type: String

Required.

Default text if localization fails

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.

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

However, to specify currency and date in addition to the default, when applicable, use the currency and date_time objects, as shown below. 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.

The following is a complete example that demonstrates the use of all of the currently supported localized types:

{
  "to": "19195551112",
  "type": "hsm",
  "recipient_type": "individual",
  
  "hsm": {
    "namespace": "cdb2df51_9816_c754_c5a4_64cdabdcad3e",
    "element_name": "four_lparam_demo",
    "language": {
            "policy": "deterministic",
            "code": "en_US"
        }
  
    "localizable_params": [
      {
        "default": "just a string"
      },
      {
        "default": "$100.99",
        "currency": {
          "currency_code": "USD",
          "amount_1000": 100990
        }
      },
      {
        "default": "February 25, 1977",
        "date_time": {
          "component": {
            "day_of_week": 5,
            "day_of_month": 25,
            "year": 1977,
            "month": 2,
            "hour": 15,
            "minute": 33
          }
        }
      },
      {
        "default": "January 26, 2017",
        "date_time": {
          "unix_epoch": {
            "timestamp": 1485470276
          }
        }
      }
    ]
  
  }
}

Response

A successful response includes a messages object with an id.

{
  "messages": [{
    "id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
  }]
}  

An unsuccessful response contains an error object with an error string, error code and other information. See Error and Status Codes for more information.

FAQ

Absolutely! Reach out to your WhatsApp representative and make this request. Please refer to the Creating Message Templates documentation for the information we will need from you to process your Message Template creation.