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

• Image: Accepts image files in .jpg, or .png format, with a maximum file size of 5 MB.
• Video: It must be less than 5MB and the format .mp4, .3gpp (Only H.264 video codec and AAC audio codec are supported).
• Document: Accepts .pdf documents with a maximum file size of 5 MB.

📘

NOTE

You are only able to edit the Multimedia Header (Image, Video, 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 message 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 message template by adding a variable at the end of the link. The suffix value you set here acts as a default. When you send this message 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 Communications Platform, in the Message Templates section or by Message 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 Communications 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 message template to the request body.

🚧

WARNING

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

You are only able to set a value for a Multimedia Header (Image, Video, 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 message 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 this 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, they 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 they 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 Message Template, it is essential to understand how to include placeholders in the payload when the message template created contains personalized fields in the Header or Text Message components. Furthermore, if the message 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 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:

  Request body example when sending the message 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 message 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 message template

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

  The "templateHeader.type"parameter includes the header type chosen when creating the message 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 message template.

Text Message Body

If the created message 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 message template. Then set the value of the placeholder parameter.

For instance, according to the previous example, the text message body of the created message 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 message template was created.

Position Index (Buttons)

If the created message 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 message 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 message 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 message template, it’s important to maintain this order (position index) for each button.

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

• for quick reply buttons, enter the keyword defined when creating the message template regarding its index position.
• for call to action buttons, enter the URL suffix value defined when creating the message 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 Message Template for each component are editable when you send the message 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.

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

Message Template Creation

When creating a message 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 message 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 Message Template

When sending the message template, the dynamic URL suffix ({{order}}) must be replaced with an actual value (URL suffix value) in the payload. The payload for sending the message 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 message 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 message 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 message template through the Messaging API.

⚠️

WARNING

You can not edit the message template content as phone numbers (Call to Action), and Static URLs (Call to Action) in the request body when sending the message 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, 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 message template. It highlights the importance of identifying the message template, specifying the sender and recipient, and ensuring the message 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 message 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 message 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 message 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, Document), and placeholder(s) that include the text message body.

Buttons Component parameters

You are only able to edit if the created message 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: