Media card carousel templates | Developer Documentation
Media card carousel templates
Updated: Nov 4, 2025
Media card carousel templates allow you to send a single marketing template message accompanied by a set of up to 10 product media cards in a horizontally scrollable view:
When a user taps a media card’s URL button to buy a product, the URL mapped to the button is loaded in the device’s default web browser, thus taking the user out of the WhatsApp client experience. If you prefer to keep the user in the WhatsApp client, see Product Card Carousel Templates. Note that carousel cards are only available for marketing template messages.
Media cards
Carousel templates consist of a message body text and up to 10 product media cards. Each card in the template has an image or video header asset and can optionally include a body text and up to two buttons. Button combinations can be a mix of quick reply buttons, phone number buttons, and URL buttons.
All cards defined on a template must have the same components.
WhatsApp users who place an order do so outside of the WhatsApp client, so no webhooks are triggered describing their order.
Creating media card carousel templates
Use the POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates endpoint to create a media card carousel template.
Request syntax
It is necessary to define the exact number of product cards (minimum 2 and maximum 10) upon template creation. An approved template can only be used to send the same number of cards as defined during its creation. If any card in the carousel includes a card body text, then all cards must include a card body text to ensure consistent card heights.
curl -X POST "https://graph.facebook.com/v23.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '
{
"name": "<TEMPLATE_NAME>",
"language": "<TEMPLATE_LANGUAGE>",
"category": "marketing",
"components": [
{
"type": "body",
"text": "<MESSAGE_BODY_TEXT>",
"example": {
"body_text": [
[
"<MESSAGE_BODY_TEXT_VARIABLE_EXAMPLE_1>",
"<MESSAGE_BODY_TEXT_VARIABLE_EXAMPLE_2>"
]
]
}
},
{
"type": "carousel",
"cards": [
{
"components": [
{
"type": "header",
"format": "<CARD_HEADER_FORMAT>",
"example": {
"header_handle": [
"<CARD_HEADER_ASSET_HANDLE>"
]
}
},
{
"type": "buttons",
"buttons": [
{
"type": "quick_reply",
"text": "<QUICK_REPLY_BUTTON_LABEL_TEXT>"
},
{
"type": "url",
"text": "<URL_BUTTON_LABEL_TEXT>",
"url": "<URL_BUTTON_URL>",
"example": [
"<URL_BUTTON_URL_VARIABLE_EXAMPLE>"
]
},
{
"type": "phone_number",
"text": "<PHONE_NUMBER_BUTTON_LABEL_TEXT>",
"phone_number": "<PHONE_NUMBER>"
}
]
}
]
}
// Add additional cards here, following the same structure
]
}
]
}'Request parameters
| Placeholder | Description | Example Value |
|---|---|---|
<CARD_HEADER_ASSET_HANDLE>String | Required. Uploaded media asset handle. Use the Resumable Upload API to generate an asset handle. Media assets are automatically cropped to a wide ratio based on the WhatsApp user’s device. | |
<CARD_HEADER_FORMAT>String | Required. Card header format. Value can be image or video. | image |
<MESSAGE_BODY_TEXT>String | Required. Message body text. Supports variables. Maximum 1024 characters. | |
<MESSAGE_BODY_TEXT_VARIABLE_EXAMPLE>String | Required if message body text string uses variables. Message body text example variable string(s). Number of strings must match the number of variable placeholders in the message body text string. If message body text uses a single variable, body_text value can be a string, otherwise it must be an array containing an array of strings. | 20OFF |
<PHONE_NUMBER>String | Required if using a phone number button. Alphanumeric string. Business phone number to be called when the WhatsApp user taps the button. Maximum 20 characters. | +15550051310 |
<PHONE_NUMBER_BUTTON_LABEL_TEXT>String | Required if using a phone number button. Phone number button label text. Maximum 25 characters. | Call |
<QUICK_REPLY_BUTTON_LABEL_TEXT>String | Required if using a quick-reply button. Quick-reply button label text. Maximum 25 characters. | Send more like this! |
<TEMPLATE_LANGUAGE>String | Required. Template language and locale code. | en_US |
<TEMPLATE_NAME>String | Required. Template name. Maximum 512 characters. | carousel_template_media_cards_v1 |
<URL_BUTTON_LABEL_TEXT>String | Required if using a URL button. URL button label text. 25 characters maximum. | Shop |
<URL_BUTTON_URL>String | Required if using a URL button. URL to be loaded in the device’s default web browser when the WhatsApp user taps the button. Supports 1 variable. Variable placeholder must be appended to the end of the URL string. Maximum 2000 characters. | https://www.luckyshrub.com/rare-succulents/{{1}} |
<URL_BUTTON_URL_VARIABLE_EXAMPLE>String | Required if URL button URL uses a variable. URL button URL example variable string. Maximum 2000 characters. | BUDDHA |
Example request
This example request creates a media card carousel template with a message that uses 3 variables and 3 media cards. Each media card has a quick reply button, and a URL button that uses a variable.
curl 'https://graph.facebook.com/v25.0/102290129340398/message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
"name": "carousel_template_media_cards_v1",
"language": "en_US",
"category": "marketing",
"components": [
{
"type": "body",
"text": "Rare succulents for sale! {{1}}, add these unique plants to your collection. Each of these rare succulents are {{2}} if you checkout using code {{3}}. Shop now and add some unique and beautiful plants to your collection!",
"example": {
"body_text": [
[
"Pablo",
"30%",
"30OFF"
]
]
}
},
{
"type": "carousel",
"cards": [
{
"components": [
{
"type": "header",
"format": "image",
"example": {
"header_handle": [
"4::an..."
]
}
},
{
"type": "buttons",
"buttons": [
{
"type": "quick_reply",
"text": "Send me more like this!"
},
{
"type": "url",
"text": "Shop",
"url": "https://www.luckyshrub.com/rare-succulents/{{1}}",
"example": [
"BLUE_ELF"
]
}
]
}
]
},
{
"components": [
{
"type": "header",
"format": "image",
"example": {
"header_handle": [
"4::an..."
]
}
},
{
"type": "buttons",
"buttons": [
{
"type": "quick_reply",
"text": "Send me more like this!"
},
{
"type": "url",
"text": "Shop",
"url": "https://www.luckyshrub.com/rare-succulents{{1}}",
"example": [
"BUDDHA"
]
}
]
}
]
},
{
"components": [
{
"type": "header",
"format": "image",
"example": {
"header_handle": [
"4::an..."
]
}
},
{
"type": "buttons",
"buttons": [
{
"type": "quick_reply",
"text": "Send me more like this!"
},
{
"type": "url",
"text": "Shop",
"url": "https://www.luckyshrub.com/rare-succulents{{1}}",
"example": [
"BLACK_PRINCE"
]
}
]
}
]
}
]
}
]
}'
Sending Media Card Carousel Templates
This document describes how to send approved media card carousel templates to WhatsApp users.
Request Syntax
curl -X POST "https://graph.facebook.com/v23.0/<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "<WHATSAPP_USER_PHONE_NUMBER>",
"type": "template",
"template": {
"name": "<TEMPLATE_NAME>",
"language": {
"code": "<TEMPLATE_LANGUAGE>"
},
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "<MESSAGE_BODY_TEXT_VARIABLE_1>" },
{ "type": "text", "text": "<MESSAGE_BODY_TEXT_VARIABLE_2>" }
]
},
{
"type": "carousel",
"cards": [
{
"card_index": 0,
"components": [
{
"type": "header",
"parameters": [
{
"type": "<MESSAGE_HEADER_FORMAT>",
"<MESSAGE_HEADER_FORMAT>": {
"id": "<MESSAGE_HEADER_ASSET_ID>"
}
}
]
},
{
"type": "body",
"parameters": [
{ "type": "text", "text": "<CARD_BODY_VARIABLE_1>" },
{ "type": "text", "text": "<CARD_BODY_VARIABLE_2>" }
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": 0,
"parameters": [
{
"type": "payload",
"payload": "<QUICK_REPLY_BUTTON_PAYLOAD>"
}
]
},
{
"type": "button",
"sub_type": "url",
"index": 1,
"parameters": [
{
"type": "text",
"text": "<URL_BUTTON_URL_VARIABLE>"
}
]
}
]
}
// Add additional cards here, following the same structure
]
}
]
}
}'Request parameters
| Placeholder | Description | Example Value |
|---|---|---|
<BUTTON_INDEX>Integer | Required. Zero-indexed order in which button appears at the bottom of the template message. 0 indicates the first button, 1 indicates second button, etc.Note that if any buttons use variables, the type and order of buttons must match the type and order defined on the template, so you can’t use the index values to arrange the order of the buttons in the sent template. For example, if the template defines a phone number button first (which equates to index 0) and a URL button that supports a single variable second (which equates to index 1), if you attempt to send the template with the URL button index set to 0 , the API would return an error (“Parameter value for URL was expected but was not found”) because it’s expecting a button object with an index of 1 to be present in the post body payload. | 0 |
<CARD_BODY_VARIABLE>Object | Required if the template card body text uses variables, otherwise omit. Object describing a card body variable. If the template uses multiple variables, you must define an object for each variable. There is no maximum character limit on this value, but does count against the card body text limit of 160 characters. | |
<CARD_INDEX>Integer | Required. Zero-indexed order in which card should appear within the card carousel. 0 indicates first card, 1 indicates second card, etc. | 0 |
<MESSAGE_BODY_TEXT_VARIABLE>Object | Required if template message body text uses variables, otherwise omit. Object describing a message variable. If the template uses multiple variables, you must define an object for each variable. There is no maximum character limit on this value, but it does count against the message body text limit of 1024 characters. | |
<MESSAGE_HEADER_ASSET_ID>String | Required. Header asset’s uploaded media asset ID. Use the POST /<BUSINESS_PHONE_NUMBER_ID>/media endpoint to generate an asset ID. | 1558081531584829 |
<MESSAGE_HEADER_FORMAT>String | Required. Indicates header type and a matching property name. Note that the <MESSAGE_HEADER_FORMAT> placeholder appears twice in the post body example above, as it serves as a placeholder for the type property’s value and its matching property name.Value can be image or video. | image |
<QUICK_REPLY_BUTTON_PAYLOAD>String | Optional. Value to be included in messages webhooks ( messages.button.payload) when the button is tapped. | more-aloes |
<TEMPLATE_LANGUAGE>String | Required. Template language and locale code. | en_US |
<TEMPLATE_NAME>String | Required. Template name. Maximum 512 characters. | carousel_template_media_cards_v1 |
<URL_BUTTON_URL_VARIABLE>String | Required if the URL button URL uses a variable. URL button variable value. | blue-elf |
<WHATSAPP_USER_PHONE_NUMBER>String | Required. WhatsApp user phone number. | +16505551234 |
Example request
This example request sends a media card carousel template named “carousel_template_media_cards_v1”. It supplies three body text variables (which the template requires) and contents for three cards (which the template also requires). For each card, the request supplies an image asset ID, a quick-reply button payload (to be included in webhooks when the button is tapped), and a text string to be injected into the URL mapped to the card’s URL button (which is defined on the template).
curl 'https://graph.facebook.com/v25.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "+16505551234",
"type": "template",
"template": {
"name": "carousel_template_media_cards_v1",
"language": {
"code": "en_US"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Pablo"
},
{
"type": "text",
"text": "20%"
},
{
"type": "text",
"text": "20OFF"
}
]
},
{
"type": "carousel",
"cards": [
{
"card_index": 0,
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": {
"id": "1558081531584829"
}
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
"payload": "more-aloes"
}
]
},
{
"type": "button",
"sub_type": "url",
"index": "1",
"parameters": [
{
"type": "text",
"text": "blue-elf"
}
]
}
]
},
{
"card_index": 1,
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": {
"id": "861236878885705"
}
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
"payload": "more-crassulas"
}
]
},
{
"type": "button",
"sub_type": "url",
"index": "1",
"parameters": [
{
"type": "text",
"text": "buddhas-temple"
}
]
}
]
},
{
"card_index": 2,
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": {
"id": "1587064918516321"
}
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
"payload": "more-echeverias"
}
]
},
{
"type": "button",
"sub_type": "url",
"index": "1",
"parameters": [
{
"type": "text",
"text": "black-prince"
}
]
}
]
}
]
}
]
}
}'
No comments to display
No comments to display