Creating & Sending WhatsApp Text Message Template
Create a simple whatsapp text message template. This type of template allows you to predefine the configuration of text message and personalized fields (placeholders).
The body of a message template should only contain text, personalized fields and emojis. There is no limit to the number of parameters allowed in the body but when sending the message template, the total number of characters may not exceed 1024. If using parameters in the body, they may contain many characters as long as the total body length does not exceed the aforementioned 1024 characters.
The following text template example will help you to understand the location of the text, parameters, and JSON format for each one according to the template type. That is, this diagram shows each parameter in which the text template is composed and how it will be displayed by the user.

The requirements before sending the Text Message Template to the recipients via WhatsApp Business API are the following:
-
Create the Text Message Template from the Digital Engagement Platform, in the Templates section or through the Templates API.
-
Once you have created the text message template, you'll need to submit it for WhatsApp approval. This can be done directly from the Digital Engagement Platform where the message template is created or through the Templates API.
-
It takes WhatsApp up to 48 hours to review a message template.
-
After the text message template is created and approved, you can send it to recipients via API by copying each value of the template message to the request body if you created it via UI. Remember , once WhatsApp has approved your message template, our support team will provide you a namespace identifier (Id) of the Message Templates in your account →
"templateNamespace"
.
NOTE
If you created the text message template via UI or API, in both cases our support team will provide you the namespace identifier (
"templateNamespace"
) of the Message Template once the template has been approved.
For more information to create a WhatsApp message template via Digital Engagement Platform go to the WhatsApp Templates section.
Creating a Text Message Template
If you want to create the text message template via Templates API, you need to provide the WhatsApp Business Account ID (WABA) or the unique identifier of the sender, and enter the following parameters to the request body:
HTTP Request : POST /whatsapp/templates
Required Parameter | Description |
---|---|
wabaId | WhatsApp Business Account ID (WABA). In case you don't have a WABA Id, our support team will provide it to you. |
senderId | Unique identifier of the Sender. |
{
"name": "code_shipping",
"category": "TRANSACTIONAL",
"templateLanguages": [
{
"language": "en_US",
"components": [
{
"type": "BODY",
"text": "Hi! your discount code is {{code}}",
"example": {
"body_text": [
[
"4257"
]
]
}
}
]
}
]
}
The parameters presented in the request body example when creating the Text Message Template are the following:
Parameter | Required | Description |
---|---|---|
name | Yes | Name of the template created in your WhatsApp Business Account. The name of each template you create cannot be the same. |
category | Yes | Supported Template Categories.
|
templateLanguages | Yes | Specify the language and components of the template. |
templateLanguages.language | Yes | Specifies the language of the template. Currently the API supports 3 Languages: English, Spanish and Portuguese. Required if you want to send templates in languages other than en_US.English: Spanish: Portuguese: |
templateLanguages.components | Yes | Components of the template. |
templateLanguages.components. type |
Yes | Type of message template you want to send.
|
templateLanguages.components. text |
Yes | Content of the text message template that will be sent to the end user. Emojis and markdown are supported. Maximum length: 1024 characters. |
templateLanguages.components. example |
Yes | Required If the body contains placeholders. |
templateLanguages.components. example.body_text |
Yes | Set Placeholder values of the body. Placeholder values must be replaced with dynamic content inside double curly braces ( Placeholders have to be correctly formatted and in the correct order, regardless of other sections. Example: {{1}}, {{2}}, {{3}}... |
When you created the Text Message Template, the response body contains the following data:
{
"meta": {
"timestamp": 1667428537012,
"transactionId": "447ac3bf-7d9f-4699-ab9b-998c66217475"
},
"data": {
"wabaId": 107837261,
"name": "code_shipping",
"category": "TRANSACTIONAL",
"templateLanguages": [
{
"id": "667214721",
"language": "en_US",
"components": [
{
"type": "BODY",
"text": "Hi! your discount code is {{code}}",
"example": {
"body_text": [
[
"4257"
]
]
}
}
]
}
]
}
}
Parameters presented in the response body example when creating the Text Message Template are the following:
Parameter | Description |
---|---|
data | Data contained in the Text Message Template. |
data.wabaId | WhatsApp Business Account ID (WABA). |
data.name | Name of the template created in your WhatsApp Business Account. The name of each template you create cannot be the same. |
data.category | Supported Template Categories.
|
data.templateLanguages | Specify the language and components of the template. |
data.templateLanguages. id |
Unique identifier of the template. |
data.templateLanguages. language |
Currently the API supports 3 Languages: English, Spanish and Portuguese. Required if you want to send templates in languages other than en_US. English: Spanish: Portuguese: |
data.templateLanguages. components |
Components of the template. |
data.templateLanguages. components.type |
Type of message template you want to send.
|
data.templateLanguages. components.text |
Content of the text message template that will be sent to the end user. Emojis and markdown are supported. Maximum length: 1024 characters. |
data.templateLanguages. components.example |
Required If the body contains placeholders. |
data.templateLanguages. components.example.body_text |
Set Placeholder values of the body. Placeholder values must be replaced with dynamic content inside double curly braces ( Placeholders have to be correctly formatted and in the correct order, regardless of other sections. Example: {{1}}, {{2}}, {{3}}... |
Sending a Text Message Template
There are new changes when you send a text message template to the recipients. So we divide this section in two parts:
-
New Changes (New way to send a text message template)
We recomend you go to this section.
New Changes
Once the text message template has been created via UI or API and approved, the next step is sending the template to the end users through the Messages API.
NOTE
NOTE: Remember , once WhatsApp has approved your message template, our support team will provide you a namespace identifier (Id) of the Message Templates in your account →"templateNamespace". Or you can query the value of the "templateNamespace" parameter through the following method: Getting Sender.
When you created the text message template earlier, you must copy the exact name of the template when sending the template to your recipients in the request body. That is, the value of the parameter "name" when creating the whatsapp template must be the same value of the parameter "templateName" when sending the whatsapp template.
WARNING
You can not edit the template content in the request body because the values of each parameter have been approved by WhatsApp. You are only able to edit a value for placeholders in the body (text message).
In this new version (v2), it is not necessary to copy each value according to its corresponding parameter you set when creating the text template via UI (Digital Engagement Platform) or Templates API to the request body of the Messages API.
There are two new ways to send a text message template to your recipients:
- Including only the unique identifier of the text message template created. You get this id in the response once the template has been created.
{
"templateId": "4567890987654",
"from": "1000000001",
"to": "+1000000002"
}
- Including only the name and language of the text message template once the template has been created.
{
"templateName": "code_shipping",
"templateLanguage": "en_US",
"from": "1000000001",
"to": "+1000000002"
}
NOTE
In case you send the id, name and language in one request body as the following example, it takes as priority the id of the template, not the name and language.
{
"templateId": "4567890987654",
"templateName": "code_shipping",
"templateLanguage": "en_US",
"from": "1000000001",
"to": "+1000000002"
}
If the text message body of the template includes personalized fields (placeholders), you need to include the "globalPlaceholders"
parameter in the request body when sending the template. This parameter allows you to type each placeholder you set in the message when creating the template.
Returning to the previous example, the request body contains the following data:
HTTP Request : POST /whatsapp/messages
{
"templateId": "667214721",
"from": "1000000001",
"to": "+1000000002",
"globalPlaceholders": {
"code": "4257"
}
}
If you notice, you don't have to type the text body message when sending the template like the previous version (v1).
Parameters present in the request body example when sending a Text Template Message are the following:
Parameter | Required | Description |
---|---|---|
templateId | Yes | Unique identifier of the template. |
templateName | No | Name of the template created in your WhatsApp Business Account. |
templateLanguage | No | Template Language you set when creating the text template. Currently the API supports 3 Languages: English, Spanish and Portuguese. Required if you want to send templates in languages other than en_US.English: Spanish: Portuguese: |
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. |
to | Yes | Determines the destination phone number for your template message. Numbers are specified in E.164 format → (‘+’ and a country code). |
globalPlaceholders | No | Required if the text message body contains placeholders. Array that contains placeholders. Enter the value of each placeholder parameter configured in the text message body when creating the template. That is, type the name of the placeholder and its value. Remember, the name of each placeholder is inside double curly braces ( |
When you send a Text Message Template, the response body contains the following data:
{
"meta": {
"timestamp": 1675866052931,
"transactionId": "8ce-8cbc-48bb-84-1598c8"
},
"data": {
"id": "63e3afc4d5b4e4",
"body": "Hi! your discount code is {{code}}",
"from": "1000000001",
"to": "+1000000002",
"date": "2023-02-08T14:20:52.926220289Z",
"statusDate": "2023-02-08T14:20:52.926080215Z",
"externalId": null,
"owner": "[email protected]",
"operator": "[email protected]",
"status": "QUEUED",
"providerId": "dfghj4567"
}
}
Parameters presented in the response body example when sending a Text Message Template are the following:
Parameter | Description |
---|---|
data | Data contained in the Message object. |
data.id | Unique identifier of the WhatsApp message. |
data.body | Content of the text template message that will be sent to the end user. Emojis and markdown are supported. Maximum length: 1024 characters. |
data.from | 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. |
data.to | Determines the destination phone number for your regular message. Numbers are specified in E.164 format → (‘+’ and a country code). |
data.date | Date when the message has been sent. |
data.statusDate | Date when the last update or status change. |
data.externalId | Alphanumeric identifier used for reporting purposes. |
data.owner | Owner or creator of the message. |
data.operator | User who is a member of the owner or creator’s space. |
data.status | When a Message is sent, the system assigns one of the following possible statuses to an WhatsApp message:
|
data.providerId | Unique identifier of the provider. The support team provides this Id once the account has been approved. |
Original Send
Once the text message template has been created via UI or API and approved, the next step is sending the template to the end users through the Messages API.
NOTE
Remember , once WhatsApp has approved your message template, our support team will provide you a namespace identifier (Id) of the Message Templates in your account →
"templateNamespace"
. Or you can query the value of the "templateNamespace" parameter through the following method: Getting Sender.When you created the text message template earlier, you must copy the exact name of the template when sending the template to your recipients in the request body. That is, the value of the parameter
"name"
when creating the whatsapp template must be the same value of the parameter"templateName"
when sending the whatsapp template.
WARNING
You must carefully copy each value according to its corresponding parameter you set when creating the text template via UI (Digital Engagement Platform) or Templates API to the request body of the Messages API.
You can not edit the template content in the request body because the values of each parameter have been approved by WhatsApp. You are only able to set a value for placeholders in the body (text message).
The request body contains the following data:
HTTP Request : POST /whatsapp/messages
{
"from": "1000000001",
"to": "+1000000002",
"body": "Hi! your discount code is {{code}}",
"templateNamespace": "31291098",
"templateName": "code_shipping",
"templateLanguage": "en_US",
"placeholders": {
"CODE": "4257"
}
}
Parameters present in the request body example when sending a Text Template Message are the following:
Parameter | Required | Description |
---|---|---|
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. |
to | Yes | Determines the destination phone number for your template message. Numbers are specified in E.164 format → (‘+’ and a country code). |
body | Yes | Content of the text template message that will be sent to the end user. Emojis and markdown are supported. Maximum length: 1024 characters. |
templateNamespace | Yes | Unique identifier of the Message Templates for your account. Our support team provides this Id once WhatsApp has approved the message template. You can get the “templateNamespace” by querying the information of the sender Id (list Senders) via Senders API. Only templates created in your own namespace will work. |
templateName | Yes | Name of the template created in your WhatsApp Business Account. |
templateLanguage | Yes | Template Language you set when creating the text template. Currently the API supports 3 Languages: English, Spanish and Portuguese. Required if you want to send templates in languages other than en_US.English: Spanish: Portuguese: |
placeholders | Yes | Required If the body contains placeholders. Placeholder values must be replaced with dynamic content inside double curly braces ( Placeholders have to be correctly formatted and in the correct order, regardless of other sections. Example: {{1}}, {{2}}, {{3}}... |
When you send a Text Message Template, the response body contains the following data:
{
"meta": {
"timestamp": 1645414827658,
"transactionId": "830b1b35-1db0-414b-a687-2bd9c627d144"
},
"data": {
"id": "621309ab65a0ac43",
"body": "Hi! your discount code is {{code}}",
"from": "1000000001",
"to": "+1000000002",
"date": "2022-02-21T03:40:27.649724390Z",
"statusDate": "2022-02-21T03:40:27.649644953Z",
"externalId": null,
"owner": "[email protected]",
"operator": "[email protected]",
"status": "SENT",
"providerId": "cTHXRWagvUiGmeoz"
}
}
Parameters presented in the response body example when sending a Text Message Template are the following:
Parameter | Description |
---|---|
data | Data containing the Message object. |
data.id | Unique identifier of the WhatsApp message. |
data.body | Content of the text template message that will be sent to the end user. Emojis and markdown are supported. Maximum length: 1024 characters. |
data.from | 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. |
data.to | Determines the destination phone number for your regular message. Numbers are specified in E.164 format → (‘+’ and a country code). |
data.date | Date when the message has been sent. |
data.statusDate | Date when the last update or status change. |
data.externalId | Alphanumeric identifier used for reporting purposes. |
data.owner | Owner or creator of the message. |
data.operator | User who is a member of the owner or creator’s space. |
data.status | When a Message is sent, the system assigns one of the following possible statuses to an WhatsApp message:
|
data.providerId | Unique identifier of the provider. The support team provides this Id once the account has been approved. |
Updated about 2 months ago