Creating & Sending WhatsApp Text Message Template

Suggest Edits

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 ParameterDescription
wabaIdWhatsApp Business Account ID (WABA).

In case you don't have a WABA Id, our support team will provide it to you.
senderIdUnique identifier of the Sender.
{
  "name": "code_shipping",
  "category": "MARKETING",
  "templateLanguages": [
    {
      "language": "en",
      "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.

  • "MARKETING": Send promotional offers, product announcements, and more to increase awareness and engagement.
  • "AUTHENTICATION": Send codes that allow your customers to securely access their accounts.

    To create an Authentication WhatsApp Template go to the Create Authentication Media Message Template section.

  • "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

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

English: "en"

Spanish: "es"

Portuguese: "pt_BR", "pt_PT"
templateLanguages.components Yes

Components of the template.
templateLanguages.components.
type
 Yes

Type of message template you want to send.

  • "BODY": Content of the text 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

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 ({{...}}) when a message is sent.

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": "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

Supported Template Categories.

  • "MARKETING": Send promotional offers, product announcements, and more to increase awareness and engagement.
  • "AUTHENTICATION": Send codes that allow your customers to securely access their accounts.

    To create an Authentication WhatsApp Template go to the Create Authentication Media Message Template section.

  • "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

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

English: "en"

Spanish: "es"

Portuguese: "pt_BR", "pt_PT"
data.templateLanguages.
components

Components of the template.
data.templateLanguages.
components.type

Type of message template you want to send.

  • "BODY": Content of the text 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

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 ({{...}}) when a message is sent.

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 two ways when you send a text message template to the recipients. So we divide this section in two parts:

Simplified 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

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",
  "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"
}

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 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).
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 the template was created.

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:

  • "SENT": Message was sent to the outbound delivery system.

  • "DELIVERED": Message was delivered to the end-device of the user.

  • "READ": Message has been opened or acknowledged by the end user.
    Note: The “READ” status may not be displayed because an end user can block the read option.

  • "CODE_NOT_ALLOWED": Sender of the WhatsApp Business Account is not valid to send the message.

  • "FAILED"Message delivery failed.

  • "QUOTA_EXCEEDED"WhatsApp Business Account exceeded the message sending limits.
    For more information about Messaging Limits go to: Capacity, Quality Rating, and Messaging Limits section.

  • "EXPIRED"Message was too old to be sent.

  • "INCOMPLETE"The placeholders (personalized fields) of the message sent through templates must be complete. Users who receive the message contain an assigned value of the placeholders. i.e. a message was sent to 3 users with email and activation_link personalized fields, but one user doesn’t contain an email. For that user, the message will not be delivered and will be marked as “incomplete”.

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 the messages, go to the Creating WhatsApp Regular Message section.

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",
  "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.

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:"
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 English.

English: "en"

Spanish: "es"

Portuguese: "pt_BR", "pt_PT"
placeholders Yes

Required If the body contains placeholders.

Placeholder values must be replaced with dynamic content inside double curly braces ({{...}}) when a message is sent.

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:

  • "SENT": Message was sent to the outbound delivery system.

  • "DELIVERED": Message was delivered to the end-device of the user.

  • "READ": Message has been opened or acknowledged by the end user.
    Note: The “READ” status may not be displayed because an end user can block the read option.

  • "CODE_NOT_ALLOWED": Sender of the WhatsApp Business Account is not valid to send the message.

  • "FAILED"Message delivery failed.

  • "QUOTA_EXCEEDED"WhatsApp Business Account exceeded the message sending limits.
    For more information about Messaging Limits go to: Capacity, Quality Rating, and Messaging Limits section.

  • "EXPIRED"Message was too old to be sent.

  • "INCOMPLETE"The placeholders (personalized fields) of the message sent through templates must be complete. Users who receive the message contain an assigned value of the placeholders. i.e. a message was sent to 3 users with email and activation_link personalized fields, but one user doesn’t contain an email. For that user, the message will not be delivered and will be marked as “incomplete”.

data.providerId Unique identifier of the provider. The support team provides this Id once the account has been approved.

Updated 3 months ago