Creating & Sending WhatsApp Media Message Template
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.

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.

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.

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.

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

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:

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 Components | Options | Required |
---|---|---|
Header | Text: 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 Message | Contains text, personalized fields (placeholders), and emojis. | Yes |
Footer | Contains only text. | No |
Buttons | Call 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 Parameter | Description |
---|---|
wabaId | WhatsApp Business Account ID (WABA). In case you don't have a WABA Id, our support team will provide it to you. |
senderId | Unique 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.
|
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: Spanish: Portuguese: |
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:
|
templateLanguages.components. format |
No | Only applies to the Header content displayed on top of a message. The header object contains the following options:
The URL of the header (image, video and document) must be a valid URL that starts with |
templateLanguages.components. text |
No | Only applies to the 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 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 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 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 |
templateLanguages.components. example.body_text |
No | Only applies to the 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.
|
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:
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:
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 ( |
templateLanguages.components. buttons.phone_number |
No | Only applies to the Call To Action Phone number that is called on clicking the button. if you set |
templateLanguages.components. buttons.url |
No | Only applies to the Call To Action If you set 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 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 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 (New way to send a media message template)
We recomend you go to this section.
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: Spanish: Portuguese: |
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 Array of URL containing the header type chosen when creating the template. |
templateHeader.type | Yes | Only applies if the template created contains the Enter the media header type chosen when creating the template in lower case: |
templateHeader.url | Yes | Only applies if the template created contains the 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 |
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 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:
|
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 Array of personalized fields (placeholders) containing the text message body. Set as parameter the placeholder you configured that is inside double curly braces ( For example: 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 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 Enter the header type chosen when creating the template in lower case: |
templateHeader.type.text | No | Only applies if the template created contains the Enter the personalized fields (placeholders) in order of how they were defined. |
templateHeader.type.url | No | Only applies if the template created contains the 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 |
- 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 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 Enter the button type chosen when creating the template:
|
templateButtons.values | No | Only applies if the template created contains the Array that contains the Template button values. |
templateButtons.values.index | No | Only applies if the template created contains the 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 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 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