The WhatsApp Media Message Template is a more advanced 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 templates are pre-approved by WhatsApp and must be created either through the Digital Engagement Platform or via the WhatsApp Business API. Once approved, they can be used through the SFTP integration by uploading JSON files that reference the 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 campaigns without direct interaction with the API or the platform. The SFTP service automatically validates the uploaded JSON against the approved 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 Template Structure
   • Includes multiple components included in the 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
   • Templates must be created and approved in the Digital Engagement Platform or via the WhatsApp Business API before use.
   • The JSON must reference the template by its exact "templateName" and "templateLanguage".
   • You can not edit the 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 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 template.
   • Make sure these are examples and do not include any confidential or personal information.
   • Once the template is approved and ready to be sent, replace the placeholders included in the template with the actual (real) placeholder values.
4. High-volume Automation
   • Media templates are particularly suited for enterprises running interactive campaigns, such as promotional offers, appointment confirmations, or customer service flows.
   • With support for multimedia headers and interactive buttons, these 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 Template, it is essential to understand how to include placeholders in the payload when the template is created, which contains personalized fields in the Header or Text Message components. Furthermore, if the 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 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 template that you set up during the template creation.

Header

Text header

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

Media header

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

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

Text Message Body

If the created 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 template and must include only the placeholders enclosed in double curly braces {{PlaceholderName}}, exactly as they were defined in the 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 template created contains call-to-action buttons that include dynamic URLs. Currently, templates support adding up to two dynamic URLs for call-to-action buttons.

Remember, dynamic URLs in WhatsApp 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 template.

Creating the Template

When creating a 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 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 template, it’s important to maintain this order (position index) for each button.

Sending the Template

When sending the 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 template (0, 1, 2, 3, ...).

• "placeholders": Lists all the placeholder names ({{placeholderName}}) defined in the approved WhatsApp 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 template is sent. The order of the placeholders in this array must match the order in which they were defined when creating the template.

  For each recipient, the corresponding values for these placeholders are provided in the "data.placeholders" object. When the 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 template.

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

🚧

Media Template Placeholders Editable

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

Remember, when creating a WhatsApp Media Template only provide example placeholder values for each component if the 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 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 template. They are automatically displayed as part of the 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 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 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 Template message over SFTP. These parameters define the campaign 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.\
  
• Template Components parameters: Describe the elements that define and customize the approved WhatsApp Media Template. This section includes referencing the 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 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 template creation. These parameters ensure strict alignment with the approved template structure while enabling accurate and dynamic personalization for each recipient.\
  
• Buttons Component parameters: Detail the configuration of interactive buttons included in the 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 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 template with accurate, individualized content.

Main parameters

Template Components parameters

Buttons Component parameters

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

Recipients & Personalization Data parameters