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

# Modelli carosello

> Invia messaggi con card multimediali scorrevoli orizzontalmente con più destinazioni o prodotti — il tipo di modello con il maggior engagement per il settore viaggi e retail.

I modelli carosello ti permettono di visualizzare fino a 10 card di prodotto o destinazione in un singolo messaggio WhatsApp. Ogni card ha una propria immagine, testo del corpo e bottoni di azione — e il destinatario scorre orizzontalmente tra di esse.

## Quando usare i caroselli

Ideali per mostrare più opzioni fianco a fianco:

* **Agenzia di viaggi**: mostra 3–5 diverse destinazioni turistiche, ciascuna con un bottone di prenotazione
* **Retail**: mostra più prodotti di una collezione con link individuali al negozio
* **Eventi**: presenta eventi o date in arrivo con una risposta rapida di registrazione

## Limiti

| Proprietà                     | Limite          |
| ----------------------------- | --------------- |
| Numero minimo di card         | 2               |
| Numero massimo di card        | 10              |
| Bottoni massimi per card      | 2               |
| Testo del corpo della card    | 160 caratteri   |
| Testo del corpo del messaggio | 1 024 caratteri |
| Etichetta bottone             | 25 caratteri    |
| URL                           | 2 000 caratteri |
| Categoria del modello         | solo MARKETING  |

## Struttura della card

Ogni card contiene:

* **Intestazione** (obbligatoria): `image` o `video` — caricata al momento della creazione del modello come handle asset; sostituita con l'ID media effettivo al momento dell'invio
* **Corpo** (opzionale): breve descrizione per ogni card. Se una card ha un corpo, tutte le card devono averne uno.
* **Bottoni** (fino a 2): qualsiasi combinazione di `quick_reply`, `url`, o `phone_number`

## Creare un modello carosello

1. Vai su **Modelli → Nuovo modello**
2. Seleziona **Carosello** come tipo di modello
3. Aggiungi il testo del corpo del messaggio (mostrato sopra tutte le card)
4. Aggiungi almeno 2 card — carica un'immagine per ciascuna, aggiungi testo del corpo opzionale e bottoni
5. Assicurati che tutte le card abbiano la stessa struttura di componenti
6. Invia per la revisione di Meta

<Warning>
  Una volta approvato, un modello carosello può essere inviato solo con il numero esatto di card definito durante la creazione. Non puoi aggiungere o rimuovere card dopo l'approvazione — crea un nuovo modello.
</Warning>

## Payload di creazione del modello

```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"] }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

## Payload di invio

Al momento dell'invio della campagna, ogni card necessita del proprio ID media caricato (ottenuto da `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" }] }
            ]
          }
        ]
      }
    ]
  }
}
```

## Tipi di bottone

| Tipo           | Descrizione                                                                  | Supporto variabili                       |
| -------------- | ---------------------------------------------------------------------------- | ---------------------------------------- |
| `quick_reply`  | Bottone tocca-per-rispondere. Il payload viene inviato nel webhook al tocco. | No                                       |
| `url`          | Apre l'URL nel browser.                                                      | 1 variabile, aggiunta alla fine dell'URL |
| `phone_number` | Avvia una chiamata.                                                          | No                                       |

<Tip>
  Combina diversi tipi di bottone tra le card — ad es. la card 1 ha un bottone quick\_reply + URL, la card 2 ha un bottone phone\_number + URL. Tutte le card devono usare lo stesso numero e lo stesso tipo di bottoni.
</Tip>

## Chiedere a Margaret

Scrivi nel compositore di Margaret:

* *"Crea un modello carosello per i nostri 4 migliori resort estivi — Cilento, Praia a Mare, Torre Rinalda, Manacore"*
* *"Prepara un carosello a 3 card che promuova le offerte estive di GB Viaggi con un bottone di prenotazione su ogni card"*

Margaret crea la struttura; tu inserisci le immagini per ogni card al momento dell'invio della campagna.