Guides

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 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 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. 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 (Id) of the Message Template ("templateNamespace") 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.

If you want to create the text message template via Templates API, you need to enter the following parameters to the request body:

HTTP Request : POST /whatsapp/templates

Before creating the text template, you need to provide the WhatsApp Business Account ID (WABA) or the unique identifier of the sender.

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": "TRANSACTIONAL",
  "templateLanguages": [
    {
      "language": "en_US",
      "components": [
        {
          "type": "BODY",
          "text": "Hi! your discount code is {{code}}",
          "example": {
            "body_text": [
              [
                "code"
              ]
            ]
          }
        }
      ]
    }
  ]
}

The parameters presented in the request body example when creating a 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.
  • "PASSWORDS": Send codes that allow your customers to securely access their accounts.
  • "TRANSACTIONAL": Send account updates, order updates, alerts, and more to share important information.
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: "en", "en_GB", "en_US"

Spanish: "es", "es_AR", "es_ES", "es_MX"

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.
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 create a 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": [
                [
                  "code"
                ]
              ]
            }
          }
        ]
      }
    ]
  }
}

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.
  • "PASSWORDS": Send codes that allow your customers to securely access their accounts.
  • "TRANSACTIONAL": Send account updates, order updates, alerts, and more to share important information.
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: "en", "en_GB", "en_US"

Spanish: "es", "es_AR", "es_ES", "es_MX"

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

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

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

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

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: "en", "en_GB", "en_US"

Spanish: "es", "es_AR", "es_ES", "es_MX"

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

Media Message Template

Media message templates expand the content you can send recipients beyond the standard message template type to include headers, media and buttons. That is, this type of template allows you to predefine the configuration of text message, media and buttons features and personalized fields (placeholders) that provide additional information.

Media Message Templates contain 3 main components:

  • Header (Text & Media)

  • Text Message (body)

  • Buttons (Call to Action & Quick Reply)

Header : This type of template includes an optional header.

The Header contains the media, which can be text, an image, video or pdf file and it is located at the top of the message. You can use headers to provide additional information to end users.

Headers can contain the following:

  • Text: Should only contain text and emojis. A text header has a limit of 60 characters including emojis.

📘

NOTE

When creating a media message template with a media header, you do not specify the actual files that will be used; you only specify the type of file that will be used. Actual files to be sent are specified as links when sending the template.

  • Image: Images must be less than 5MB and the format must be .jpg or .png.

  • Video: Video must be less than 5MB and the format must be .mp4, .3gpp (Only H.264 video codec and AAC audio codec are supported).

  • Document: Documents must be less than 5MB and the format must be .pdf

📘

NOTE

You are only able to edit the Multimedia Header (Image, Video or Document) in the request body when sending the message template to the recipient.

Text Message: The body of a message template should only contain text, personalized fields (placeholders) 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 1024 characters.

Buttons: This type of template includes optional buttons.

There are two kinds of buttons that may be added to a media message template: call to action and quick reply.

  • Call To Action: A call to action button allows the customer to call a specific phone number or go to a specific URL. Up to two (2) distinct buttons are allowed, you can’t place 2 phone buttons or 2 URL buttons.

    Format options include Phone Number, URL and Dynamic URL. This lets you add a phone number or website URL to your message. If you choose a URL, you can choose from a Static (fixed) website URL or a Dynamic website URL, which creates a personalized link for each campaign you use the template on by adding a variable at the end of the link. The suffix value you set here acts as a default, when you send this template, you can set another value or leave it as it is.

📘

NOTE

You are able to edit the URL Suffix (Dynamic URL) in the request body when sending the message template to the recipient.

  • Quick Reply : Messages include up to 3 options —each option is a button. This type of message offers a quicker way for users to make a selection from a menu when interacting with a business. For example, we are going to add two buttons to the message content:

    Button text* = Yes, Button payload: agree
    Button text* = No, Button payload: NotAgree

    If the end user selects the button ‘Yes’, the platform will interpret it as ‘agree’ → agree (Yes).

    You set the value of the Button payloads to Keyword Senders (Auto-Reply, Opt-Out, Help Response, Join Response).

📘

NOTE

You are able to edit the Button payload in the request body when sending the message template to the recipient.

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

  • Create the Media Message Template from the Digital Engagement Platform, in the Templates section or through the Templates API.

  • Once you have created the media 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 media 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 via UI. Remember , once WhatsApp has approved your first 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 media message template via UI or API, in both cases our support team will provide you the namespace identifier (Id) of the Message Template ("templateNamespace") once the template has been approved.

For more information about creating a WhatsApp message template via Digital Engagement Platform go to the WhatsApp Templates section.

If you want to create the media message template via Templates API, you need to enter the following parameters to the request body:

HTTP Request: POST /whatsapp/templates

Before creating the media template, you need to provide the WhatsApp Business Account ID (WABA) or the unique identifier of the sender.

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": "TRANSACTIONAL",
  "templateLanguages": [
    {
      "language": "en_US",
      "components": [
        {
          "type": "HEADER",
          "format": "IMAGE",
          "example": {
            "header_handle": [
              "https://example.com?media=image.png"
            ]
          }
        },
        {
          "type": "BODY",
          "text": "Hi! your discount code is {{code}}",
          "example": {
            "body_text": [
              [
                "code"
              ]
            ]
          }
        },
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type": "URL",
              "text": "info",
              "url": "https://www.example.com/airplaneTickets"
            }
          ]
        }
      ]
    }
  ]
}

The parameters presented in the request body example when creating a Media Message Template are the following:

Parameter Required Description
name Yes

Name of the template created in your WhatsApp Business Account.
category Yes

Supported Template Categories.

  • "MARKETING": Send promotional offers, product announcements, and more to increase awareness and engagement.
  • "PASSWORDS": Send codes that allow your customers to securely access their accounts.
  • "TRANSACTIONAL": Send account updates, order updates, alerts, and more to share important information.
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: "en", "en_GB", "en_US"

Spanish: "es", "es_AR", "es_ES", "es_MX"

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

Components of the template.
templateLanguages.components.type No

Type of component of the message template you want to send.

There are three main template components:

  • "HEADER": Header content displayed on top of a message.
  • "BODY": Content of the message template.
  • "BUTTONS": There are two types of buttons displayed at the bottom of the template: Call to Action and Quick reply.

In this example, we set the Header, Body, and Buttons components in order. That is, we set the "HEADER" as the first component.

Each template component has its own structure to provide additional information.
templateLanguages.components.format Yes

The Header contains the media, which can be text, an image, video or pdf file and it is located at the top of the message. You can use headers to provide additional information to end users.

  • "TEXT": Should only contain text and emojis. A text header has a limit of 60 characters including emojis.
  • "IMAGE": Maximum image size is 5MB and the format must be .jpg or .png.
  • "VIDEO": Maximum video size is 5MB and the format must be .mp4, .3gpp (Only H.264 video codec and AAC audio codec are supported).
  • "DOCUMENT": Maximum document size is 5MB and the format must be .pdf

The URL of the header (image, video and document). Should be a valid URL that starts with "http://…" or "https://…" and provides a direct download. Redirects are not supported.

In this example we set an image header.
templateLanguages.components.example Yes

Required if the text header contains placeholders.

For media headers, set the URL of the header component (image, video, document).
templateLanguages.components.example.header_handle Yes

If you set a media header, enter the URL of the header (image, video and document). Should be a valid URL that starts with "http://…" or "https://…" and provides a direct download. Redirects are not supported.

In this example, we set the URL of an image.
templateLanguages.components.example.header_text Yes

If you set a text header, enter the content of the text header. Should only contain text and emojis. A text header has a limit of 60 characters including emojis.
templateLanguages.components.type Yes

Type of component of the message template you want to send.

There are three main template components:

  • "HEADER": Header content displayed on top of a message.
  • "BODY": Content of the message template.
  • "BUTTONS": There are two types of buttons displayed at the bottom of the template: Call to Action and Quick reply.

In this example, we set the Header, Body, and Buttons components in order. That is, we set the "BODY" as the second component.

Each template component has its own structure to provide additional information.
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 ({{...}}) when a message is sent.

Placeholders have to be correctly formatted and in the correct order, regardless of other sections. Example: {{1}}, {{2}}, {{3}}...
templateLanguages.components.type No

Type of component of the message template you want to send.

There are three main template components:

  • "HEADER": Header content displayed on top of a message.
  • "BODY": Content of the message template.
  • "BUTTONS": There are two types of buttons displayed at the bottom of the template: Call to Action and Quick reply.

In this example, we set the Header, Body, and Buttons components in order. That is, we set the "BUTTONS" as the third component.

Each template component has its own structure to provide additional information.
templateLanguages.components.buttons Yes

Template Buttons.
templateLanguages.components.buttons.type Yes

Button types.

For Call To Action buttons, format options include Phone Number, URL and Dynamic URL. You can have up to 2 distinct buttons. you can’t place 2 phone buttons or 2 URL buttons.

"URL": if the message template will be defined with a dynamic URL, set the URL suffix. The URL suffix is then propagated as an extension of the registered URL address. Nevertheless, If the registered message template has been defined with a phone number or Static URL, don't place it in the request body when sending the message template to end users because this object will be approved by WhatsApp.

"PHONE_NUMBER": Add a phone number button to your message. If the user selects the button, it will direct him to the phone call of the number you entered as value.

For Quick reply buttons, you can have up to 3 buttons.

QUICK_REPLY: If the message template will be defined with Quick Reply buttons, set the button payload for each one.

In this example, we set a dynamic URL Call to Action button, which creates a personalized link for each campaign you use the template on by adding a variable at the end of the link.
templateLanguages.components.buttons.text Yes

Template button text.

For Call To Action buttons, if you set "URL" as a dynamic website URL button, enter the URL suffix value. The suffix value you set here acts as a default, when you send this template, you can set another value or leave it as it is.

NOTE: You are able to edit the URL Suffix (Dynamic URL) in the request body when sending the message template to the recipient.

If you set "PHONE_NUMBER" as the phone number button, set the text to be displayed on the button.

For Quick Reply buttons, set the text to be displayed for each button.

In this example, we set the suffix value of a dynamic URL.
templateLanguages.components.buttons.url Yes

For Call To Action buttons, if you set "URL" as a dynamic or static website URL button, enter a valid URL that starts with "http://…" or "https://…" that will redirect the user to the website.
templateLanguages.components.buttons.phone_number Yes

For Call To Action buttons, if you set "PHONE_NUMBER" as the phone number button, enter a valid phone number that will redirect the user to the phone call.

When you create a Media Message Template, the response body contains the following data:

{
  "meta": {
    "timestamp": 1667537542614,
    "transactionId": "673bedd1-30e3-406e-907f-388384c8"
  },
    "data": {
     "wabaId": 107837261,
     "name": "code_shipping10",
     "category": "TRANSACTIONAL",
     "templateLanguages": [
      {
        "id": "84497985",
        "language": "en_US",
        "components": [
         {
            "type": "HEADER",
            "format": "IMAGE",
            "example": {
            "header_handle": [
              "https://example.com?media=image.png"
             ]
           }
          },
          {
            "type": "BODY",
            "text": "Hi! your discount code is {{code}}",
            "example": {
              "body_text": [
                [
                  "code"
                ]
              ]
            }
          },
          {
            "type": "BUTTONS",
            "buttons": [
              {
                "type": "URL",
                "text": "info",
                "url": "https://www.example.com/airplaneTickets"
              }
            ]
          }
        ]
      }
    ]
  }
}

Parameters presented in the response body example when creating the Media Message Template are the following:

Parameter Description
data

Data contained in the Media 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.
  • "PASSWORDS": Send codes that allow your customers to securely access their accounts.
  • "TRANSACTIONAL": Send account updates, order updates, alerts, and more to share important information.
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: "en", "en_GB", "en_US"

Spanish: "es", "es_AR", "es_ES", "es_MX"

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

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

Type of component of the message template you want to send.

There are three main template components:

  • "HEADER": Header content displayed on top of a message.
  • "BODY": Content of the message template.
  • "BUTTONS": There are two types of buttons displayed at the bottom of the template: Call to Action and Quick reply.

In this example, we set the Header, Body, and Buttons components in order. That is, we set the "HEADER" as the first component.

Each template component has its own structure to provide additional information.
data.templateLanguages.components.format

The Header contains the media, which can be text, an image, video or pdf file and it is located at the top of the message. You can use headers to provide additional information to end users.

  • "TEXT": Should only contain text and emojis. A text header has a limit of 60 characters including emojis.
  • "IMAGE": Maximum image size is 5MB and the format must be .jpg or .png.
  • "VIDEO": Maximum video size is 5MB and the format must be .mp4, .3gpp (Only H.264 video codec and AAC audio codec are supported).
  • "DOCUMENT": Maximum document size is 5MB and the format must be .pdf

The URL of the header (image, video and document). Should be a valid URL that starts with "http://…" or "https://…" and provides a direct download. Redirects are not supported.

In this example we set an image header.
data.templateLanguages.components.example

Required if the text header contains placeholders.

For media headers, set the URL of the header component (image, video, document).
data.templateLanguages.components.example.header_handle

If you set a media header, enter the URL of the header (image, video and document). Should be a valid URL that starts with "http://…" or "https://…" and provides a direct download. Redirects are not supported.

In this example, we set the URL of an image.
data.templateLanguages.components.example.header_text

If you set a text header, enter the content of the text header. Should only contain text and emojis. A text header has a limit of 60 characters including emojis.
data.templateLanguages.components.type

Type of component of the message template you want to send.

There are three main template components:

  • "HEADER": Header content displayed on top of a message.
  • "BODY": Content of the message template.
  • "BUTTONS": There are two types of buttons displayed at the bottom of the template: Call to Action and Quick reply.

In this example, we set the Header, Body, and Buttons components in order. That is, we set the "BODY" as the second component.

Each template component has its own structure to provide additional information.
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}}...
data.templateLanguages.components.type

Type of component of the message template you want to send.

There are three main template components:

  • "HEADER": Header content displayed on top of a message.
  • "BODY": Content of the message template.
  • "BUTTONS": There are two types of buttons displayed at the bottom of the template: Call to Action and Quick reply.

In this example, we set the Header, Body, and Buttons components in order. That is, we set the "BUTTONS" as the third component.

Each template component has its own structure to provide additional information.
data.templateLanguages.components.buttons

Template Buttons.
data.templateLanguages.components.buttons.type

Button types.

For Call To Action buttons, format options include Phone Number, URL and Dynamic URL. You can have up to 2 distinct buttons. you can’t place 2 phone buttons or 2 URL buttons.

"URL": if the message template will be defined with a dynamic URL, set the URL suffix. The URL suffix is then propagated as an extension of the registered URL address. Nevertheless, If the registered message template has been defined with a phone number or Static URL, don't place it in the request body when sending the message template to end users because this object will be approved by WhatsApp.

"PHONE_NUMBER": Add a phone number button to your message. If the user selects the button, it will direct him to the phone call of the number you entered as value.

For Quick reply buttons, you can have up to 3 buttons.

QUICK_REPLY: If the message template will be defined with Quick Reply buttons, set the button payload for each one.

In this example, we set a dynamic URL Call to Action button, which creates a personalized link for each campaign you use the template on by adding a variable at the end of the link.
data.templateLanguages.components.buttons.text

Template button text.

For Call To Action buttons, if you set "URL" as a dynamic website URL button, enter the URL suffix value. The suffix value you set here acts as a default, when you send this template, you can set another value or leave it as it is.

NOTE: You are able to edit the URL Suffix (Dynamic URL) in the request body when sending the message template to the recipient.

If you set "PHONE_NUMBER" as the phone number button, set the text to be displayed on the button.

For Quick Reply buttons, set the text to be displayed for each button.

In this example, we set the suffix value of a dynamic URL.
data.templateLanguages.components.buttons.url

For Call To Action buttons, if you set "URL" as a dynamic or static website URL button, enter a valid URL that starts with "http://…" or "https://…" that will redirect the user to the website.
data.templateLanguages.components.buttons.phone_number

For Call To Action buttons, if you set "PHONE_NUMBER" as the phone number button, enter a valid phone number that will redirect the user to the phone call.

Once the media 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 must carefully copy each value according to its corresponding parameter you set when creating the media template via UI (Digital Engagement Platform) or Templates API to the request body of the Messages API.

You are only able to set a value for a Multimedia Header (Image, Video or Document), a URL Suffix (Dynamic URL) for a Call To Action Button, or values for Button Payloads from Quick Reply Buttons in the request body. You can not edit Text Headers, phone numbers (Call to Action), Static URLs (Call to Action), the template content, among others in the request body because these values have been approved by WhatsApp.

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": "224477"
  },
  "templateHeader":{
    "type": "image",
    "url": "https://example.com?media=image.png"
  },
  "templateButtons": {
    "type": "cta",
    "values": [
      {
        "index": 0,
        "value": "info"
      }
    ]
  }
}

Parameters present in the request body example when sending a Media 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.
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 media 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.

Only templates created in your own namespace will work.
templateName Yes Name of the template created in your WhatsApp Business Account.
templateLanguage No

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: "en", "en_GB", "en_US"

Spanish: "es", "es_AR", "es_ES", "es_MX"

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}}...
templateHeader No Header content displayed on top of a message.
templateHeader.type Yes

Type of message template you want to send.

Header contains the following fields:

"image": Maximum image size is 5MB and the format must be .jpg or .png

"video": Maximum video size is 5MB and the format must be .mp4, .3gpp (Only H.264 video codec and AAC audio codec are supported).

"document": Maximum document size is 5MB and the format must be .pdf

NOTE: If the registered message template has been defined with a text header, don't place it in the request body because this object has been approved by WhatsApp.
templateHeader.url Yes URL of the header (image, video and document). Should be a valid URL that starts with "http://…" or "https://…" and provides a direct download. Redirects are not supported.
templateButtons No Template Buttons.
templateButtons.type Yes

Button type:

"cta": Call To Action buttons.

Call to action buttons must be unique in type.

"quick-reply": Quick reply buttons.
templateButtons.values Yes Template button values.
templateButtons.values.index Yes

Position index of the button.

For Call To Action buttons, you can have up to 2 distinct buttons using index values of 0-1.

For Quick Reply buttons, you can have up to 3 buttons using index values of 0-2.
templateButtons.values.value Yes

For Call To Action buttons, if the registered message template has been defined with a dynamic URL, set the URL suffix. The URL suffix is then propagated as an extension of the registered URL address. Nevertheless, If the registered message template has been defined with a phone number or Static URL, don't place it in the request body because this object has been approved by WhatsApp.

If the registered message template has been defined with Quick Reply buttons, set the button payload for each one.

When you send a Media 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 present in the response body example when sending the MediaTemplate Message 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.
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.

The following examples will help you notice the difference between call to action and quick reply buttons in the request body when sending a message template:

Call To Action Example

First step is creating the Media Message Template from the Digital Engagement Platform, in the Templates section.

In this example, we will add a multimedia header image, a text message with one placeholder and two distinct call to action buttons, along with the requirement parameters.

833

After you have completed the WhatsApp Template content, click Save. Your template will now be sent for review.

The status of your template is visible under Message Templates as Pending. If your template is approved or rejected 48 hours after being submitted, the Template Status will change to either one of those states in the Templates section of the platform.

318

Second step, after the 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 exactly how you registered the template for approval. Remember , once WhatsApp has approved your first message template, our support team will provide you a namespace identifier (Id) of the Message Templates in your account. "templateNamespace".

{
  "from": "1000000001",
  "to": "+1000000002",
  "body": "Check the status of your flight {{name}}",
  "templateNamespace": "31291098",
  "templateName": "Flight Ticket",
  "templateLanguage": "en_US",
  "placeholders": {
    "name": "Elizabeth"
  },
  "templateHeader":{
    "type": "image",
    "url": "https://example.com?media=Airplane.png"
  },
  "templateButtons": {
    "type": "cta",
    "values": [
      {
        "index": 1,
        "value": "information"
      }
    ]
  }
}

For Call To Action buttons, the registered message template has been defined with a dynamic URL so we can edit the value of the URL suffix. If you notice, the index is in position 1, this is because in the registered template, the dynamic URL is located in the second position.

733

Remember, If the registered message template has been defined with a phone number or URL, don't place it in the request body because this object has been sent and approved by WhatsApp.

Once the message has been sent via API and received by the recipient successfully , the message will look like this:

324

Quick Reply Example

First step is creating the Media Message Template from the Digital Engagement Platform, in the Templates section.

In this example, we will add a multimedia header image, a text message with two placeholders and quick reply buttons,along the requirement parameters.

834

After you have completed the WhatsApp Template content, click Save. Your template will now be sent for review.

The status of your template is visible under Message Templates as Pending. If your template is approved or rejected 48 hours after being submitted, the Template Status will change to either one of those states in the Templates section of the platform.

352

Second step, after the 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 exactly how you registered the template for approval. Remember , once WhatsApp has approved your first message template, our support team will provide you a namespace identifier (Id) of the Message Templates in your account. "templateNamespace".

{
  "from": "1000000001",
  "to": "+1000000002",
  "body": "Dear {{name}} {{last name}}, we wish to  confirm your home delivery on Saturday at 8:00 am.",
  "templateNamespace": "31291098",
  "templateName": "Confirm Delivery",
  "templateLanguage": "en_US",
  "placeholders": {
    "name": "Zoe",
    "last name": "Smith",
  },
  "templateHeader":{
    "type": "image",
    "url": "https://example.com?media=eliPackage.png"
  },
  "templateButtons": {
    "type": "quick-reply",
    "values": [
      {
        "index": 0,
        "value": "Agree"
      },
      {
        "index": 1,
        "value": "NotAgree"
      }
    ]
  }
}

Registered message template has been defined with two Quick Reply buttons so we can edit the value of the Button Payload.

979

Once the message has been sent via API and received by the recipient successfully , the message will look like this:

345

Creating a Regular Message

If a WhatsApp user has sent your application a message — whether it’s a reply to one of your outbound messages, or they have initiated communication themselves — your application has a 24-hour window to send that user any messages, without using a template. These are known as conversational messages.

If your application sends a message to a WhatsApp user outside a 24-hour session, the message must use an approved template as described in the previous section.

You can add media as attachments to conversational messages. Supported content types and sizes:

MediaContent TypePost-Processing Media Size
documentdocument/pdf5 MB
imageimage/jpeg
image/png		5 MB
audioaudio/aac
audio/mp4
audio/amr
audio/mpeg
audio/ogg; codecs=opus

Note: The base audio/pgg type is not supported.		5 MB
videovideo/mp4
video/3gpp

Note: Only H.264 video codec and AAC audio codec are supported.		5 MB

When you send a Regular Message, the request body contains the following data:

HTTP Request : POST /whatsapp/messages 

{
  "from": "1000000001",
  "to": "+1000000002",
  "body": "Thank you for contacting the support team, we will assist you as soon as possible.",
  "mediaLinks": [
    "https://example.com?media=image.png"
  ]
}

Parameters presented in the request body example when sending the Regular 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.
to Yes Determines the destination phone number for your regular message. Numbers are specified in E.164 format → (‘+’ and a country code).
body Yes The content of the regular message that will be sent to the end user.
mediaLinks No

URL of a media file to be sent as an attachment.

There are four types of media compatible with the API:

  • Document (.pdf)
  • Image (.jpeg, .png)
  • Audio (.acc, .mp4, .amr, .mpeg, .ogg; codecs=opus)
  • Video (.mp4, .3gpp) Only H.264 video codec and AAC audio codec are supported)

When you send a Regular Message, the response body contains the following data:

{
  "meta": {
    "timestamp": 1645414827658,
    "transactionId": "830b1b35-1db0-414b-a687-2bd9c627d144"
  },
  "data": {
    "id": "621309ab65a0ac43",
    "body": "Thank you for contacting the support team, we will assist you as soon as possible.",
    "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 the 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 message.
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.
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.

  • "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 over 1 year ago