The WhatsApp Media Message Template is a more advanced message template type that supports rich formatting and interactive elements. These templates allow you to combine multiple components—such as headers, body text, and buttons—to deliver highly engaging and personalized customer experiences.

Media message templates are pre-approved by WhatsApp and must be created either through the Communications Platform or via the WhatsApp Business API. Once approved, they can be used through the SFTP integration by uploading JSON files that reference the message template name, language, and associated placeholders.

By uploading JSON files referencing a valid Media Message Template, organizations can automate the delivery of rich WhatsApp notifications, alerts, and events without direct interaction with the API or the platform. The SFTP service automatically validates the uploaded JSON against the approved message template structure, replacing placeholders with dynamic values provided for each recipient and rendering the configured media components (header, body, and buttons).

Key features of Media Message Templates

1. Rich Message Template Structure
   • Includes multiple components included in the message template, such as header, body, footer, and interactive buttons (Call to Action, Quick Reply).
   • The header may contain text with placeholders, or media (image, video, or document).
   • The message body delivers the main text content, which can include placeholders for personalization.
   • The buttons section allows interactivity through Call to Action (CTA) or Quick Reply options.
2. Pre-approval Required
   • Message Templates must be created and approved in the Communications Platform or via the WhatsApp Business API before use.
   • The JSON must reference the message template by its exact "templateName" and "templateLanguage".
   • You can not edit the message template content in the request body because WhatsApp has approved the values of each parameter. You are only able to edit the value for placeholders (e.g., in the header, body, or button fields).
3. Dynamic Personalization
   • Placeholders in the header, body, or button labels can be dynamically replaced with recipient-specific values.
   • A single approved media message template can therefore be reused across thousands of recipients with personalized content.
   • The personalized fields (placeholders) you set when creating the WhatsApp Media Message Template for each component are editable when you send the message template.
   • Make sure these are examples and do not include any confidential or personal information.
   • Once the message template is approved and ready to be sent, replace the placeholders included in the message template with the actual (real) placeholder values.
4. High-volume Automation
   • Media message templates are particularly suited for enterprises running messages, such as promotional offers, appointment confirmations, or customer service flows.
   • With support for multimedia headers and interactive buttons, these message templates allow brands to deliver richer experiences than text-only formats.
   • By leveraging SFTP, organizations can integrate WhatsApp media messaging seamlessly into existing workflows and automate delivery at scale.

Before sending a WhatsApp Message Template, it is essential to understand how to include placeholders in the payload when the message template is created, which contains personalized fields in the Header or Text Message components. Furthermore, if the message template included a Buttons component with a dynamic URL (call-to-action) or quick reply buttons (or both), it is important to know how to add each button to the payload based on its respective position index to send the message template properly to recipients when initiating the API call.

Personalized Fields (placeholders)

This section will guide you on how to include the placeholders in the request body for sending the WhatsApp media message template that you set up during the message template creation.

Header

Text header

If the created message template includes a “Header” component of text type with a placeholder, the example payload JSON will be as follows:

"templateHeader": {  
    "type": "text",  
    "text": "{{code}}"  
}

📘

Text Header Placeholder Limit

The Text Header is allowed to include only a single personalized field (placeholder).

The "templateHeader.text" parameter includes the name of the placeholder.

Then, from the "placeholders" object, enter the placeholder you configured that is inside double curly braces {{PlaceholderName}}, defined in the "templateHeader.text".

{
   "placeholders": [
      "code"
   ]
}

If the header contains only text and no placeholders or media, the "templateHeader" parameter will not be included in the request body when sending the message template.

Media header

If the created message template includes a “Header” component of media type (image, video, document), the example payload JSON will be as follows:

"templateHeader":{
    "type": "image",
    "fileName": "winterpromotion.png",
    "url": "https://campaignpromotion_01.png"
}

The "templateHeader.type" parameter includes the header type chosen when creating the message template in lower case: "image", "video", or "document". The "fileName" parameter indicates the name and extension of the media file chosen, while the "url" parameter must contain the public HTTPS link where the media file is hosted.

If the header contains only text and no placeholders or media, the "templateHeader" parameter will not be included in the request body when sending the message template.

The next table summarizes each component you can include in the media header and its different options.

Text Message Body

If the created message template includes the message body with placeholder(s) in the request body, the example payload JSON will be as follows:

{
  "message": "{{discount}} {{date}}",
  "placeholders": [
    "discount",
    "date"
  ]
}

The "message" parameter defines the message body of the message template and must include only the placeholders enclosed in double curly braces {{PlaceholderName}}, exactly as they were defined in the message template creation process and in the same order.

Then, from the "placeholders" object, enter the placeholder(s) you configured that are inside double curly braces {{PlaceholderName}}, defined in the "message" parameter in the same order.

If the message body does not contain placeholders, the "message" parameter must not be included in the request body.

Position Index (Buttons)

In this section, we are going to learn how to include dynamic URLs in the payload if the message template created contains call-to-action buttons that include dynamic URLs. Currently, message templates support adding up to two dynamic URLs for call-to-action buttons.

Remember, dynamic URLs in WhatsApp message templates allow for the inclusion of personalized links in call-to-action buttons, making it possible to provide unique URLs for each recipient. These dynamic URLs are defined using placeholders (URL suffix), which are replaced with actual values (URL suffix value) when sending the message template.

Creating the Message Template

When creating a message template with a call-to-action button containing a dynamic URL, you specify a placeholder that is inside double curly braces {{...}} (URL suffix) in the "url" parameter of the button. Here’s an example of how the payload might look during message template creation that includes two dynamic URLs for call-to-action buttons.

{
   "type":"BUTTONS",
   "buttons": [
          {
            "type":"URL",
            "text":"New Offer",
            "url":"https://www.elipackagedomain.com/{{offer}}",
            "example": [
               "https://www.elipackagedomain.com/user-71421"
              ]
          },
          {
            "type":"URL",
            "text":"New Offer",
            "url":"https://www.elipackagedomain.com/{{shoes}}",
            "example": [
               "https://www.elipackagedomain.com/141518"
              ]
          }
     ]
}    

In this payload:

• "url": Includes two URL suffix ({{offer}}) , {{shoes}} for the dynamic portion of both URLs.
• "example": Provides a sample URL demonstrating how the URL suffix will be replaced.

From the payload above, we can notice that,

• The Call To Action button with the dynamic URL {{offer}} is in the first position (0).
• The Call To Action button with the dynamic URL {{shoes}} is in the second position (1).

Furthermore, when sending the message template, it’s important to maintain this order (position index) for each button.

Sending the Message Template

When sending the message template, each dynamic URL suffix {{offer}} , {{shoes}} must be replaced with an actual value (URL suffix value) in the payload.

{
   "templateButtons": [
       {
           "type": "cta",
           "values": [
               {
                   "index": 0,
                   "value": "{{offer}}"
               },
               {
                   "index": 1,
                   "value": "{{shoes}}"
               }
           ]
       }
   ],
   "placeholders": [
    "offer",
    "shoes"
  ],
   "data": [
       {
           "to": "+525500000000",
           "placeholders": {
               "offer": "new-promo-141518",
               "shoes": "2028-tennis-07"
           }
       }
   ]
}

In this payload:

• "templateButtons.values.index": indicates the position index of the button of how it was defined when creating the message template (0, 1, 2, 3, ...).

• "placeholders": Lists all the placeholder names ({{placeholderName}}) defined in the approved WhatsApp message template across its components --> header, body, and buttons (URL suffix).

  This array ensures that the system knows which variables need to be dynamically replaced when the message template is sent. The order of the placeholders in this array must match the order in which they were defined when creating the message template.

  For each recipient, the corresponding values for these placeholders are provided in the "data.placeholders" object. When the message template is processed, the system automatically replaces the placeholders (e.g., {{offer}}, {{shoes}}) with the real values you supply, ensuring personalized delivery for every user.

• "data.placeholders": Set the URL suffix value for each URL suffix ({{offer}} , {{shoes}}) that will receive each recipient. Remember, the URL suffix is then propagated as an extension of the registered URL address you set when creating the message template.

  It is a key-value object (URL suffix value) that provides the real values for each dynamic placeholder (URL suffix) defined in the message template ({{offer}} , {{shoes}}). When the message template is sent, these values automatically replace the placeholders in the dynamic URLs, ensuring that each recipient receives the personalized URL you specified.

🚧

Media Message Template Placeholders Editable

The personalized fields (placeholders) you set when creating the WhatsApp Media Message Template for each component are editable when you send the template.

Remember, when creating a WhatsApp Media Message Template only provide example placeholder values for each component if the message template includes placeholders. 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.

Once the message template is approved and ready to be sent, replace the placeholders with the actual (real) placeholder values.

Quick Reply buttons do not need to be included in the request body when sending a message template. They are automatically displayed as part of the message template configuration. The only buttons that require explicit definition in the payload are call-to-action (CTA) buttons with dynamic URLs, where you must specify their position index.

The Footer does not need to be included in the request body when sending a message template.

Sending WhatsApp Media Message Template

We are going to send a media message template example that includes a header (Image format), a text body with a personalized field (placeholder), and two call-to-action buttons with a Dynamic URL, by entering the following parameters in the request body:

{
  "campaignName": "Appointment Reminder",
  "from": "580000000000",
  "template": {
    "templateName": "appointment_reminder",
    "templateLanguage": "en",
    "templateHeader":{
      "type": "image",
      "fileName": "winterpromotion.png",
      "url": "https://cdn.example.com/images/winterpromotion.png"
    }
  },
  "message": "{{name}}, {{time}}",
  "placeholders": [
    "name",
    "time",
    "offer"
  ],
  "templateButtons": [
         {
             "type": "cta",
             "values": [
                 {
                     "index": 0,
                     "value": "{{offer}}"
                 }
             ]
         }
     ],
  "data": [
    {
      "to": "+581111111111",
      "placeholders": {
        "name":  "Jorge",
        "time":  "10:00 AM",
        "offer": "ertyhgf456"
      }
    }
  ]
}

📘

Editable Parameters

You are only able to edit the value for a Multimedia Header (Image, Video or Document), a URL Suffix (placeholder) of Dynamic URL for a Call To Action Button, and placeholders that includes the text message body when sending the message template.

The parameters of the request body are divided into three (3) main sections to send a media message template:

• Main parameters: Outline the essential parameters required to initiate a WhatsApp Media Message Template message over SFTP. These parameters define the broadcast name and identify the sender’s WhatsApp Business Number. They are fundamental to associating the message with the correct account and ensuring that it originates from an authorized number.\
  
• Message Template Components parameters: Describe the elements that define and customize the approved WhatsApp Media Message Template. This section includes referencing the message template by its exact name and language, configuring the header (which may consist of text with placeholders or media files such as images, videos, or documents). The "message" parameter must include only the placeholders explicitly defined in the template’s message body, while the "placeholders" parameter must include all the placeholders defined across the message template—whether they are located in the header, the message body, or dynamic URL (URL suffix) buttons. All placeholders must be declared in the exact order in which they were originally configured during message template creation. These parameters ensure strict alignment with the approved message template structure while enabling accurate and dynamic personalization for each recipient.\
  
• Buttons Component parameters: Detail the configuration of interactive buttons included in the message template. This section specifically covers Call to Action (CTA) buttons with dynamic URLs. Each CTA button must specify its type, assign a placeholder (URL suffix) for the dynamic URL, and reference its position index exactly as defined during message template creation (0, 1, 2, etc.). These parameters ensure that the CTA buttons are rendered correctly and that each recipient receives a personalized, functional URL embedded within the button.\
  
• Recipients & Personalization Data parameters: Define the list of recipients and their specific personalization details. Each recipient entry includes a destination phone number in E.164 format and the set of placeholder values that will dynamically replace placeholders in the header, body, or buttons (URL suffix value). These parameters ensure that every recipient receives a tailored version of the message template with accurate, individualized content.

Main parameters

Message Template Components parameters

Buttons Component parameters

You are only able to edit if the created message template includes a “Buttons” component with a dynamic URL (call to action type button).

Recipients & Personalization Data parameters