Creating & Sending WhatsApp Media Message Template

Suggest Edits

Media message templates expand the content you can send recipients beyond the standard message template type to include these components: 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.

When creating a media message template, you must select which components that you would like to include. It is important to note that you cannot add a new component to an existing template. You must create a new template — with a new template name — if you wish to incorporate a new component into a template.

Media Message Templates contain 4 main components:

  • Header (Text & Media -> Optional)

  • Text Message (body -> Required)

  • Footer (Text -> Optional)

  • Buttons (Call to Action & Quick Reply -> Optional)

Header : Add a title or choose which type of media you'll use for this 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, personalized fields (placeholders), 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

The following media template examples will help you to understand each media that contains the header (text with placeholders, image, video, component) in JSON format. That is, this diagram shows each parameter in which the header is composed and how it will be displayed by the user.

1051

📘

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 even though the media template has been approved.

Text Message: Enter the text for your message in the language you've selected. 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.

The following media template example will help you to understand the location of the Text Message with a personalized field (placeholder) in JSON format. That is, this diagram shows each parameter in which the text message is composed and how it will be displayed by the user.

1252

Footer: Add a short line of text to the bottom of your message template. When creating a message template, you may include a footer at the end of the message. A footer may only contain text. No personalized fields (placeholders) or emojis are allowed. A footer has a limit of 60 characters.

1349

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.

The following media template examples will help you to understand the location of the Call To Action buttons and each format option that it contains (Phone number, Static URL, Dynamic URL) in JSON format. That is, this diagram shows each parameter in which the Call To Action button is composed and how it will be displayed by the user.

1062

📘

NOTE

You are able to edit the URL Suffix (Dynamic URL) in the request body when sending the message template to the recipient even though the media template has been approved.

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

The following media template example will help you to understand the location of the Quick Reply buttons and each option that it contains (Up to 3 option buttons) in JSON format. That is, this diagram shows each parameter in which the Call To Action button is composed and how it will be displayed by the user.

1025

📘

NOTE

You are able to edit the Button payload in the request body when sending the message template to the recipient even though the media template has been approved.

Therefore, the following media template examples will help you to understand the location of the header, text message, footer, buttons, parameters in JSON format for each one according to the template type. That is, this diagram shows each parameter in which the media template is composed and how it will be displayed by the user.

The next Media Message Template example includes only a Header, Text Message, Footer, and Call To Action Buttons with a Dynamic URL:

2103

📘

NOTE

Remember, you need to include in the request body when creating the media message template, the name, category, language of the template. and components you desire to include (header, text message or buttons).

At last, the next table summarizes each component you can include in the media message template and their different types of options.

Main ComponentsOptionsRequired
HeaderText: Contains text, personalized fields (placeholders), and emojis.

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

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

Document: It must be less than 5MB and the format .pdf.		No
Text MessageContains text, personalized fields (placeholders), and emojis.Yes
FooterContains only text.No
ButtonsCall To Action: Up to two (2) distinct buttons (format options) are allowed.

Format Options:

- Phone Number
- Static URL
- Dynamic URL

Quick Reply: Up to three (3) distinct buttons are allowed.		No

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

Create Media Message Template

If you want to create the media 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.

The following media message template example includes a header, text body and call to action button with a Dynamic URL.

{
  "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": [
              [
                "34871"
              ]
            ]
          }
        },
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type": "URL",
              "text": "Click Here!",
              "url": "https://www.example.com/{{ticketAirplane}}",
              "example": [
                 "https://www.example.com/ertyhgf456"
              ]
            }
          ]
        }
      ]
    }
  ]
}

In your POST call, include the following message template parameters to create a media message template:

  • Main Parameters
Parameter Required Description
name Yes

Name of the template created in your WhatsApp Business Account.

The name of each template you create cannot be the same.
category Yes

Type of message template.

Supported Template Categories.

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

Array of languages objects containing the language that template may be rendered in and the components.
templateLanguages.language Yes

Language of the message template.

Currently the API supports 3 Languages: English, Spanish and Portuguese. Required if you want to send templates in languages other than en_US.

English: "en", "en_GB", "en_US"

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

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

The parts of the message template.

Array of components objects containing the different types of options you can include in the message.
  • Components Parameter
Parameter Required Description
templateLanguages.components.
type		 Yes

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

There are four optional main template components you can include in the template:

  • "HEADER": Header content displayed on top of a message.
  • "BODY": Content of the message template.
  • "FOOTER": Short line of text to the bottom of your message.
  • "BUTTONS": There are two types of buttons displayed at the bottom of the template: Call to Action and Quick reply.
templateLanguages.components.
format		 No

Only applies to the "HEADER" type.

Header content displayed on top of a message.

The header object contains the following options:

  • "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) must be a valid URL that starts with "http://…" or "https://…" and provides a direct download. Redirects are not supported.
templateLanguages.components.
text		 No

Only applies to the "HEADER" type, "TEXT" type, "BODY" type and "FOOTER" type.

if you set the Header type, enter the text message header to be sent. Only contain text, personalized fields (placeholders), and emojis. A text header has a limit of 60 characters including emojis.

if you set the Body type, enter the text message body to be sent. Only contain text, personalized fields (placeholders), and emojis. A text body has a limit of 1024 characters including emojis.

if you set the Footer type, enter the text message footer to be sent. Only contain text and no personalized fields (placeholders). A text footer has a limit of 60 characters.
templateLanguages.components.
example		 No

Only applies to the "HEADER" type and "BODY" type.

Provides an example of possible data for your template. This helps Meta during the review and approval process, so they can understand what kind of message you plan to send. Make sure these are examples and do not include any confidential or personal information.

if you set the Header type, it is required when the header contains placeholders or media links (image, video, document).

if you set the Body type, it is required when the text message body contains placeholders.
templateLanguages.components.
example.header_text		 No

Only applies to the "HEADER" type.

if you set the Text as Header option, it is required when the text header contains placeholders.

Array of personalized fields (placeholders) containing the text message header.
templateLanguages.components.
example.header_handle		 No

Only applies to the "HEADER" type.

if you set the Video, Image or Document as Header option, enter the URL of the chosen media.

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

Only applies to the "BODY" type.

Array of personalized fields (placeholders) containing the text message body.
  • Buttons Component Type: Inside the components object, you can set type to button. These are the button parameters.
<
Parameter Required Description
templateLanguages.components.
type		 Yes

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

  • "BUTTONS": There are two types of buttons displayed at the bottom of the template: Call to Action and Quick reply.
templateLanguages.components.
buttons		 Yes

Array of Buttons type options you can include to the template.
templateLanguages.components.
buttons.type		 Yes

Buttons Type options.

The Call To Action buttons object contains the following options:

  • "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.
  • "URL": The URL that the user is sent to after the button is clicked. Variables can be used to create dynamic links.

You can have up to 2 distinct call to action buttons. That is, you can’t set 2 phone buttons or 2 URL buttons to the template.

The Quick Reply buttons object contains the following option:

  • "QUICK_REPLY": Set the button payload for each one.

You can have up to 3 quick reply buttons.
templateLanguages.components.
buttons.text		 Yes

Text to be displayed on the button.

Regardless of the button type option you choose from Call To Action ( "PHONE_NUMBER" , "URL") or "QUICK_REPLY", set the text button to be displayed on the button.
templateLanguages.components.
buttons.phone_number		 No

Only applies to the Call To Action "PHONE_NUMBER" option.

Phone number that is called on clicking the button.

if you set "PHONE_NUMBER" as the phone number button, enter a valid phone number that will redirect the user to the phone call.
templateLanguages.components.
buttons.url		 No

Only applies to the Call To Action "URL" option.

If you set "URL" as a static or dynamic website URL button, enter a valid URL that starts with "http://…" or "https://…" that will redirect the user to the website.

If the message template is 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.

For the dynamic website URL button, enter a forward slash at the end of the link → "https://www.google.com/". At least, enter the URL suffix (dynamic content of the url) as placeholder inside double curly braces ({{...}}).

For example: "https://www.google.com/{{survery_url}}"
templateLanguages.components.
buttons.example		 No

Only applies to the Call To Action "URL" option if you set a dynamic URL.

Provides an example of possible data for your template. This helps Meta during the review and approval process, so they can understand what kind of message you plan to send. Make sure these are examples and do not include any confidential or personal information.

If you set "URL" as a dynamic website URL button, enter the static URL, plus the forward slash and the URL suffix value (dynamic content of the url -> placeholder).

For example: "https://www.google.com/45yuhgfhj"

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_shipping",
     "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": [
                [
                  "34871"
                ]
              ]
            }
          },
          {
            "type": "BUTTONS",
            "buttons": [
              {
                "type": "URL",
                "text": "Click Here!",
                "url": "https://www.example.com/{{ticketAirplane}}",
                     "example": [
                 "https://www.example.com/ertyhgf456"
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Regardless of the types of objects you chose to customize the media template, the response body provides you with the WhatsApp Business Account ID (WABA) ("wabaId") and the template id ("id"), which will allow you to obtain information, edit or delete from a specific template, and list templates.

Send Media Message Template

There are new changes when you send a media message template to the recipients. So we divide this section in two parts:

New Changes

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.

📘

NOTE

Remember , once WhatsApp has approved your message template, our support team will provide you a namespace identifier (Id) of the Message Template in your account →"templateNamespace". Or you can query the value of the "templateNamespace" parameter through the following method: Getting Sender.

When you created the media 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 as Text Headers that do not include personalized fields (placeholders), phone numbers (Call to Action), Static URLs (Call to Action), among others in the request body because the values of each parameter have been approved by WhatsApp.

You are only able to edit a value for a Multimedia Header (Image, Video or Document), a URL Suffix (placeholder) of Dynamic URL for a Call To Action Button, or Button Payloads values from Quick Reply Buttons in the request body, and placeholders that includes the text message body.

In this new version (v2), it is not necessary to 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.

There are two new ways to send a media message template to your recipients:

  • Including only the unique identifier of the media 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 media message template once the template has been created.
{
  "templateName": "code_shipping",
  "templateLanguage": "en_US",
  "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_US",
"from": "1000000001",
"to": "+1000000002"
}

If the template created includes a header with a media object (image, video, document), you need to include it in the request body in case you want to edit the value of the media object.

If the template created includes personalized fields (placeholders) in the header (text type), text message body, or buttons (call to action → Dynamic URL) , 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.

We are going to send the media message template example we created earlier that includes a header, text body and call to action button with a Dynamic URL by entering the following parameters to the request body:

{
  "templateId": "84497985",
  "from": "1000000001",
  "to": "+1000000002",
  "templateHeader": {
    "type": "image",
    "url": "https://example.com?media=imageEdited123.png"
  },
  "globalPlaceholders": {
    "code": "34871",
    "ticketAirplane": "ertyhgf456"
  }
}

If you notice, you don't have to type the text header (only type it if you want to edit the image, video or document in case you have set one of these when creating the template), footer, text message body and buttons (call to action or quick reply) when sending the template like the previous version (v1).

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

English: "en", "en_GB", "en_US"

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

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

Only applies if the template created contains the "HEADER" type with an URL based on the chosen media header (image, video, document) and desire to edit the url of each media header option.

Array of URL containing the header type chosen when creating the template.
templateHeader.type Yes

Only applies if the template created contains the "HEADER" type.

Enter the media header type chosen when creating the template in lower case: "image", "video", "document".
templateHeader.url Yes

Only applies if the template created contains the "IMAGE", "VIDEO" or "DOCUMENT" header option.

if you set the Video, Image or Document as Header option when creating the template, enter the URL of the chosen media to edit it.

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

Required if the text header, text message body or Call To Action button (Dynamic URL) contains placeholders.

Array that contains placeholders.

Enter the value of each placeholder parameter configured in the text header, text message body or dynamic URL from call to action button 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 Media Message Template, the response body contains the following data:

{
  "meta": {
    "timestamp": 1675867435696,
    "transactionId": "0b9-c8d4-44-39-a93b87"
  },
  "data": {
    "id": "63e3b52078b655",
    "body": "Hi! your discount code is {{code}}",
    "from": "1000000001",
    "to": "+1000000002",
    "date": "2023-02-08T14:43:55.689967263Z",
    "statusDate": "2023-02-08T14:43:55.689921048Z",
    "externalId": null,
    "owner": "[email protected]",
    "operator": "[email protected]",
    "status": "QUEUED",
    "providerId": "fghj12345"
  }
}

Parameters presented in the response body example when sending a Media 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.

Original Send

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.

📘

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 media 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 media template via UI (Digital Engagement Platform) or Templates API to the request body of the Messages API.

You can not edit the template content as Text Headers that do not include personalized fields (placeholders), phone numbers (Call to Action), Static URLs (Call to Action), among others in the request body because these values have been approved by WhatsApp.

You are only able to edit a value for a Multimedia Header (Image, Video or Document), a URL Suffix (placeholder) of Dynamic URL for a Call To Action Button, or Button Payloads values from Quick Reply Buttons in the request body, and placeholders that includes the text message body.

HTTP Request : POST /whatsapp/messages

We are going to send the media message template example we created earlier that includes a header, text body and call to action button with a Dynamic URL by entering the following parameters to the request body:

{
  "from": "1000000001",
  "to": "+1000000002",
  "body": "Hi! your discount code is {{code}}",
  "templateNamespace": "31291098",
  "templateName": "code_shipping",
  "templateLanguage": "en_US",
  "placeholders": {
    "code": "34871"
  },
  "templateHeader":{
    "type": "image",
    "url": "https://example.com?media=image.png"
  },
  "templateButtons": {
    "type": "cta",
    "values": [
      {
        "index": 0,
        "value": "ertyhgf456"
      }
    ]
  }
}

In your POST call, include the following message template parameters to send a media message template:

  • Main Parameters
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

Copy the text message body configured when creating the template to be sent.
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

Copy the language configured when creating the template to be sent.
placeholders No

Only applies if the "BODY" type contains personalized fields (placeholders).

Array of personalized fields (placeholders) containing the text message body.

Set as parameter the placeholder you configured that is inside double curly braces ({{...}}) when creating the template. Then set the value of the placeholder parameter.

For example: "code": "34871"

Placeholders have to be correctly formatted in order of how the template was defined.
  • Components Parameter: You are only able to edit the header options (text, image, video, document) like placeholders and link despite template creation being approved when sending the media message template.
Parameter Required Description
templateHeader No

Only applies if the template created contains the "HEADER" type with personalized fields (placeholders) or an URL based on the chosen media header (image, video, document).

Array of personalized fields (placeholders) or URL containing the header type chosen when creating the template.
templateHeader.type Yes

Only applies if the template created contains the "HEADER" type.

Enter the header type chosen when creating the template in lower case: "text" (type it if the text header contains placeholders), "image", "video", "document".
templateHeader.type.text No

Only applies if the template created contains the "TEXT" header option and includes personalized fields (placeholders).

Enter the personalized fields (placeholders) in order of how they were defined.
templateHeader.type.url No

Only applies if the template created contains the "IMAGE", "VIDEO" or "DOCUMENT" header option.

if you set the Video, Image or Document as Header option when creating the template, enter the URL of the chosen media.

The URL of the header (image, video and document) must be a valid URL that starts with "http://…" or "https://…" and provides a direct download. Redirects are not supported.
  • Buttons Component Type: You are only able to edit the dynamic URL from the Call To Action button and the payload from the Quick Reply Buttons despite template creation being approved when sending the media message template.
Parameter Required Description
templateButtons No

Only applies if the template created contains the "BUTTONS" type with a Dynamic URL or Quick Reply buttons.

if you set the Call To Action as Button type, it is required when the button contains a Dynamic URL.

if you set the Quick Reply as Button type, it is required when the button contains a payload.

Array that contains the URL Suffix (placeholder) of Dynamic URL for a Call To Action Button, or Payloads values from Quick Reply Buttons containing the button type chosen when creating the template.
templateButtons.type Yes

Only applies if the template created contains the "BUTTONS" type with a Dynamic URL or Quick Reply buttons.

Enter the button type chosen when creating the template:

  • "cta": call to action button.
  • "quick-reply": quick reply button.
templateButtons.values No

Only applies if the template created contains the "BUTTONS" type with a Dynamic URL or Quick Reply buttons.

Array that contains the Template button values.
templateButtons.values.index No

Only applies if the template created contains the "BUTTONS" type with a Dynamic URL or Quick Reply buttons.

Position index of the button of how it was defined when creating the template.

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

For example, if you set "PHONE_NUMBER" as the phone number button in the first position and the Dynamic URL in the second position. Therefore, the position index of the dynamic URL is 1.

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

Only applies if the template created contains the "BUTTONS" type with a Dynamic URL or Quick Reply buttons.

For Call To Action buttons, if the created template has been defined with a dynamic URL, enter the URL suffix (placeholder). The URL suffix is then propagated as an extension of the registered URL address.

If the created template has been defined with Quick Reply buttons, enter the button payload for each one. The Payload is data you are interested in transporting to the server when you make an API request.

Updated about 2 months ago