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:
Use the POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates endpoint to create a carousel template.
POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
{ "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 */ ] } ] }
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. |
|
A message bubble is required. Message bubbles are text-only and support variables.
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.
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"
]
}
]
}
]
}
]
}
]
}'
{ "id": "546151681022936", "status": "PENDING", "category": "MARKETING" }
Once your catalog template is approved, you can use the Cloud API to send it in a carousel template message.