Send an approved WhatsApp text message template with personalized fields through the Messaging API.

A template body can contain text, personalized fields (placeholders), and emojis. There is no limit to the number of parameters in the body, but the complete body—including placeholder values—must not exceed 1,024 characters when you send it.

Before you begin

Create the text message template in Communications Platform from the Message Templates section, or use the Message Templates API.
Submit the template for WhatsApp approval from Communications Platform.
Allow up to 48 hours for WhatsApp to review the template.
After WhatsApp approves the template, copy every template value into the API request body.

🚧
WARNING
You must carefully copy each value according to its corresponding parameter you set when creating the text message template via UI (Communications Platform) to the request body.

Send a Text Message Template

Send the approved template to recipients through the Messaging API.

🚧
WARNING
You can not edit the message template content in the request body because the values of each parameter have been approved by WhatsApp. You are only able to edit the value for placeholders in the body (text message).

Add personalized fields (placeholders)

If your template includes a Text Message component with placeholders, include those placeholders and their values in the request body.

Use the following placeholders object:

"placeholders": {  
    "name": "Elizabeth",  
    "lastName": "Smith"  
}

For each property in the "placeholders" object, use the placeholder name that appears between double curly braces ({{...}}) in the template. Set its value to the content that you want to send.

For example, the following template body uses the name and lastName placeholders:

{  
   "type":"BODY",  
   "text":"Welcome {{name}} {{lastName}} we have a new offer for you!",  
   "example":{  
      "body_text": [  
         [  
            "John",  
            "Doe"  
         ]  
      ]  
   }  
}

Format placeholders in the same order as the message template.

🚧
WARNING
The personalized fields (placeholders) you set when creating the WhatsApp Text Message Template for each component are editable when you send the message template.
Make sure these are examples and do not include any confidential or personal information.
Once the message template is approved and ready to be sent, replace the placeholders with the actual (real) placeholder values.

To send a text message template with a personalized field, provide the following request-body parameters.

HTTP request: POST / notification

{
  "channel": "WHATSAPP",
  "request": {
    "from":"1000000001",
    "to":"+1000000002",
    "templateName":"code_shipping",
    "templateLanguage":"en",
    "message": "Hi! your discount code is {{code}}",
    "placeholders":{
       "code":"34871"
    }
  }
}

The following table describes the request-body parameters:

Parameter	Required	Description
channel	Yes	Specifies the type of delivery channel which the notification message will be sent: `"SMS"`, `"EMAIL"`, `"RCS"`, `"WHATSAPP"`. In this case, we enter the `"WHATSAPP"` value to send the WhatsApp message.
request	Yes	Message content.
request. from	Yes	Phone number of the sender. Phone number provided during the WABA account setup will be used as the sender of the notification message. Only accepts numeric characters. Do not include the "+" sign.
request. to	Yes	Determines the destination phone number for your message template. Numbers are specified in E.164 format → (‘+’ and a country code).
request. templateName	Yes	Name of the message template created in your WhatsApp Business Account.
request. templateLanguage	Yes	Message Template Language you set when creating the message template. Currently the API supports 3 Languages: English, Spanish and Portuguese. Required if you want to send message templates in languages other than English. English: `"en"` Spanish: `"es"` Portuguese: `"pt_BR"`, `"pt_PT"`
request. message	Yes	Content of the text message template that will be sent to the end user. Emojis and markdown are supported. Maximum length: 1024 characters.
request. placeholders	No	Only applies if the `"message"` parameter contains personalized fields (placeholders). Object of personalized fields (placeholders) containing the text message body. From the `"placeholders"` object, set as parameter the placeholder you configured that is inside double curly braces `{{...}}` when creating the message template. Then set the value of the placeholder parameter. The placeholders must be correctly formatted in order of how the message template was created. For example, for a text message body like `“Here is your {{code}}”`, you would set the placeholder as `"code": "34871"`.
request. externalId	No	Alphanumeric identifier used for reporting purposes.
request. clientId	No	Unique user identifier that can be used for reporting purposes. This is an identifier you can use to uniquely identify the destination address in your systems. This is similar to the externalId and will be sent back to you if you are requesting callbacks that contain status changes of the messages you send.
callbacks	No	Indicate one or more (separated by comma) webhook URLs to notify about the status of the message delivery.That is, If you want to receive the status of the message you've sent to your contacts, you need to specify your endpoint. Your endpoint must have a HTTP POST access method and receive a JSON body. The URL is the external callback where the events of the Email will be registered and published. Once an email is processed, its status will be posted to your callback URL. To view the full list and meaning of each status, please refer to the WhatsApp Status section.

A successful request returns the following response body:

{
  "meta": {
    "timestamp": 1642531254980,
    "transactionId": "077da1d0-e089-487e-aed0-59534ba2d9f5",
    "explain": "Send Notification"
  }
}

The following table describes the response-body parameters:

Parameter	Description
meta	`"meta"` segment is dedicated to metadata regarding the call itself.
meta. timestamp	Call’s time mark. Sequence of characters identifying when the message has been sent.
meta. transactionId	Call’s transaction ID, this will help our teams to locate issues faster if arose.
meta. explain	Useful message regarding the operation or the call.