Carousel templates

Carousel templates let you display up to 10 product or destination cards in a single WhatsApp message. Each card has its own image, body text, and action buttons — and the recipient swipes horizontally through them.

When to use carousels

Best for showcasing multiple options side by side:

Travel agency: display 3–5 different resort destinations, each with a booking button
Retail: show multiple products from a collection with individual shop links
Events: present upcoming events or dates with a register quick reply

Limits

Property	Limit
Minimum cards	2
Maximum cards	10
Max buttons per card	2
Card body text	160 characters
Message body text	1 024 characters
Button label	25 characters
URL	2 000 characters
Template category	MARKETING only

Card structure

Each card contains:

Header (required): image or video — uploaded at template creation time as an asset handle; replaced with the actual media ID at send time
Body (optional): short per-card description. If any card has a body, all cards must have one.
Buttons (up to 2): any combination of quick_reply, url, or phone_number

Creating a carousel template

Go to Templates → New template
Select Carousel as the template type
Add your message body text (shown above all cards)
Add at least 2 cards — upload an image for each, add optional body text and buttons
Ensure all cards have the same component structure
Submit for Meta review

Once approved, a carousel template can only be sent with the exact number of cards defined during creation. You cannot add or remove cards after approval — create a new template.

Template creation payload

POST /<WABA_ID>/message_templates
{
  "name": "summer_resorts_2026",
  "language": "it",
  "category": "marketing",
  "components": [
    {
      "type": "body",
      "text": "Ciao {{1}}! Scopri le nostre offerte estate 2026 — ogni resort include volo, hotel e trasferimento.",
      "example": { "body_text": [["Marco"]] }
    },
    {
      "type": "carousel",
      "cards": [
        {
          "components": [
            { "type": "header", "format": "image", "example": { "header_handle": ["4::abc..."] } },
            { "type": "body", "text": "Cilento Resort Velia — da {{1}}€ a settimana", "example": { "body_text": [["499"]] } },
            {
              "type": "buttons",
              "buttons": [
                { "type": "quick_reply", "text": "Più informazioni" },
                { "type": "url", "text": "Prenota", "url": "https://gbviaggi.it/resort/{{1}}", "example": ["cilento-2026"] }
              ]
            }
          ]
        },
        {
          "components": [
            { "type": "header", "format": "image", "example": { "header_handle": ["4::def..."] } },
            { "type": "body", "text": "Praia a Mare — da {{1}}€ a settimana", "example": { "body_text": [["549"]] } },
            {
              "type": "buttons",
              "buttons": [
                { "type": "quick_reply", "text": "Più informazioni" },
                { "type": "url", "text": "Prenota", "url": "https://gbviaggi.it/resort/{{1}}", "example": ["praia-2026"] }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Send payload

At campaign send time, each card needs its own uploaded media ID (obtained from POST /<PHONE_NUMBER_ID>/media):

POST /<PHONE_NUMBER_ID>/messages
{
  "messaging_product": "whatsapp",
  "to": "+393289214993",
  "type": "template",
  "template": {
    "name": "summer_resorts_2026",
    "language": { "code": "it" },
    "components": [
      { "type": "body", "parameters": [{ "type": "text", "text": "Marco" }] },
      {
        "type": "carousel",
        "cards": [
          {
            "card_index": 0,
            "components": [
              { "type": "header", "parameters": [{ "type": "image", "image": { "id": "1558081531584829" } }] },
              { "type": "body", "parameters": [{ "type": "text", "text": "499" }] },
              { "type": "button", "sub_type": "quick_reply", "index": "0", "parameters": [{ "type": "payload", "payload": "cilento-info" }] },
              { "type": "button", "sub_type": "url", "index": "1", "parameters": [{ "type": "text", "text": "cilento-2026" }] }
            ]
          },
          {
            "card_index": 1,
            "components": [
              { "type": "header", "parameters": [{ "type": "image", "image": { "id": "861236878885705" } }] },
              { "type": "body", "parameters": [{ "type": "text", "text": "549" }] },
              { "type": "button", "sub_type": "quick_reply", "index": "0", "parameters": [{ "type": "payload", "payload": "praia-info" }] },
              { "type": "button", "sub_type": "url", "index": "1", "parameters": [{ "type": "text", "text": "praia-2026" }] }
            ]
          }
        ]
      }
    ]
  }
}

Button types

Type	Description	Variable support
`quick_reply`	Tap-to-reply button. Payload sent in webhook on tap.	No
`url`	Opens URL in browser.	1 variable, appended to end of URL
`phone_number`	Initiates a call.	No

Mix button types across cards — e.g. card 1 has a quick_reply + URL button, card 2 has a phone_number + URL button. All cards must use the same number and type of buttons.

Asking Margaret

Type in Margaret’s composer:

“Create a carousel template for our top 4 summer resorts — Cilento, Praia a Mare, Torre Rinalda, Manacore”
“Draft a 3-card carousel promoting GB Viaggi summer offers with a book button on each card”

Margaret scaffolds the structure; you fill in the per-card images when sending the campaign.

Get Started

Features

WhatsApp

Guides

Contributing

Platform

Operations

Security & Compliance

When to use carousels

Limits

Card structure

Creating a carousel template

Template creation payload

Send payload

Button types

Asking Margaret

​When to use carousels

​Limits

​Card structure

​Creating a carousel template

​Template creation payload

​Send payload

​Button types

​Asking Margaret

When to use carousels

Limits

Card structure

Creating a carousel template

Template creation payload

Send payload

Button types

Asking Margaret