> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Carousel templates

> Send horizontally scrollable media card messages with multiple destinations or products — the highest-engagement template type for travel and retail.

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

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

<Warning>
  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.
</Warning>

## Template creation payload

```json theme={null}
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`):

```json theme={null}
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                                 |

<Tip>
  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.
</Tip>

## 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.