Updated on October 28, 2026
A WhatsApp carousel template is a marketing template that sends a main text followed by 2 to 10 horizontally scrolling cards, each with an image or video, short text and buttons. There are two template types: the media card carousel, with quick reply, URL or phone buttons, and the product card carousel, which pulls the image, title and price from your Meta catalog. Outside templates, the API also offers an interactive carousel, which can only be sent inside the 24-hour customer service window.
The three carousel types in the WhatsApp Business API
| Type | When to use it | Card header | Buttons per card | Template required? |
|---|---|---|---|---|
| Media card carousel | Campaigns that drive to a website, a reply or a call | Image or video | Up to 2: quick reply, URL or phone | Yes, marketing category |
| Product card carousel | Catalog showcase with in-chat checkout | Catalog product | 1: “View” (opens the product) or URL | Yes, marketing category |
| Interactive media carousel | Replying to a customer who is already chatting | Image or video | 1 URL or quick reply buttons | No, only inside the 24-hour window |
According to Meta’s documentation, carousel cards in templates are only available for marketing messages. To review how Meta categorizes templates, see WhatsApp template categories.
Media card carousel limits
| Item | Limit |
|---|---|
| Number of cards | Minimum 2, maximum 10, fixed at creation |
| Main message body | 1,024 characters, supports variables |
| Card body text | Optional, up to 160 characters (variable values count) |
| Card header | Image or video, automatically cropped to a wide ratio |
| Buttons per card | Up to 2, mixing quick reply, URL and phone number |
| Button label | 25 characters |
| Button URL | 2,000 characters, at most 1 variable, at the end |
| Phone button number | 20 characters |
| Template name | 512 characters |
Three rules that trip people up:
- Every card has the same components. If the first card has a quick reply and a URL button, all cards need a quick reply and a URL button, in the same order.
- Card text is all or nothing. If one card has body text, all of them must, so card heights stay consistent.
- The card count is fixed. A template approved with 3 cards can only be sent with 3 cards. If you want 3-product and 5-product showcases, create two templates.
Want to try it while you read? Create a Vectalk account and send your first message through the official API. Create free account →
How to create a media card carousel template
Creation uses POST /<WABA_ID>/message_templates, with a body component (main text) and a carousel component holding the cards list.
Each card header needs a sample asset in header_handle. That value isn’t a URL: it’s a handle generated by Meta’s Resumable Upload API.
Example with 2 cards, each with a quick reply and a URL button with a variable (for copy ideas, see the template examples by industry):
{
"name": "summer_collection_carousel",
"language": "en_US",
"category": "marketing",
"components": [
{
"type": "body",
"text": "Hi {{1}}! Our summer collection is here. Use code {{2}} until Sunday.",
"example": { "body_text": [["Anna", "SUMMER10"]] }
},
{
"type": "carousel",
"cards": [
{
"components": [
{ "type": "header", "format": "image", "example": { "header_handle": ["<IMAGE_HANDLE_1>"] } },
{
"type": "buttons",
"buttons": [
{ "type": "quick_reply", "text": "I want this" },
{ "type": "url", "text": "View in store", "url": "https://shop.example.com/p/{{1}}", "example": ["linen-dress"] }
]
}
]
},
{
"components": [
{ "type": "header", "format": "image", "example": { "header_handle": ["<IMAGE_HANDLE_2>"] } },
{
"type": "buttons",
"buttons": [
{ "type": "quick_reply", "text": "I want this" },
{ "type": "url", "text": "View in store", "url": "https://shop.example.com/p/{{1}}", "example": ["leather-sandals"] }
]
}
]
}
]
}
]
}The number of examples in body_text must match the number of variables. The template can only be sent once its status is APPROVED. If it gets rejected, WhatsApp template rejected covers the usual reasons.
How to send the carousel template
At send time, each card gets the real media and the variable values. Media goes by ID: upload it with POST /<PHONE_NUMBER_ID>/media and use the returned id. card_index starts at 0 and sets the card’s position; the button index also starts at 0 and follows the order defined in the template.
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "15551234567",
"type": "template",
"template": {
"name": "summer_collection_carousel",
"language": { "code": "en_US" },
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "text": "Anna" },
{ "type": "text", "text": "SUMMER10" }
]
},
{
"type": "carousel",
"cards": [
{
"card_index": 0,
"components": [
{ "type": "header", "parameters": [{ "type": "image", "image": { "id": "1234567890" } }] },
{ "type": "button", "sub_type": "quick_reply", "index": 0, "parameters": [{ "type": "payload", "payload": "want:linen-dress" }] },
{ "type": "button", "sub_type": "url", "index": 1, "parameters": [{ "type": "text", "text": "linen-dress" }] }
]
},
{
"card_index": 1,
"components": [
{ "type": "header", "parameters": [{ "type": "image", "image": { "id": "1234567891" } }] },
{ "type": "button", "sub_type": "quick_reply", "index": 0, "parameters": [{ "type": "payload", "payload": "want:leather-sandals" }] },
{ "type": "button", "sub_type": "url", "index": 1, "parameters": [{ "type": "text", "text": "leather-sandals" }] }
]
}
]
}
]
}
}When the customer taps “I want this”, the messages webhook arrives with the button payload in messages.button.payload. If the button order or type in your send request doesn’t match the template, the API returns an error, because index can’t reorder buttons.
The URL button opens the site outside WhatsApp, and orders placed there don’t trigger order webhooks.
Product card carousel
The product carousel keeps the purchase inside WhatsApp. Each card shows the image, title and price from your catalog, and the “View” button opens the product details, where the customer can add to cart and place the order. When the order is submitted, an order messages webhook fires.
- Connected catalog. You need an e-commerce product catalog with inventory connected to your messaging account. See WhatsApp API catalog and product messages.
- Create with 2 cards, send up to 10. That’s Meta’s guidance for this type.
productheader. At creation, each card has"format": "product"and either anspmbutton (the “View” button) or a URL button.
At send time, each card points to a catalog product:
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "15551234567",
"type": "template",
"template": {
"name": "product_showcase",
"language": { "code": "en_US" },
"components": [
{ "type": "body", "parameters": [{ "type": "text", "text": "Anna" }] },
{
"type": "carousel",
"cards": [
{
"card_index": 0,
"components": [
{ "type": "header", "parameters": [{ "type": "product", "product": { "product_retailer_id": "SKU-001", "catalog_id": "194836987003835" } }] }
]
},
{
"card_index": 1,
"components": [
{ "type": "header", "parameters": [{ "type": "product", "product": { "product_retailer_id": "SKU-002", "catalog_id": "194836987003835" } }] }
]
}
]
}
]
}
}Interactive carousel, no template needed
If the customer is already chatting with you, the 24-hour window is open and you can send a carousel as an interactive message (type: "interactive", interactive.type: "carousel") without creating or approving a template.
The rules for the interactive message, per Meta’s documentation:
- 2 to 10 cards; main body text is required (up to 1,024 characters), with no header or footer.
- Each card has an image or video (sent by public
link) and optional text of up to 160 characters with at most 2 line breaks. - Each card has one URL button or quick reply buttons, and the type and count must match across all cards. Labels are limited to 20 characters.
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "15551234567",
"type": "interactive",
"interactive": {
"type": "carousel",
"body": { "text": "Here are two options for you:" },
"action": {
"cards": [
{
"card_index": 0,
"type": "cta_url",
"header": { "type": "image", "image": { "link": "https://shop.example.com/img/linen-dress.jpg" } },
"body": { "text": "*Linen dress*\n$39.90" },
"action": { "name": "cta_url", "parameters": { "display_text": "Buy now", "url": "https://shop.example.com/p/linen-dress" } }
},
{
"card_index": 1,
"type": "cta_url",
"header": { "type": "image", "image": { "link": "https://shop.example.com/img/leather-sandals.jpg" } },
"body": { "text": "*Leather sandals*\n$29.90" },
"action": { "name": "cta_url", "parameters": { "display_text": "Buy now", "url": "https://shop.example.com/p/leather-sandals" } }
}
]
}
}
}How much a carousel costs
A carousel template is billed as one marketing message, per message and not per card. Meta’s rates depend on the recipient’s country. For recipients in Brazil, the marketing rate since October 1, 2026 is R$ 0.3217 (Brazilian reais) per delivered message, so 10,000 delivered carousels cost R$ 3,217.00 on Meta’s rate card. The interactive carousel, sent inside the service window, is a service message: each number gets 1,000 free service messages per month and pays R$ 0.0350 per message to Brazil from the 1,001st on. For peak dates, the Black Friday on WhatsApp playbook helps you plan volume and budget.
Best practices for carousels that convert
- Consistent images. Meta crops the header to a wide ratio depending on the device, so keep the product centered and avoid text near the edges.
- Strongest card first. Cards appear left to right starting at
card_index0; the rest are only seen if the customer scrolls. - Product ID in the payload. That tells you which card generated the reply, so you can answer with the right product.
- URL variable for tracking. The only variable allowed in a URL button goes at the end; use it for the product slug or a campaign parameter.
- Opt-in and frequency. A carousel is marketing: send it only to people who agreed to receive offers. The per-user marketing limit (error
131049) and template pausing for low quality still apply. See error 131049 and the marketing limit.
Doing it with Vectalk
Vectalk is a proxy for Meta’s official WhatsApp Cloud API, and the payloads are the same as Meta’s. With an instance token, you:
- Upload the send-time images to
POST https://apis.vectalk.com.br/api/mediaand use the returnedidin the card headers. - Create the template with
POST https://apis.vectalk.com.br/api/templatesusing the creation JSON. For the header sample (header_handle), check the accepted format on the create-template page of the docs. - Send the carousel with
POST https://apis.vectalk.com.br/api/messagesusing the same send JSON shown above.
You pay a Vectalk monthly fee and keep a prepaid balance: each delivered message is deducted from that balance, and Vectalk pays Meta, so no card is needed on Meta. Each endpoint is detailed in the Vectalk documentation, and you can sign up at apps.vectalk.com.br/register. For the big picture, see the WhatsApp Cloud API guide.
FAQ
Can I create a carousel in the utility category?
No. Meta’s documentation says carousel cards in templates are only available for marketing messages.
How many cards can I send?
From 2 to 10. In the media carousel, the number is fixed when you create the template. In the product carousel, you create it with 2 cards and can send up to 10.
Can I send a carousel without a template?
Yes, as an interactive message, but only inside the 24-hour window opened by the customer’s last message. To start a conversation, you need the marketing template.
Official sources checked on October 28, 2026: Media card carousel templates (Meta, updated June 24, 2026), Product card carousel templates (Meta, updated June 18, 2026), Interactive media carousel messages (Meta, updated May 21, 2026), Templates overview (Meta), Pricing (Meta), Vectalk: create template, Vectalk: media upload, Vectalk: authentication.
Try the official WhatsApp API today
Create your account, generate a token and send your first message with the quick-start guide. Same payloads and webhooks as Meta's Cloud API.