Botões e listas na WhatsApp API: listas, carrossel e Pix
Como enviar botões e listas pela WhatsApp API, além de carrossel e Pix, e ler a resposta do cliente por webhook dentro do seu SaaS.
Time D-API. Atualizado em .8 min de leitura.
Botões e listas na WhatsApp API transformam uma conversa aberta em uma escolha estruturada. Em vez de pedir que o cliente digite “1 para confirmar, 2 para remarcar” e torcer para o texto chegar no formato certo, o seu SaaS envia opções clicáveis e recebe de volta um identificador que o seu código conhece. Para quem vende atendimento, agendamento, delivery ou automação de marketing, isso significa menos mensagens sem resposta clara, menos fallback para atendente humano e fluxos que funcionam do jeito que foram desenhados.
A D-API oferece cinco formatos de mensagem interativa em endpoints separados: lista, carrossel, Pix, botões NativeFlow e template com botões de ação. Todos seguem o mesmo padrão de autenticação e de sessionId que o seu backend já usa para enviar texto, e todas as respostas do cliente chegam pelo mesmo webhook de mensagens recebidas.
Este artigo mostra quando usar cada formato, como montar o payload a partir da documentação real e como ler a escolha do cliente para dar o próximo passo no fluxo.
Por que interatividade melhora o produto do seu SaaS
O primeiro ganho é previsibilidade. Uma resposta de lista chega com o rowId que você mesmo definiu, então o seu código decide o próximo passo com um switch, sem interpretar texto livre. Isso vale para chatbots, para fluxos do builder de automação e para agentes de IA que precisam de pontos de decisão confiáveis no meio da conversa.
O segundo ganho é experiência. O cliente final toca numa opção em vez de digitar, o que reduz atrito em menus de atendimento, escolha de horário e seleção de produto. O terceiro ganho é comercial: carrossel e Pix colocam vitrine e pagamento dentro da conversa, o que abre features novas para o seu cliente vender pelo WhatsApp.
Os cinco formatos e quando usar cada um
Lista: menus e escolhas com muitas opções
A lista é o formato mais versátil e, segundo a própria referência da API, a melhor alternativa ao carrossel quando o objetivo é apresentar opções. A mensagem mostra um texto e um botão (buttonText) que abre as opções, organizadas em seções. Os campos obrigatórios são sessionId, to, description, buttonText e sections. São de 1 a 10 seções, cada uma com 1 a 10 linhas, e cada linha tem rowId, title e uma description opcional.
curl -X POST https://api.d-api.cloud/api/v1/interactive/send/list \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "cliente-4821",
"to": "5511999999999",
"title": "Agendamento",
"description": "Escolha o melhor horário para a sua consulta.",
"buttonText": "Ver horários",
"footerText": "Clínica Exemplo",
"sections": [
{
"title": "Terça-feira",
"rows": [
{ "rowId": "slot_ter_0900", "title": "09:00", "description": "Dra. Ana" },
{ "rowId": "slot_ter_1430", "title": "14:30", "description": "Dr. Paulo" }
]
}
]
}'
Use o rowId para carregar contexto: um prefixo que indica o fluxo e o identificador do objeto no seu banco. Quando a resposta chegar, você sabe exatamente o que fazer sem consultar estado em memória.
Carrossel: vitrine de produtos e planos
O carrossel envia até 10 cards, cada um com body obrigatório, header com mídia, footer opcional e até 2 botões. Os botões aceitam os campos type, title, id, url e phone. Acima dos cards, o campo body da mensagem traz o texto de introdução, com title e footer opcionais.
É o formato natural para SaaS de e-commerce, cardápio de delivery e catálogo de serviços: cada card mostra um item com imagem e um botão para pedir ou saber mais.
O cabeçalho do card usa type: "image", com a imagem em media por URL ou base64. Outro valor em header.type faz o card sair sem mídia, então trate o carrossel como vitrine de imagens. Nos botões, type aceita três valores: reply (resposta rápida, com o identificador em id), url (abre o endereço em url) e call (liga para o número em phone). Um botão com tipo fora dessa lista não aparece no card, por isso vale validar antes do envio.
{
"sessionId": "cliente-4821",
"to": "5511999999999",
"body": "Conheça os planos da Academia Exemplo:",
"footer": "Toque num card para escolher",
"cards": [
{
"header": { "type": "image", "media": "https://exemplo.com.br/planos/mensal.jpg" },
"body": "Plano Mensal: acesso livre à musculação.",
"footer": "Sem fidelidade",
"buttons": [
{ "type": "reply", "title": "Quero este", "id": "plano_mensal_assinar" },
{ "type": "url", "title": "Ver detalhes", "url": "https://exemplo.com.br/planos/mensal" }
]
},
{
"header": { "type": "image", "media": "https://exemplo.com.br/planos/anual.jpg" },
"body": "Plano Anual: musculação e aulas coletivas.",
"buttons": [
{ "type": "reply", "title": "Quero este", "id": "plano_anual_assinar" },
{ "type": "call", "title": "Falar com a recepção", "phone": "5511999999999" }
]
}
]
}
Pix: cobrança dentro da conversa
O endpoint de Pix envia uma mensagem com botão de cópia da chave Pix. Os campos obrigatórios são sessionId, to, content e pixKey, e você pode incluir pixAmount, pixMessage e footer. Para SaaS de cobrança, agendamento com sinal ou delivery, isso reduz o caminho entre “quanto fica?” e o pagamento.
{
"sessionId": "cliente-4821",
"to": "5511999999999",
"content": "Seu pedido #1932 está confirmado. Toque no botão para copiar a chave Pix.",
"pixKey": "[email protected]",
"pixAmount": 89.9,
"pixMessage": "Pedido 1932",
"footer": "Pagamento via Pix"
}
A mensagem facilita o pagamento, mas a confirmação continua com o seu sistema: conciliação pelo seu provedor de pagamentos e atualização do pedido no seu banco.
NativeFlow: botões rápidos, links, ligação e cópia
O NativeFlow aceita de 1 a 4 botões dos tipos quick_reply, url, call e copy, com body obrigatório, title, footer e imageUrl opcionais. O botão copy usa o campo copy_code, útil para cupom de desconto ou código de rastreio. A referência da API indica que esse formato é exibido apenas no celular, então vale usar onde o público majoritário acessa pelo app mobile e ter um texto alternativo no body.
Template com botões de ação
O endpoint /api/v1/interactive/send/template envia uma mensagem com botões CTA dos tipos url e call. Os campos obrigatórios são sessionId, to, content e buttons, com title, footer e imageUrl opcionais. Serve para avisos que terminam numa ação externa: “acompanhar pedido” abrindo um link, “falar com a loja” iniciando uma ligação.
Este endpoint é diferente dos templates aprovados pela Meta na API Oficial, que têm categorias, aprovação e cobrança próprias.
Os cinco endpoints de /api/v1/interactive/send/* (lista, carrossel, Pix, NativeFlow e template com botões) foram feitos para as conexões da API não-oficial. Numa conexão da API Oficial, a mesma rota é aceita e traduzida para o formato da Meta, mas só vale dentro da janela de 24 horas, e alguns formatos são adaptados (o Pix, por exemplo, sai como texto). Se a sua base mistura as duas modalidades, guarde o tipo de cada conexão e decida o formato antes do envio: para clientes na API Oficial, a mensagem iniciada pela empresa sai por template aprovado, pelo POST /api/v1/messages/send/template.
Lendo a resposta do cliente pelo webhook
Enviar o botão é metade do trabalho. A outra metade é receber a escolha e decidir o próximo passo. As respostas chegam no evento messages.received do webhook, com o campo data.type indicando o formato:
data.type |
O que significa |
|---|---|
list_response |
O cliente escolheu uma opção de lista |
template_button_reply |
O cliente clicou num botão |
Este é o trecho relevante de um list_response, conforme a documentação:
{
"event": "messages.received",
"sessionId": "my-session",
"data": {
"id": "3EB00E07AFE6175651FCE9",
"type": "list_response",
"message": "Sim",
"data": {
"selected_row_id": "t1",
"selected_title": "Sim",
"description": "aham",
"list_type": 1,
"original_list": { "title": "Teste", "options": ["Sim"] }
}
}
}
O selected_row_id é o rowId que você enviou. No caso de botão, o template_button_reply traz selected_id, selected_display_text, selected_index (começando em 0) e quoted_message_id, que aponta para a mensagem com os botões. Com esses campos, o handler do seu webhook fica simples: identifique o tipo, leia o identificador, execute a ação correspondente.
O mesmo webhook também registra as mensagens interativas enviadas pelo próprio número em outro dispositivo, com tipos list, carousel e nativeflow. Filtre por fromMe para tratar só as respostas dos contatos. A referência completa do endpoint de lista está na documentação da D-API, e o artigo sobre webhooks da API de WhatsApp cobre envelope, retentativas e idempotência.
Mensagens interativas num SaaS multi-tenant
Em um SaaS com muitos clientes, cada cliente tem a própria conexão, identificada pelo sessionId. O webhook de mensagens recebidas traz o sessionId no nível raiz, então o roteamento por tenant acontece antes de qualquer lógica de fluxo. O artigo sobre API de WhatsApp multi-tenant detalha esse desenho.
Algumas práticas deixam os fluxos interativos estáveis em escala:
rowIdeidautodescritivos. Inclua o tipo de ação e o identificador do objeto, comoslot_ter_0900oupedido_1932_confirmar. O handler não precisa de estado em memória do processo, o que permite rodar várias réplicas.- Validação na borda. Antes de executar a ação, confira se o identificador recebido pertence ao tenant daquele
sessionId. Nunca confie que o identificador veio intacto. - Idempotência no handler. Um clique repetido ou uma retentativa do webhook não pode confirmar o mesmo agendamento duas vezes.
- Limites respeitados no seu lado. Valide antes do envio: até 10 seções e 10 linhas na lista, até 10 cards e 2 botões por card no carrossel, até 4 botões no NativeFlow.
Interativas e custo de mensagens
Na API não-oficial, a cobrança é por conexão, com preço que cai com o volume (veja a tabela em /#preco). Se parte dos clientes do seu SaaS usa a API Oficial, as mensagens fora da janela de 24 horas dependem de templates aprovados e seguem as tarifas da Meta, cobradas na conta Meta do cliente final. Antes de desenhar o fluxo, confira a tarifa de cada categoria na tabela de preços da Meta.
Por onde começar
Escolha um ponto do seu produto em que o cliente final hoje responde em texto livre e o seu sistema sofre para interpretar. Confirmação de agendamento e menu inicial de atendimento são os candidatos mais comuns. Troque esse ponto por uma lista com rowId bem definidos, implemente o handler de list_response no webhook e meça quantas conversas passam a seguir o fluxo sem intervenção humana.
Depois disso, carrossel e Pix entram como extensões naturais para quem vende pelo WhatsApp. A D-API sustenta esses fluxos com 1.875 conexões, 4 datacenters no Brasil e 99,9% de uptime garantido em contrato, e o grupo de onboarding dos 14 dias de teste acompanha a implementação do primeiro envio ao primeiro clique tratado.
Veja também: Integração, API de WhatsApp.
Perguntas frequentes
Como sei qual opção da lista o cliente escolheu?
A escolha chega no webhook messages.received com type list_response. O campo data.selected_row_id traz o rowId que você definiu no envio, e data.selected_title traz o texto da opção.
Quantas opções cabem numa mensagem de lista?
O endpoint aceita de 1 a 10 seções, e cada seção aceita de 1 a 10 linhas. Cada linha precisa de rowId e title, com description opcional.
Qual a diferença entre o endpoint template e o nativeflow?
O /api/v1/interactive/send/template envia botões de URL e de ligação. O /api/v1/interactive/send/nativeflow aceita até 4 botões dos tipos quick_reply, url, call e copy, e é exibido apenas no celular.
O botão Pix processa o pagamento?
O endpoint de Pix envia uma mensagem com botão de cópia da chave, com valor opcional. A confirmação do pagamento continua sendo responsabilidade do seu sistema ou do seu provedor de pagamentos.
Preciso de um sessionId para enviar mensagens interativas?
Sim. Todos os endpoints interativos exigem sessionId e to, porque a mensagem sai por uma conexão de WhatsApp específica. Em um SaaS multi-tenant, o sessionId identifica a conexão de cada cliente.