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.

📘
Markdown syntax
Markdown syntax is a powerful tool that can help you make your messages stand out and capture the attention of your recipients. You can create visually appealing and easy-to-understand messages. making your messages more readable. In the world of short attention spans, properly formatted messages can help ensure that your content is understood and remembered. Therefore, markdown is a lightweight markup language that you can use to add formatting elements to plain text text.
Markdown for WhatsApp templates refers to a simplified text formatting system that allows you to apply basic styles to text in WhatsApp (Text Message - Body).
WhatsApp only supports a limited set of basic formatting options, such as bold, italics, strikethrough, and monospace:

Bold Text: To make text bold, place asterisks *around the text. (e.g., *this text is bold*).

Italic Text: To italicize text, use underscores _ around the text. (e.g., _this text is italic_).

Strikethrough Text: To strike through text, place tildes ~ around the text. (e.g., ~this text is Strikethrough~).

Monospaced Text: To display text in a monospaced (fixed-width) font, use three backticks (```) around the text. (e.g.,```this text is Monospaced```).

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.
The Template Category must be Marketing or Utility.
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 a 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.

For more information about creating a WhatsApp message template via the 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.

The following text message template example includes a text body with a personalized field (placeholder).

{
  "name": "code_shipping",
  "category": "MARKETING",
  "templateLanguages": [
    {
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "text": "Hi! your discount code is {{code}}",
          "example": {
            "body_text": [
              [
                "34871"
              ]
            ]
          }
        }
      ]
    }
  ]
}

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	Type of message template. Supported Template Categories for WhatsApp Text Message Template. `"MARKETING"`: Send promotional offers, product announcements, and more to increase awareness and engagement. `"UTILITY"`: Send account updates, order updates, alerts, and more to share important information.
autoCategory	No	Allow to assign or change the selected category according to the rules and content of the template. Avoid being rejected for being wrongly categorized `true`: authorize META to change the category type if necessary. Costs may vary for the new category. `false`: not authorize META to change the category type.
templateLanguages	Yes	Array of languages objects containing the language that template may be rendered in and the components.
templateLanguages.language	Yes	Language of the message template. Currently the API supports 3 Languages: English, Spanish and Portuguese. Required if you want to send templates in languages other than English. English: `"en"` Spanish: `"es"` Portuguese: `"pt_BR"`, `"pt_PT"`
templateLanguages.components	Yes	The parts of the message template. Array of components objects containing the different types of options you can include in the message.
templateLanguages.components. type	Yes	Type of component of the message template you want to send. `"BODY"`(Required): The main content of the message template.
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. For instance, let's compose the following message that includes a line break (\n) and this emoji (😀): "`We are pleased to present our new product: \nThe Amplifier 480xAr :grinning:`"
templateLanguages.components. example	Yes	it is required when the body contains placeholders.
templateLanguages.components. example.body_text	Yes	it is required when the body contains placeholders. Specifies the value(s) as a sample data for the placeholder(s) defined in the `"templateLanguages.components.text"` parameter for Body type. Array of personalized fields values containing the text message body.

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": "MARKETING",
    "templateLanguages": [
      {
        "id": "667214721",
        "language": "en",
        "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	Type of message template. Supported Template Categories for WhatsApp Text Message Template. `"MARKETING"`: Send promotional offers, product announcements, and more to increase awareness and engagement. `"UTILITY"`: Send account updates, order updates, alerts, and more to share important information.
data.autoCategory	Allow to assign or change the selected category according to the rules and content of the template. Avoid being rejected for being wrongly categorized `true`: authorize META to change the category type if necessary. Costs may vary for the new category. `false`: not authorize META to change the category type.
data.templateLanguages	Array of languages objects containing the language that template may be rendered in and the components.
data.templateLanguages. id	Unique identifier of the template.
data.templateLanguages. language	Language of the message template. Currently the API supports 3 Languages: English, Spanish and Portuguese. Required if you want to send templates in languages other than English. English: `"en"` Spanish: `"es"` Portuguese: `"pt_BR"`, `"pt_PT"`
data.templateLanguages. components	The parts of the message template. Array of components objects containing the different types of options you can include in the message.
data.templateLanguages. components.type	Type of component of the message template you want to send. `"BODY"`(Required): The main content of the message template.
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	it is required when the body contains placeholders.
data.templateLanguages. components.example. body_text	it is required when the body contains placeholders. Specifies the value(s) as a sample data for the placeholder(s) defined in the `"templateLanguages.components.text"` parameter for Body type. Array of personalized fields values containing the text message body.

Sending a Text Message Template

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.

🚧
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 the value for placeholders in the body (text message).

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",
  "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",
"from": "1000000001",
"to": "+1000000002"
}

Personalized Fields (placeholders)

This section will guide you on how to include the placeholders in the request body for sending the WhatsApp text message template that you set up during the template creation.

Text Message Body

If the created template includes a "Text Message" component with placeholder(s), the example payload JSON will be as follows:

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

From the "placeholders" object, set as parameter the placeholder you configured that is inside double curly braces {{...}} when creating the template. Then set the value of the placeholder parameter.

For instance, according to the previous example, the text message body of the created template is as follows:

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

The placeholders must be correctly formatted in order of how the template was created.

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

We are going to send the text message template example we created earlier that includes a text body with a personalized field (placeholder) by entering the following parameters in the request body:

HTTP Request : POST /whatsapp/messages

{
    "from":"1000000001",
    "to":"+1000000002",
    "templateName":"code_shipping",
    "templateLanguage":"en",
    "placeholders":{
       "code":"34871"
    }
 }

Parameters present in the request body example when sending a Text Message Template 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 template. Currently the API supports 3 Languages: English, Spanish and Portuguese. Required if you want to send templates in languages other than English. English: `"en"` Spanish: `"es"` Portuguese: `"pt_BR"`, `"pt_PT"`
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).
placeholders	No	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 template. Then set the value of the placeholder parameter. The placeholders must be correctly formatted in order of how the template was created. For example, for a text message body like `“Here is your {{code}}”`, you would set the placeholder as `"code": "34871"`.

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 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: `"CODE_NOT_ALLOWED"`: Messangi suggests that the WhatsApp Business Account (WABA) used is either not activated on the platform or lacks the capability to message the recipient. Additionally, it could be because the owner does not have a WABA assigned , which is required to send the message. Contact our support team to verify the WABA. `"INCOMPLETE"`: Messangi indicates that a personalized WhatsApp message was sent without the necessary placeholder data filled in. Please note, personalized messages are those that feature dynamic fields—like "Name", "Phone Number", "Last Name", and similar—which need to be populated before sending. `"BLACKLISTED"`: Messangi indicates that the intended recipient's phone number is on a blacklist, preventing any messages from being sent to that number. When a number is blacklisted, it is essentially blocked from receiving any further communications from the sender's number or campaign, ensuring that no messages are delivered to that recipient. `"QUOTA_EXCEEDED"`: The WhatsApp Business Account (WABA) has surpassed the allowed limit for sending messages within a specified period, as defined by WhatsApp's messaging policies or limits. `"SENT"`: Indicates that the message has been successfully dispatched from our system and is en route to META. This status means that the message is on its way to the recipient but does not confirm that the message has been delivered to the end user. It signifies a successful handoff to the next stage in the message delivery process. `"DELIVERED"`: Messangi has received confirmation of message delivery from META. The message has successfully reached the recipient's device. This status confirms that the message not only was sent and processed by META but also was received by the intended recipient's WhatsApp application, ensuring that the communication was successfully completed. `"READ"`: Indicates that the recipient has opened and seen the message. `"FAILED"`: Indicates that META could not deliver the message to the recipient's device.
data.providerId	Unique identifier of the provider. The support team provides this Id once the account has been approved.

If your business has already engaged in communications with the customer(s) you intend to send campaigns or messages to, or the customer has contacted your business within a 24-hour window, you can create a regular message. To reply to the messages, go to the Creating WhatsApp Session Messages section.

Creating & Sending WhatsApp Text Message Template

📘
Markdown syntax

Creating a Text Message Template

Sending a Text Message Template

🚧
WARNING

📘
NOTE

Personalized Fields (placeholders)

🚧
WARNING

📘Markdown syntax

Creating a Text Message Template

Sending a Text Message Template

🚧WARNING

📘NOTE

Personalized Fields (placeholders)

🚧WARNING

📘
Markdown syntax

🚧
WARNING

📘
NOTE

🚧
WARNING