Pular para o conteúdo
D-APITestar grátis

carrossel pela api

Carrossel WhatsApp API para o seu SaaS mostrar produtos na conversa

Com o carrossel da WhatsApp API, o seu SaaS envia até 10 cards com imagem, texto e botões numa mensagem só. O cliente final desliza, escolhe e responde sem sair do WhatsApp.

SaaS testa 14 dias com o time técnico ajudando na integração.

conexões na D-API
1.875
de uptime garantido em contrato
99,9%
datacenters no Brasil
4
por ligação de WhatsApp na API não-oficial
R$ 0
  • Até 10 cards por mensagem

    Cada card tem body obrigatório, header com imagem, footer opcional e até 2 botões.

  • Botões de resposta, link e ligação

    Na API não-oficial, os botões aceitam resposta rápida, abertura de URL e ligação para um número.

  • Mesma rota na API Oficial

    Dentro da janela de 24 horas, o mesmo payload vira o carrossel interativo da Meta, com as regras dela validadas antes do envio.

O carrossel da WhatsApp API coloca uma vitrine dentro da conversa. Em vez de mandar cinco fotos soltas e uma lista de preços em texto, o seu SaaS envia uma mensagem com cards lado a lado, cada um com imagem, descrição curta e botões. O cliente final desliza com o dedo, toca em “quero este” e a resposta volta para o seu sistema com o identificador do item.

Para quem constrói plataforma de e-commerce, cardápio de delivery, CRM imobiliário ou software de academia, o carrossel é a forma mais direta de transformar o atendimento em venda. Na API de WhatsApp da D-API, ele sai por um endpoint só: POST /api/v1/interactive/send/carousel.

Onde o carrossel faz diferença no seu produto

O carrossel funciona quando a decisão do cliente final depende de ver o item. Alguns exemplos de clientes SaaS:

  • Imobiliária. O corretor envia os três imóveis que batem com o perfil do lead, com foto da fachada, bairro e valor, e um botão para agendar visita.
  • Delivery. O restaurante manda os pratos do dia com foto, e o botão de resposta coloca o item no pedido.
  • E-commerce. A loja mostra variações de um produto ou uma recomendação depois da compra, com botão para a página do item.
  • Academia. A recepção apresenta os planos com imagem e um botão para ligar e tirar dúvida.

Nos quatro casos, o seu cliente ganha uma vitrine que ele não precisaria desenhar: o seu SaaS monta o payload a partir do catálogo que já existe no banco.

Estrutura de um carrossel pela API

O corpo tem sessionId, to, cards (de 1 a 10) e três campos opcionais da mensagem: body (texto acima dos cards), title e footer. Cada card leva:

Campo do card Regra
body Obrigatório, texto do card
header Opcional, com type, media e title opcional
footer Opcional
buttons Até 2, cada um com type, title e, conforme o tipo, id, url ou phone
curl -X POST https://api.d-api.cloud/api/v1/interactive/send/carousel \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "imobiliaria-4821",
    "to": "5511999999999",
    "body": "Separei três opções no seu perfil:",
    "cards": [
      {
        "header": { "type": "image", "media": "https://exemplo.com.br/imoveis/1032.jpg" },
        "body": "Apartamento 2 quartos, Vila Mariana. R$ 2.800/mês.",
        "buttons": [
          { "type": "reply", "title": "Agendar visita", "id": "visita_imovel_1032" },
          { "type": "url", "title": "Ver fotos", "url": "https://exemplo.com.br/imoveis/1032" }
        ]
      },
      {
        "header": { "type": "image", "media": "https://exemplo.com.br/imoveis/1047.jpg" },
        "body": "Studio mobiliado, Pinheiros. R$ 2.300/mês.",
        "buttons": [
          { "type": "reply", "title": "Agendar visita", "id": "visita_imovel_1047" },
          { "type": "url", "title": "Ver fotos", "url": "https://exemplo.com.br/imoveis/1047" }
        ]
      }
    ]
  }'

A resposta de sucesso traz messageId e messageType: "carousel". O mesmo carrossel aparece no evento messages.sent, com data.type: "carousel" e a lista de cards.

Botões e mídia na API não-oficial

Nas conexões da API não-oficial, o código de envio trata o card assim:

  • Mídia. A imagem é anexada quando header.type é image e media está preenchido. Outro valor em type faz o card sair sem mídia, então trate o carrossel como vitrine de imagens.
  • Tipos de botão. reply (ou quick_reply) para resposta rápida com o identificador em id, url (ou cta_url) para abrir um endereço, call (ou cta_call) para ligar para o número em phone.
  • Tipo desconhecido. Um botão com type fora da lista é descartado sem erro, e o card sai sem ele. Valide no seu lado antes de enviar.

Carrossel na API Oficial

Se parte da sua base está na API Oficial, a mesma rota funciona dentro da janela de 24 horas, e a D-API traduz o payload para o carrossel interativo da Meta. As regras da Meta são mais estreitas, e a tradução valida cada uma antes do envio:

Regra API não-oficial API Oficial
Quantidade de cards 1 a 10 2 a 10
Header Imagem Imagem ou vídeo, obrigatório em todo card
Botões por card Até 2, opcionais Pelo menos 1; um botão de URL ou botões de resposta rápida
Botão de ligação Aceito Recusado
Uniformidade Livre Todos os cards com o mesmo tipo e quantidade de botões
title e footer da mensagem Campos próprios Entram no texto do body
footer do card Campo próprio Entra no texto do card, até 160 caracteres somados

O texto do botão na API Oficial tem até 20 caracteres, e o body da mensagem, com título e rodapé somados, até 1.024. Se o payload quebra uma regra, a chamada volta com erro dizendo qual, em vez de sair um carrossel pela metade. Para um SaaS com base mista, a saída prática é montar sempre no formato mais restrito: 2 ou mais cards, todos com imagem e com os mesmos botões.

Lendo a escolha do cliente

O seu código precisa saber qual card o cliente final escolheu. Por isso, o id do botão de resposta deve carregar o contexto completo, como visita_imovel_1032: o tipo de ação e o identificador do objeto no seu banco. O handler do webhook não precisa guardar estado em memória para interpretar o clique.

Na API não-oficial, o bridge de conexão classifica respostas a mensagens nativas como nativeflow_response, com os campos name, params_json (os parâmetros do botão em JSON) e quoted_message_id, que aponta para a mensagem original. Esse tipo não aparece na lista da referência de messages.received, então valide o payload exato do clique no seu ambiente de teste antes de tratar em produção. O artigo sobre webhooks da API de WhatsApp cobre envelope, retentativas e idempotência, e o formato do carrossel enviado está na documentação da D-API.

Do carrossel ao pedido

Um fluxo de venda completo combina formatos. O carrossel apresenta, a resposta rápida identifica o item, o seu sistema monta o pedido e o botão Pix fecha a cobrança na mesma conversa. Se o catálogo do seu cliente já está no WhatsApp Business, a API de catálogo mantém produtos e coleções sincronizados com o seu sistema.

O artigo sobre mensagens interativas compara carrossel, lista, NativeFlow e Pix e ajuda a escolher o formato para cada ponto do fluxo.

Time D-API. Atualizado em .

Perguntas frequentes

Quantos cards e botões cabem num carrossel?

A rota aceita de 1 a 10 cards, com até 2 botões por card. Na API Oficial, o mínimo sobe para 2 cards e cada card precisa de pelo menos um botão.

Posso usar vídeo no header do card?

Na API Oficial, o header aceita imagem ou vídeo. Na API não-oficial, a mídia do card é anexada quando header.type é image; outro tipo faz o card sair sem mídia.

O que acontece se eu mandar um tipo de botão que a conexão não suporta?

Na API não-oficial, o botão com tipo desconhecido é descartado e o card sai sem ele. Na API Oficial, a D-API recusa o envio com erro e explica a regra que falhou, como botão de ligação em card.

Carrossel custa mais que uma mensagem de texto?

Na API não-oficial, a D-API cobra por conexão ativa, sem cobrança por mensagem. Na API Oficial, o envio dentro da janela de 24 horas segue as regras de cobrança da Meta na conta do seu cliente.

Carrossel ou lista, qual escolher?

Carrossel quando a imagem vende, como produto, imóvel ou plano. Lista quando há muitas opções em texto, como horários ou categorias: ela aceita até 10 seções com 10 linhas cada.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.