Carousel Templates
This document describes carousel templates and how to use them. Carousel templates allow you to send a single text message accompanied by a set of up to 10 carousel cards in a horizontally scrollable view:
Creating Carousel Templates
Use the POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates endpoint to create a carousel template.
Request Syntax
POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
Post Body
{
"name": "<TEMPLATE_NAME>",
"language": "<TEMPLATE_LANGUAGE>",
"category": "<TEMPLATE_CATEGORY>",
"components": [
/* Message bubble, required */
{
"type": "BODY",
"text": "<BUBBLE_TEXT>",
"example": {
"body_text": [["<BUBBLE_TEXT_VAR_EXAMPLE>"]]
}
},
/* Carousel cards */
{
"type": "CAROUSEL",
"cards": [
/* First carousel card */
{
"components": [
{
"type": "HEADER",
"format": "<CARD_HEADER_FORMAT>",
"example": {
"header_handle": ["<CARD_HEADER_HANDLE>"]
}
},
{
"type": "BODY",
"text": "<CARD_BODY_TEXT>",
"example": {
"body_text": [["<CARD_BODY_TEXT_VAR_EXAMPLE>"]]
}
},
/* At least one button required */
{
"type": "BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "<QUICK_REPLY_BUTTON_TEXT>"
},
{
"type": "URL",
"text": "<URL_BUTTON_TEXT>",
"url": "<URL_BUTTON_URL>",
"example": ["<URL_BUTTON_VAR_EXAMPLE>"]
}
]
}
]
},
/* Addt'l cards would follow, using same structure as first card */
]
}
]
}
Body Properties
| Placeholder | Description | Example Value |
|---|---|---|
| String |
Required. Message bubble text string. Supports variables. Maximum 1024 characters. |
|
| Array of strings |
Required if the message bubble text string uses variables. Array of example variable strings. Number of strings must match the number of variables included in the string. |
|
| String |
Required. Card body text. Support variables. Maximum 160 characters. |
|
| Array of strings |
Required if using card body text with variables. Card body text example variables. |
|
| Enum |
Required. Card media header
format. Must be |
|
| Media asset handle |
Required. Uploaded media asset handle. Use the Resumable Upload API to generate an asset handle. See Carousel Cards for media asset requirements. |
|
| String |
Required if using a quick reply button. Quick reply button label text. Maximum 25 characters. |
|
| Enum |
Required. Must be |
|
| Enum |
Required. Template language and locale code . |
|
| String |
Required. Template name. Maximum 512 characters. |
|
| String |
Required if using a URL button. URL button label text. Supports 1 variable. 25 characters maximum. |
|
| String |
Required if using a URL button. URL of website that loads in the device's default mobile web browser when the URL button is tapped by the app user. Supports 1 variable, appended to the end of the URL string. Maximum 2000 characters. |
|
| String |
Required if using a URL button. URL of website. Supports 1 variable. If using a variable, add sample variable property to the end of the URL string. The URL loads in the device's default mobile web browser when the customer taps the URL button . Maximum 2000 characters. |
|
Message Bubble
A message bubble is required. Message bubbles are text-only and support variables.
Carousel Cards
Carousel templates support up to 10 carousel cards. Cards must have a media header (image or video), body text, and at least one button. Supports 2 buttons. Buttons can be the same or a mix of quick reply buttons , phone number buttons , or URL buttons .
The media header format and button types must be the same across all cards that make up a carousel template.
Media assets will be cropped to a wide ratio based on the customer's device.
Example Request
curl 'https://graph.facebook.com/ v20.0
/102290129340398/message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
"name": "summer_carousel_promo_2023",
"language": "en_US",
"category": "MARKETING",
"components": [
{
"type": "BODY",
"text": "Summer is here, and we have the freshest produce around! Use code {{1}} to get {{2}} off your next order.",
"example": {
"body_text": [
[
"15OFF",
"15%"
]
]
}
},
{
"type": "CAROUSEL",
"cards": [
{
"components": [
{
"type": "HEADER",
"format": "IMAGE",
"example": {
"header_handle": [
"4::aW..."
]
}
},
{
"type": "BODY",
"text": "Rare lemons for unique cocktails. Use code {{1}} to get {{2}} off all produce.",
"example": {
"body_text": [
[
"15OFF",
"15%"
]
]
}
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Send more like this"
},
{
"type": "URL",
"text": "Buy now",
"url": "https://www.luckyshrub.com/shop?promo={{1}}",
"example": [
"https://www.luckyshrub.com/shop?promo=summer_lemons_2023"
]
}
]
}
]
},
{
"components": [
{
"type": "HEADER",
"format": "IMAGE",
"example": {
"header_handle": [
"4::aW..."
]
}
},
{
"type": "BODY",
"text": "Exotic fruit for unique cocktails! Use code {{1}} to get {{2}} off all exotic produce.",
"example": {
"body_text": [
[
"20OFFEXOTIC",
"20%"
]
]
}
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Send more like this"
},
{
"type": "URL",
"text": "Buy now",
"url": "https://www.luckyshrub.com/shop?promo={{1}}",
"example": [
"https://www.luckyshrub.com/shop?promo=exotic_produce_2023"
]
}
]
}
]
}
]
}
]
}'
Example Response
{
"id": "546151681022936",
"status": "PENDING",
"category": "MARKETING"
}
Sending Carousel Templates
Once your catalog template is approved, you can use the Cloud API to send it in a carousel template message .
