Criar conta
← Blog

·

Template carrossel no WhatsApp: cards com imagem e botão

Atualizado em 28/10/2026

O template carrossel do WhatsApp é um template de marketing que envia um texto principal acompanhado de 2 a 10 cards com rolagem horizontal, cada um com imagem ou vídeo, texto curto e botões. Existem dois tipos de template: o carrossel de cards de mídia, com botões de resposta rápida, URL ou telefone, e o carrossel de cards de produto, que puxa imagem, título e preço do catálogo da Meta. Fora dos templates, a API também tem o carrossel interativo, que só pode ser enviado dentro da janela de 24 horas.

Os três tipos de carrossel na API do WhatsApp

TipoQuando usarCabeçalho do cardBotões por cardPrecisa de template?
Carrossel de cards de mídiaCampanhas que levam ao site, a uma resposta ou a uma ligaçãoImagem ou vídeoAté 2: resposta rápida, URL ou telefoneSim, categoria marketing
Carrossel de cards de produtoVitrine de produtos do catálogo, com compra dentro do WhatsAppProduto do catálogo1: “View” (abre o produto) ou URLSim, categoria marketing
Carrossel interativo de mídiaResposta a um cliente que já está conversandoImagem ou vídeo1 URL ou botões de resposta rápidaNão, só dentro da janela de 24 h

Segundo a documentação da Meta, cards de carrossel em templates estão disponíveis apenas para mensagens de marketing. Para revisar como a Meta classifica templates, veja categorias de template.

Limites do carrossel de cards de mídia

ItemLimite
Quantidade de cardsMínimo 2, máximo 10, definida na criação
Texto principal (body)1.024 caracteres, aceita variáveis
Texto do cardOpcional, até 160 caracteres (variáveis contam no limite)
Cabeçalho do cardImagem ou vídeo, cortado automaticamente em proporção larga
Botões por cardAté 2, combinando resposta rápida, URL e telefone
Rótulo de cada botão25 caracteres
URL do botão2.000 caracteres, com no máximo 1 variável, no final
Número do botão de telefone20 caracteres
Nome do template512 caracteres

Três regras que pegam muita gente:

  • Todos os cards têm os mesmos componentes. Se o primeiro card tem resposta rápida e URL, todos precisam ter resposta rápida e URL, na mesma ordem.
  • Texto no card é tudo ou nada. Se um card tem texto, todos precisam ter, para manter a altura dos cards igual.
  • A quantidade de cards é fixa. Um template aprovado com 3 cards só pode ser enviado com 3 cards. Se você quer vitrines de 3 e de 5 produtos, crie dois templates.

Quer testar enquanto lê? Crie sua conta na Vectalk e envie a primeira mensagem pela API oficial. Criar conta grátis →

Como criar um template carrossel de mídia

A criação usa POST /<WABA_ID>/message_templates, com um componente body (texto principal) e um componente carousel com a lista de cards.

O cabeçalho de cada card precisa de um exemplo de mídia no campo header_handle. Esse valor não é uma URL: é um identificador gerado pela API de upload retomável (Resumable Upload API) da Meta.

Exemplo com 2 cards, cada um com resposta rápida e URL com variável (para ideias de texto, veja os modelos de template por setor):

{
  "name": "colecao_verao_carrossel",
  "language": "pt_BR",
  "category": "marketing",
  "components": [
    {
      "type": "body",
      "text": "Oi, {{1}}! A coleção de verão chegou. Use o cupom {{2}} até domingo.",
      "example": { "body_text": [["Ana", "VERAO10"]] }
    },
    {
      "type": "carousel",
      "cards": [
        {
          "components": [
            { "type": "header", "format": "image", "example": { "header_handle": ["<HANDLE_DA_IMAGEM_1>"] } },
            {
              "type": "buttons",
              "buttons": [
                { "type": "quick_reply", "text": "Quero este" },
                { "type": "url", "text": "Ver na loja", "url": "https://loja.example.com/p/{{1}}", "example": ["vestido-linho"] }
              ]
            }
          ]
        },
        {
          "components": [
            { "type": "header", "format": "image", "example": { "header_handle": ["<HANDLE_DA_IMAGEM_2>"] } },
            {
              "type": "buttons",
              "buttons": [
                { "type": "quick_reply", "text": "Quero este" },
                { "type": "url", "text": "Ver na loja", "url": "https://loja.example.com/p/{{1}}", "example": ["sandalia-couro"] }
              ]
            }
          ]
        }
      ]
    }
  ]
}

O número de exemplos em body_text precisa ser igual ao de variáveis. O template só pode ser enviado com status APPROVED. Se for reprovado, o guia template reprovado no WhatsApp lista os motivos mais comuns.

Como enviar o template carrossel

No envio, cada card recebe a mídia real e os valores das variáveis. A mídia vai por ID: faça o upload com POST /<PHONE_NUMBER_ID>/media e use o id retornado. O campo card_index começa em 0 e indica a posição do card; o index do botão também começa em 0 e segue a ordem definida no template.

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "colecao_verao_carrossel",
    "language": { "code": "pt_BR" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Ana" },
          { "type": "text", "text": "VERAO10" }
        ]
      },
      {
        "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": "quero:vestido-linho" }] },
              { "type": "button", "sub_type": "url", "index": 1, "parameters": [{ "type": "text", "text": "vestido-linho" }] }
            ]
          },
          {
            "card_index": 1,
            "components": [
              { "type": "header", "parameters": [{ "type": "image", "image": { "id": "1234567891" } }] },
              { "type": "button", "sub_type": "quick_reply", "index": 0, "parameters": [{ "type": "payload", "payload": "quero:sandalia-couro" }] },
              { "type": "button", "sub_type": "url", "index": 1, "parameters": [{ "type": "text", "text": "sandalia-couro" }] }
            ]
          }
        ]
      }
    ]
  }
}

Quando o cliente toca em “Quero este”, o webhook de mensagens chega com o payload do botão em messages.button.payload. Se a ordem ou o tipo dos botões no envio não bater com o template, a API devolve erro, porque o index não reordena botões.

O botão de URL abre o site fora do WhatsApp, e pedidos feitos lá não geram webhook de pedido.

Carrossel de cards de produto

O carrossel de produtos mantém a compra dentro do WhatsApp. Cada card mostra imagem, título e preço vindos do catálogo, e o botão “View” abre os detalhes do produto, onde o cliente pode adicionar ao carrinho e enviar o pedido. Quando o pedido é enviado, chega um webhook de mensagem do tipo pedido.

  • Catálogo conectado. É preciso ter um catálogo de produtos com inventário conectado à conta de mensagens. O artigo sobre catálogo na API do WhatsApp mostra como funciona.
  • Crie com 2 cards, envie até 10. É a orientação da Meta para esse tipo.
  • Cabeçalho product. Na criação, cada card tem "format": "product" e um botão spm (o “View”) ou um botão de URL.

No envio, cada card aponta para um produto do catálogo:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "vitrine_produtos",
    "language": { "code": "pt_BR" },
    "components": [
      { "type": "body", "parameters": [{ "type": "text", "text": "Ana" }] },
      {
        "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" } }] }
            ]
          }
        ]
      }
    ]
  }
}

Carrossel interativo, sem template

Se o cliente já está conversando com você, a janela de 24 horas está aberta e você pode mandar um carrossel como mensagem interativa (type: "interactive", interactive.type: "carousel"), sem criar nem aprovar template.

As regras da mensagem interativa, segundo a documentação:

  • De 2 a 10 cards; texto principal obrigatório (até 1.024 caracteres), sem cabeçalho ou rodapé.
  • Cada card tem imagem ou vídeo (por link público) e texto opcional de até 160 caracteres, com no máximo 2 quebras de linha.
  • Cada card tem um botão de URL ou botões de resposta rápida, e o tipo e a quantidade precisam ser iguais em todos os cards. Os rótulos têm até 20 caracteres.
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "carousel",
    "body": { "text": "Separei duas opções para você:" },
    "action": {
      "cards": [
        {
          "card_index": 0,
          "type": "cta_url",
          "header": { "type": "image", "image": { "link": "https://loja.example.com/img/vestido-linho.jpg" } },
          "body": { "text": "*Vestido de linho*\nR$ 189,90" },
          "action": { "name": "cta_url", "parameters": { "display_text": "Comprar", "url": "https://loja.example.com/p/vestido-linho" } }
        },
        {
          "card_index": 1,
          "type": "cta_url",
          "header": { "type": "image", "image": { "link": "https://loja.example.com/img/sandalia-couro.jpg" } },
          "body": { "text": "*Sandália de couro*\nR$ 149,90" },
          "action": { "name": "cta_url", "parameters": { "display_text": "Comprar", "url": "https://loja.example.com/p/sandalia-couro" } }
        }
      ]
    }
  }
}

Quanto custa um carrossel

O template carrossel é uma mensagem de marketing: para destinatários no Brasil, R$ 0,3217 por mensagem entregue desde 1º de outubro de 2026, por mensagem e não por card. O carrossel interativo, dentro da janela, é mensagem de serviço: cada número tem franquia de 1.000 por mês e, a partir da 1.001ª, paga R$ 0,0350 para o Brasil.

Exemplo: 10.000 carrosséis entregues no Brasil custam R$ 3.217,00 na tabela da Meta. Para datas de pico, o calendário de Black Friday no WhatsApp ajuda a planejar volume e orçamento.

Boas práticas para carrossel que converte

  • Imagens no mesmo padrão. Como a Meta corta o cabeçalho em proporção larga conforme o aparelho, mantenha o produto no centro e evite texto nas bordas da imagem.
  • O card mais forte primeiro. Os cards aparecem da esquerda para a direita a partir do card_index 0; os seguintes só são vistos se o cliente rolar.
  • Payload com ID do produto. Assim você sabe qual card gerou a resposta e responde com o produto certo.
  • Variável no fim da URL para rastreio. A única variável permitida no botão de URL fica no final; use-a para o slug do produto ou um parâmetro de campanha.
  • Opt-in e frequência. Carrossel é marketing: só envie para quem aceitou receber ofertas. O limite de marketing por usuário (erro 131049) e a pausa de templates por qualidade baixa valem igual. Veja limite de marketing por usuário.

Como fazer com a Vectalk

A Vectalk é um proxy da WhatsApp Cloud API oficial, e os payloads são os mesmos da Meta. Com um token de instância, você:

  1. Faz o upload das imagens de envio em POST https://apis.vectalk.com.br/api/media e usa o id retornado nos cabeçalhos dos cards.
  2. Cria o template em POST https://apis.vectalk.com.br/api/templates com o JSON de criação. Para o exemplo de mídia do cabeçalho (header_handle), confira o formato aceito na página de criação de template da documentação.
  3. Envia o carrossel em POST https://apis.vectalk.com.br/api/messages com o mesmo JSON de envio mostrado acima.

Você paga a mensalidade da Vectalk e mantém um saldo pré-pago: cada mensagem entregue é descontada desse saldo, e a Vectalk paga a Meta, sem cartão cadastrado na Meta. Os detalhes de cada endpoint estão na documentação da Vectalk, e a conta é criada em apps.vectalk.com.br/register. Para o contexto geral da plataforma, veja o guia da API oficial do WhatsApp.

Perguntas frequentes

Posso criar um carrossel na categoria utilidade?

Não. A documentação da Meta diz que cards de carrossel em templates estão disponíveis apenas para mensagens de marketing.

Quantos cards posso enviar?

De 2 a 10. No carrossel de mídia, o número é fixado na criação do template. No carrossel de produto, você cria com 2 cards e pode enviar até 10.

Dá para mandar carrossel sem template?

Sim, como mensagem interativa, mas só dentro da janela de 24 horas aberta pela última mensagem do cliente. Para iniciar a conversa, é preciso o template de marketing.

Fontes oficiais consultadas em 28/10/2026: Media card carousel templates (Meta, atualizado em 24/06/2026), Product card carousel templates (Meta, atualizado em 18/06/2026), Interactive media carousel messages (Meta, atualizado em 21/05/2026), Templates overview (Meta), Preços (Meta), Vectalk: criar template, Vectalk: upload de mídia, Vectalk: autenticação.

Teste a API oficial do WhatsApp hoje

Crie sua conta, gere o token e envie a primeira mensagem seguindo o guia da documentação. Mesmos payloads e webhooks da Cloud API da Meta.

Criar conta grátis
Ler a documentação