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

# Templates de carrossel

> Envie mensagens com cartões de mídia roláveis horizontalmente para múltiplos destinos ou produtos — o tipo de template com maior engajamento para turismo e varejo.

Os templates de carrossel permitem exibir até 10 cartões de produto ou destino em uma única mensagem do WhatsApp. Cada cartão tem sua própria imagem, texto de corpo e botões de ação — e o destinatário deslisa horizontalmente entre eles.

## Quando usar carrosséis

Ideal para exibir várias opções lado a lado:

* **Agência de viagens**: exibir 3 a 5 destinos de resorts diferentes, cada um com um botão de reserva
* **Varejo**: mostrar múltiplos produtos de uma coleção com links de loja individuais
* **Eventos**: apresentar próximos eventos ou datas com um botão de resposta rápida de inscrição

## Limites

| Propriedade                | Limite            |
| -------------------------- | ----------------- |
| Mínimo de cartões          | 2                 |
| Máximo de cartões          | 10                |
| Máx. de botões por cartão  | 2                 |
| Texto do corpo do cartão   | 160 caracteres    |
| Texto do corpo da mensagem | 1.024 caracteres  |
| Rótulo do botão            | 25 caracteres     |
| URL                        | 2.000 caracteres  |
| Categoria do template      | Somente MARKETING |

## Estrutura do cartão

Cada cartão contém:

* **Header** (obrigatório): `image` ou `video` — enviado no momento da criação do template como um identificador (asset handle); substituído pelo ID de mídia real no momento do envio
* **Body** (opcional): descrição curta por cartão. Se algum cartão tiver um body, todos os cartões devem ter um.
* **Buttons** (até 2): qualquer combinação de `quick_reply`, `url` ou `phone_number`

## Criando um template de carrossel

1. Vá em **Templates → Novo template**
2. Selecione **Carrossel** como o tipo de template
3. Adicione o texto do corpo da sua mensagem (exibido acima de todos os cartões)
4. Adicione pelo menos 2 cartões — envie uma imagem para cada um, adicione texto de corpo e botões opcionais
5. Garanta que todos os cartões tenham a mesma estrutura de componentes
6. Envie para revisão da Meta

<Warning>
  Depois de aprovado, um template de carrossel só pode ser enviado com o número exato de cartões definido no momento da criação. Você não pode adicionar ou remover cartões após a aprovação — crie um novo template.
</Warning>

## Payload de criação do template

```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 de envio

No momento do envio da campanha, cada cartão precisa do seu próprio ID de mídia enviado (obtido em `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" }] }
            ]
          }
        ]
      }
    ]
  }
}
```

## Tipos de botão

| Tipo           | Descrição                                                                    | Suporte a variável                  |
| -------------- | ---------------------------------------------------------------------------- | ----------------------------------- |
| `quick_reply`  | Botão de toque para responder. O payload é enviado no webhook ao ser tocado. | Não                                 |
| `url`          | Abre a URL no navegador.                                                     | 1 variável, anexada ao final da URL |
| `phone_number` | Inicia uma chamada.                                                          | Não                                 |

<Tip>
  Combine tipos de botão entre cartões — por exemplo, o cartão 1 tem um botão quick\_reply + URL, o cartão 2 tem um botão phone\_number + URL. Todos os cartões devem usar o mesmo número e tipo de botões.
</Tip>

## Perguntando à Margaret

Digite na caixa de composição da Margaret:

* *"Crie um template de carrossel para nossos 4 principais resorts de verão — Cilento, Praia a Mare, Torre Rinalda, Manacore"*
* *"Elabore um carrossel de 3 cartões promovendo as ofertas de verão da GB Viaggi com um botão de reserva em cada cartão"*

A Margaret estrutura o esqueleto; você preenche as imagens de cada cartão ao enviar a campanha.