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, a video, or a 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 by 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.

  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.

🚧

WARNING

You must carefully copy each value according to its corresponding parameter you set when creating the media template via UI (Digital Engagement Platform) to the request body.

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.

📘

NOTE

The total number of API Calls (requests) that the user can make to the POST /notification endpoint in a certain time has been limited. That is, in case the user exceeds the limit of requests (messages sent) that can be made in a specific time, he/she will not be able to send another request until the established time is up. Once the time has elapsed, the request counter is reset and the request can be sent to the endpoint again.

In this example, the user can send 2 requests in 300 seconds (5 minutes). When a third request is sent within the 5 minute range, the HTTP Status Code “429” will be generated and the following parameter will be displayed from the Response body: "errors": { "reason": Too Many Requests" }. This code tells you that the user has sent too many requests in a given amount of time. Once the required time has elapsed, the request counter is reset to 2, so the user will be able to send two requests again in 5 minutes.

To find out if the user exceeds the limit of required requests and the time he/she needs to wait to send the next request, we recommend consulting the Response Header (additional information about the body of the resource). The parameters presented in the response header are the following:

ratelimit-limit: 2
ratelimit-policy: 2;w= 300
ratelimit-remaining: 1
ratelimit-reset: 5m0s

• RateLimit-Limit: return the number of requests left for the client in the time window
• RateLimit-Remaining: return the remaining quota in the current window
• RateLimit-Reset: return the time remaining in the current window, specified in seconds
• RateLimit-Policy: return the quota policy. The quota policy expression can be found in paragraph 2.1 of the IETF draft. The format is, for example, for 2 requests in 300 seconds.

Before sending a WhatsApp Template, it is essential to understand how to include placeholders in the payload when the template created contains personalized fields in the Header or Text Message components. Furthermore, if the template included a Buttons component with 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:

  Request body example when sending the template

  "templateHeader": {  
      "type": "text",  
      "text": "Eli Package"  
    }
  

  
  

  📘

  NOTE

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

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

• Media header

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

  Request body example when sending the template

  "templateHeader":{  
      "type": "image",  
      "url": "https://example.com?media=image"
    }
  

  The "templateHeader.type"parameter includes the header type chosen when creating the template in lower case: "image", "video", "document". And enter the URL of the chosen media from the "url" parameter.

  From the above example, the media type was an image.

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

Text Message Body

If the created template includes a "Text Message" component with placeholder(s), the example payload JSON will be as follows:

"placeholders": {  
    "name": "Elizabeth",  
    "lastName": "Smith"  
}

From the "placeholders" object, 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 instance, according to the previous example, the text message body of the created template is as follows:

{  
   "type":"BODY",  
   "text":"Welcome {{name}} {{lastName}} we have a new offer for you!",  
   "example":{  
      "body_text": [  
         [  
            "John",  
            "Doe"  
         ]  
      ]  
   }  
}

The placeholders must be correctly formatted in order of how the template was created.

Position Index (Buttons)

If the created template includes a “Buttons” component with either a dynamic URL (call to action type button) or quick reply type buttons, the example payload JSON will be as follows:

This request body example contains three (3) quick reply buttons and one (1) call to action button (Dynamic URL).

{
   "templateButtons":[
      {
         "type":"quick-reply",
         "values":[
            {
               "index":0,
               "value":"Accept"
            },
            {
               "index":1,
               "value":"Decline"
            },
            {
               "index":2,
               "value":"Other"
            }
         ]
      },
      {
         "type":"cta",
         "values":[
            {
               "index":3,
               "value":"user-71421"
            }
         ]
      }
   ]
}

For Quick Reply and Call to Action buttons, the "templateButtons.values.index" parameter indicates the position index of the button of how it was defined when creating the template (0, 1, 2, 3, ...).

To clarify the position index, we will review the position of the buttons in the request body when creating the template:

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

From the example above, we can notice that

• The quick reply button with the keyword “Accept” is in the first position (0).
• The quick reply button with the keyword “Decline” is in the second position (1).
• The quick reply button with the keyword “Other” is in the third position (2).
• Lastly, the call to action button is in the fourth position (3).

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

Following the request body example when sending a template, the "templateButtons.values.value" parameter,

• for quick reply buttons, enter the keyword defined when creating the template regarding its index position.
• for call to action buttons, enter the URL suffix value defined when creating the template regarding its index position. The URL suffix is then propagated as an extension of the registered URL address.

🚧

WARNING

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.

Dynamic URLs (Call To Action)

After understanding the position index of buttons, the next step is 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.

Template Creation

When creating a template with a call-to-action button containing a dynamic URL, you specify a placeholder (URL suffix) in the "url" parameter of the button. Here’s an example of how the payload might look during template creation:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "To locate your order, click Here!",
      "url": "https://www.packageorders.com/{{order}}",
      "example": [
        "https://www.packageorders.com/hj07taw12"
      ]
    }
  ]
}

In this payload:

• "url": Includes a URL suffix ({{order}}) for the dynamic portion of the URL.
• "example": Provides a sample URL demonstrating how the URL suffix will be replaced.

Sending the Template

When sending the template, the dynamic URL suffix ({{order}}) must be replaced with an actual value (URL suffix value) in the payload. The payload for sending the template includes the "templateButtons" field, which specifies the type of button (cta for call-to-action) and the URL suffix value for the placeholder:

{
   "templateButtons":[
      {
         "type":"cta",
         "values":[
            {
               "index":0,
               "value":"hj07taw12"
            }
         ]
      }
   ]
}

In this payload:

• type: Indicates a call-to-action (cta) button.
• index: Specifies the position of the button in the template (starting at 0).
• value: Provides the actual URL suffix value to replace the URL suffix (hj07taw12 in this case).

This dynamic URL system enables personalized and actionable buttons tailored to each recipient, improving engagement and usability.

After understanding how to send personalized fields (placeholders) for the Header and Text Message, the position index of buttons, and dynamic URLs for call-to-action buttons—as long as the template includes any of these elements—, and the media message template has been created via UI or API and approved, we can proceed to send the template through the Messaging API.

⚠️

WARNING

You can not edit the template content as phone numbers (Call to Action), and Static URLs (Call to Action) in the request body when sending the template because the values of that parameters have been approved by WhatsApp.

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, or Button Payloads values from Quick Reply Buttons in the request body, and placeholder(s) that includes the text message body and the header text.

Sending Media Message Template

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

HTTP Request : POST / notification

{
  "channel": "WHATSAPP",
  "request": {
    "from":"1000000001",
    "to":"+1000000002",
    "templateName":"code_shipping",
    "templateLanguage":"en",
    "message": "Hi! your discount code is {{code}}",
    "templateHeader":{  
    "type": "image",  
    "url": "https://example.com?media=image"
    },
    "placeholders":{
       "code":"34871"
    },
    "templateButtons":[
       {
          "type":"cta",
          "values":[
             {
                "index":0,
                "value":"ertyhgf456"
             }
          ]
       },
       {
          "type":"quick-reply",
          "values":[
             {
                "index":1,
                "value":"Unsubscribe"
             }
          ]
       }
    ]
  }
}

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

• Main parameters: Outline the essential information needed to send a media WhatsApp template. It highlights the importance of identifying the template, specifying the sender and recipient, and ensuring the template is sent in the correct language. These parameters are crucial for delivering the message accurately and effectively.
• Components parameters: Outline the essential information to explain how to customize and personalize the content of a media WhatsApp template. It covers setting up the header with either a placeholder or media URL, specifying the header type, and configuring placeholder(s) in the text message body. These parameters ensure that the message is accurately tailored to the recipient, using the appropriate content and placeholders defined in the template.
• Buttons Component parameters: It details the requirements for setting up the Call to Action and Quick Reply buttons, including specifying their type, defining their values (like URL suffix and keywords), and positioning them correctly within the template. These parameters ensure that the buttons work as intended, providing a seamless interactive experience for the recipient.

Main Parameters

Components parameters

You are only able to edit the placeholder of the header text, the value for a Multimedia Header (Image, Video, or Document), and placeholder(s) that includes the text message body.

Buttons Component parameters

You are only able to edit If the created template includes a “Buttons” component with either a dynamic URL (call to action type button) or quick reply type buttons.

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

{
  "meta": {
    "timestamp": 1642531254980,
    "transactionId": "077da1d0-e089-487e-aed0-59534ba2d9f5",
    "explain": "Send Notification"
  }
}

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