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

integração

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.

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:

  • rowId e id autodescritivos. Inclua o tipo de ação e o identificador do objeto, como slot_ter_0900 ou pedido_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.

Teste com o time técnico do seu lado

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

Leia também

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.