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éimageemediaestá preenchido. Outro valor emtypefaz o card sair sem mídia, então trate o carrossel como vitrine de imagens. - Tipos de botão.
reply(ouquick_reply) para resposta rápida com o identificador emid,url(oucta_url) para abrir um endereço,call(oucta_call) para ligar para o número emphone. - Tipo desconhecido. Um botão com
typefora 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.