/v1/messages
You can use the messages
endpoint to send message templates to your customers. Use the WhatsApp Manager to create your message templates. For more information, read the Creating Message Templates documentation.
This document covers:
template
message template typePOST /v1/messages { "to": "recipient_wa_id", "ttl": "P4D" | "3600" | 3600, # The "ttl" field will be deprecated in v2.33. "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 } } ] }] } }
hsm
message template typeDeprecation of the hsm
message template type is planned for a future version. v2.31
will be the last version to support this feature.
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. Note: Beginning with v2.27.8
, the namespace
and element_name
parameters must match up or the message will fail to send.
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.
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 will look 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.
Name | Required | Description |
---|---|---|
| Yes (for message templates) | The type of message being sent |
| Yes | The WhatsApp ID to whom the message is being sent |
| No | As of |
| No (Optional) | Value: |
| Yes (For | Contains all the template information |
| Yes (for message templates) | The containing element for the message content — Indicates that the message is highly structured. Parameters contained within provide the structure. |
ttl
objectThe ttl
parameter in message templates will be deprecated with v2.33
in 2021. Please be prepared to stop using this parameter to avoid any unexpected errors with its functionality after launch of v2.33
.
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 will expire and will not be delivered. You will get a failed
callback notification with error code 410
when a sent message expires (such as the example below), but there won't be a delivery receipt because messages that expire will not be delivered.
failed
callback notification"statuses": [ { "errors": [ { "code": 410, "title": "Message expired" } ], "id": "gBGGFmkiWVVPAgmurVK0Oo_-o60", "recipient_id": "16695551234", "status": "failed", "timestamp": "1538520126" } ]
template
objectName | Required | Description |
---|---|---|
| Yes | Namespace of the template |
| Yes | Name of the template |
| Yes | Specifies the language the template may be rendered in |
| No | Array containing the parameters of the message |
components
objectName | Required | Description |
---|---|---|
| Yes | Describes the |
| No | Array containing the content of the message |
parameters
objectName | Required | Description |
---|---|---|
| Yes | Describes the |
hsm
objectName | Required | Description |
---|---|---|
| Yes | The namespace that will be used |
| Yes | The element name that indicates which template to use within the namespace |
| Yes | Allows for the specification of a deterministic or fallback language |
| Yes | This field is an array of values to apply to variables in the template |
Please note that the fallback
language policy is deprecated beginning with v2.27.8
and the deterministic
language policy is now the default policy.
The language
parameter sets the language policy for a message template.
Name | Required | Description |
---|---|---|
| Yes | Default: The |
| Yes | The code of the language or locale to use — Accepts both |
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 will be created.
A message template namespace is a bundle of language packs for a particular business.
Please note that the fallback
language policy is deprecated beginning with v2.27.8
and the deterministic
language policy is now the default policy.
There are two policies that you can specify when sending an message template: deterministic
and fallback
.
deterministic
— Deliver the message template in exactly the language and locale asked for.fallback
— Deliver the message template in the language that matches user's language/locale setting on device. If one can't be found, deliver using the specified fallback language.The only real difference is that with fallback
, we try to locate the language pack using the device's language/locale setting first.
If a message template is sent with the language: policy
field set to deterministic
, the device will query the server for a language pack of that particular language.
If 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" } ], }
When this message is delivered to the device, the device will do the following:
Step 1: "policy": "deterministic"
and "code": "en"
— Is there a cached en
pack on the device?
en
pack found on the server?
structure_unavailable
error via a Webhook, and no messages are rendered on the device.Step 2: "element": "hello_world"
— Does the element exist?
en
pack from the server and repeat Step 2.structure_unavailable
error via a Webhook, and no messages are rendered on the device.Note: 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:
Please note that the fallback
language policy is deprecated beginning with v2.27.8
and the deterministic
language policy is now the default policy.
If a message template is sent with the language: policy
field is set to fallback
, the device will try to be smart and pick the right translation to display depending on the device's language/locale settings.
If you send a message template like the following:
{ "namespace": "business_a_namespace" "element_name": "hello_world", "language": { "policy": "fallback", "code": "en" } "localizable_params": [ { "default": "1234" } ], }
When this message is delivered to the device, the device will do the following:
Step 1: "policy": "fallback"
and "code": "en"
— Load the device's language/locale setting as device_lg-lc
. Is there a cached device_lg-lc
pack on the device?
device_lg-lc
language pack found on the server?
device_lg-lc
language pack.lg-lc
(in this case, en
), and check the cache or query the server for an en
pack ("code": "en"
). Is it found?
en
pack.structure_unavailable
error via a Webhook, and no messages are rendered on the device.Step 2: "element": "hello_world"
— Does the element exist?
structure_unavailable
error via a Webhook, and no messages are rendered on the device.To avoid issues when using the fallback
policy, ensure that for every language you support, a translation is provided for all elements.
When sending a message template, the hsm
object is required. To define message templates, you specify a namespace
and an element_name
pair that identify a template. Templates have parameters that will be 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.
Note that the number of parameters passed into the payload must match the number of parameters in the hsm
object. If not, you will 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 will fallback 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.
Name | Type | Required | Description |
---|---|---|---|
| String | Yes | Default text if localization fails |
|
| No | If the |
|
| No | If the |
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 will allow 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. Note that 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 } } } ] } }
A successful response includes a messages
object with an id
.
{ "messages": [{ "id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU" }] }
An unsuccessful response will contain an error object that will contain an error string, error code and other information. See Error and Status Codes for more information on errors.