Create a simple WhatsApp text message template. This type of message template allows you to predefine the configuration of text messages 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 message template example will help you to understand the location of the text, parameters, and JSON format for each one according to the tmessage emplate type. That is, this diagram shows each parameter in which the text message 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 message 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:

1. Bold Text: To make text bold, place asterisks *around the text. (e.g., *this text is bold*).
2. Italic Text: To italicize text, use underscores _ around the text. (e.g., _this text is italic_).
3. Strikethrough Text: To strike through text, place tildes ~ around the text. (e.g., ~this text is Strikethrough~).
4. Monospaced Text: To display text in a monospaced (fixed-width) font, use three backticks (</code>) around the text. (e.g.,<code>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 Communications Platform, in the Message Templates section or through the Message Templates API.

• The Message 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 Communications Platform, where the message template is created or through the Message 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 message template to the request body if you created it via UI.

For more information about creating a WhatsApp message template via the Communications Platform, go to the WhatsApp Message Templates section.

Creating a Text Message Template

If you want to create the text message template via Message 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

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:

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:

📘

Retrieving the Status of a WhatsApp Message Template

After creating a WhatsApp message template, it is important to monitor its approval status, as this determines whether the message template can be used in messaging broadcasts. We provide two API endpoints that allow users to retrieve the current status of each message template created:

• Get Message Template: Returns the status of a specific message template.
• List Message Templates: Returns a list of all message templates associated with the WABA, including the current status of each.

These endpoints help you verify whether a message template has been approved by WhatsApp, is under review, or requires further action.

Below are the possible statuses a WhatsApp message template can return, along with their meanings:

Status	Description
APPROVED	The message template has been reviewed and accepted by Meta. It is now active and can be used in broadcasts.
PENDING	The message template has been submitted and is awaiting initial processing.
PENDING_APPROVAL	The message template is under review by Meta and is waiting for final approval.
REJECTED	The message template was reviewed and not approved due to content violations or formatting issues. A new version may need to be submitted.
IN_APPEAL	An appeal has been submitted for a previously rejected message template. It is under re-evaluation.
PAUSED	The message template has been temporarily paused and cannot be used until reactivated.
LIMIT_EXCEEDED	The message template has reached usage or submission limits as defined by Meta. Further use is restricted until limits reset or are adjusted.
DISABLED	The message template has been disabled and is no longer available for use.
DELETED	The message template has been permanently deleted from the account.
PENDING_DELETION	The message template is in the process of being deleted and will no longer be available once deletion is completed.

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 message template to the end users through the Messages API.

🚧

Non-Editable Message Template Content

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).

📘

Message Throughput (TPS)

To know about delivery throughput and how TPS is applied across channels (WhatsApp), go to the Message Throughput (TPS) section.

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 message template has been created.

{
  "templateId": "4567890987654",
  "from": "1000000001",
  "to": "+1000000002"
}

• Including only the name and language of the text message template once the message template has been created.

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

📘

Priority Handling

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 message 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 message template creation.

Text Message Body

If the created message 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 message template. Then set the value of the placeholder parameter.

For instance, according to the previous example, the text message body of the created message 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 message template was created.

🚧

Editable Placeholders

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.

We are going to send the text message 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:

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:

If your business has already engaged in communications with the customer(s) you intend to send broadcasts 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.