You create a simple WhatsApp text message template. With this type of message template, you predefine the configuration of text messages and personalized fields (placeholders).

The body of a message template should only contain text, personalized fields, and emojis, with no limit on the number of parameters. However, when you send the message template, the total body length—including all parameter values—cannot exceed 1024 characters.

The following text message template example helps you understand the location of the text, parameters, and JSON format for each message template type. This diagram shows each parameter that makes up the text message template. It also shows how the message appears to the user.

📘
Markdown syntax
Markdown syntax adds basic formatting to your messages. This makes messages easier to read. It also helps recipients notice key information.
Markdown is a lightweight markup language you use to add formatting elements to plain text. Markdown for WhatsApp message templates applies basic text styles in the message body.
WhatsApp only supports a limited set of basic formatting options, such as bold, italics, strikethrough, and monospace:

Bold Text: Bold text is wrapped in asterisks * (e.g., *this text is bold*).

Italic Text: Italic text is wrapped in underscores _ (e.g., _this text is italic_).

Strikethrough Text: Strikethrough text is wrapped in tildes ~ (e.g., ~this text is strikethrough~).

Monospaced Text: Monospaced (fixed-width) text is wrapped in three backticks (```) (e.g., ```this text is monospaced```).

The requirements before sending the Text Message Template to the recipients via WhatsApp Business API are the following:

You 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 submit it for WhatsApp approval. You do this either directly from the Communications Platform where you created it, 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 send it to recipients via API. If you created the template via UI, you copy each value of the message template into the request body.

The WhatsApp Message Templates section covers more information about creating a WhatsApp message template via the Communications Platform.

Creating a Text Message Template

Alternatively, you create the text message template via the Message Templates API. This requires the WhatsApp Business Account ID (WABA) or the unique identifier of the sender. You enter these, along with the following parameters, in the request body:

HTTP Request: POST /whatsapp/templates

Required Parameter	Description
wabaId	WhatsApp Business Account ID (WABA).
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 message template created in your WhatsApp Business Account. No two message templates can share the same name.
category	Yes	Type of message template. Supported message template categories for WhatsApp text message templates: `"MARKETING"`: Used to send promotional offers and product announcements. Increases awareness and engagement. `"UTILITY"`: Used to send account updates, order updates, and alerts. Shares important information.
templateLanguages	Yes	Array of language objects. Each object contains the language the message 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 message 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 component objects containing the different types of options available 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 is sent to the end user. Emojis and markdown are supported. Maximum length: 1024 characters. For instance, the following message includes a line break (\n) and this emoji (😀): "`We are pleased to present our new product: The 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 sample data for the placeholder(s) defined in the `"templateLanguages.components.text"` parameter for Body type. Array of personalized field values containing the text message body.

When you create 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 message template created in your WhatsApp Business Account. No two message templates can share the same name.
data. category	Type of message template. Supported message template categories for WhatsApp text message templates: `"MARKETING"`: Used to send promotional offers and product announcements. Increases awareness and engagement. `"UTILITY"`: Used to send account updates, order updates, and alerts. Shares important information.
data. templateLanguages	Array of language objects. Each object contains the language the message template may be rendered in, and the components.
data. templateLanguages. id	Unique identifier of the message 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 message 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 component objects containing the different types of options available 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 is 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 sample data for the placeholder(s) defined in the `"templateLanguages.components.text"` parameter for Body type. Array of personalized field values containing the text message body.
data. templateLanguages. disabledTrackingButton	It is required when the message template contains buttons. Indicates whether Meta's button click tracking should be enabled or disabled for WhatsApp message templates that include interactive buttons. `"true"`: Enables Meta's behavior to track and report button click events. `"false"` (default): Disables tracking of button clicks. Meta collects no analytics for button interactions.

📘
Retrieving the Status of a WhatsApp Message Template
After creating a WhatsApp message template, you monitor its approval status. This status determines whether the message template can be used in messaging broadcasts.
Two API endpoints let you 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 a message template's status: approved, under review, or requiring 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. It is no longer available once deletion completes.

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. It is no longer available once deletion completes.

Sending a Text Message Template

The text message template is now created and approved, either via UI or API. The next step is sending it to end users through the Messages API.

🚧
Non-Editable Message Template Content
You are unable to 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)
The Message Throughput (TPS) section covers delivery throughput and how TPS is applied across channels (WhatsApp).

You send a text message template to your recipients in two ways:

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
If you send the ID, name, and language together in one request body, as in the following example, the platform gives priority to the ID.
It does not use the name and language in this case.
{ "templateId": "4567890987654", "templateName": "code_shipping", "templateLanguage": "en", "from": "1000000001", "to": "+1000000002" }

Personalized Fields (placeholders)

You learn how to include placeholders in the request body when sending the WhatsApp text message template you set up during template creation.

Text Message Body

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

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

In the "placeholders" object, you use the placeholder name—without the double curly braces {{...}}—as the parameter key. You then set its value to the text that replaces the placeholder.

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 the same order as they appear in the message template.

🚧
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.
The example values you provide should not include confidential or personal information. Once the message template is approved and ready to send, you replace the placeholders with the actual (real) placeholder values.

You send the text message template created earlier—the one with a text body and a personalized field (placeholder). You do this 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 message template.
templateName	No	Name of the message template created in your WhatsApp Business Account.
templateLanguage	No	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"`
from	Yes	Phone number of the sender. Phone number provided during the WABA account setup is used as the sender of the notification message. Only numeric characters are accepted. The "+" sign is not included.
to	Yes	Determines the destination phone number for your message template. Numbers are specified in E.164 format → (‘+’ and a country code).
placeholders	No	Object of personalized fields (placeholders) containing the text message body. In the `"placeholders"` object, you use the placeholder name—without the double curly braces `{{...}}`—as the parameter key. You then set its value to the text that replaces the placeholder. The placeholders must be correctly formatted, in the same order as they appear in the message template. 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 message template that is 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 is used as the sender of the notification message. Only numeric characters are accepted. The "+" sign is not included.
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 of 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 Workspace.
data. status	When a message is sent, the system assigns one of the following possible statuses to a WhatsApp message: `"CODE_NOT_ALLOWED"`: The platform suggests that the WABA used is not activated on the platform, or that it 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. You contact the support team to verify the WABA. `"INCOMPLETE"`: The platform indicates that a personalized WhatsApp message was sent without the necessary placeholder data filled in. Personalized messages feature dynamic fields—like "Name", "Phone Number", "Last Name", and similar. These fields need to be populated before sending. `"BLACKLISTED"`: The platform 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 blocked from receiving further communications from the sender's number or broadcast. This ensures that no messages are delivered to that recipient. `"QUOTA_EXCEEDED"`: The WhatsApp Business Account (WABA) has surpassed the allowed messaging limit for a specified period, as defined by WhatsApp's policies. `"SENT"`: Indicates that the message has been successfully dispatched from the platform. It is en route to Meta. This status means the message is on its way to the recipient. It 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"`: The platform has received confirmation of message delivery from Meta. The message has successfully reached the recipient's device. This status confirms that the message was sent and processed by Meta. It also confirms that the message was received by the intended recipient's WhatsApp application. This means the communication was completed successfully. `"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.

You create a regular message instead of a template message in either of these cases:

Your business has already engaged in communications with the customer.
The customer has contacted your business within a 24-hour window.

The Creating WhatsApp Session Messages section covers how to reply to these messages.