Botões e listas no WhatsApp API: mensagens interativas com IA

Botões e listas no WhatsApp API: mensagens interativas com IA

Botões e listas são mensagens interativas da API do WhatsApp que mostram ao cliente opções fechadas para tocar, em vez de exigir que ele digite. Use-os quando a resposta cabe em poucas escolhas conhecidas, como setor, horário ou tipo de pedido, e deixe o texto livre para o que é imprevisível. Combinados com um agente de IA, eles reduzem ambiguidade: a IA interpreta o que o cliente escreve e propõe as opções, e o seu sistema recebe uma escolha com identificador, não uma frase solta.

Principais pontos

• Botões servem para decisões curtas e raras de errar (sim ou não, confirmar ou remarcar). Listas servem para escolher entre várias opções do mesmo tipo.
• Texto livre continua sendo o melhor caminho para descrever problemas, dúvidas e contexto. A interface fechada não substitui a conversa, ela a organiza.
• O agente de IA entende a intenção em linguagem natural, e as mensagens interativas confirmam o que importa antes de qualquer ação com efeito real.
• Cada botão e cada linha de lista carrega um identificador que o sistema valida. A resposta do cliente vira dado estruturado, mais fácil de registrar e auditar.
• Comece por um fluxo, meça se a ambiguidade realmente caiu e mantenha sempre uma saída para um atendente humano.

O que são botões e listas na API do WhatsApp?

Na API oficial do WhatsApp Business (a que passa pela Meta, diretamente ou por um provedor), uma mensagem interativa é aquela que traz elementos de toque junto ao texto. Os dois formatos mais usados no atendimento são:

• Botões de resposta: poucos botões abaixo da mensagem. O cliente toca em um e o sistema recebe o identificador e o título escolhido.
• Lista: um botão que abre um menu com seções e linhas, cada uma com título, descrição curta e identificador. Cabe mais opções do que os botões, mas ainda dentro de um limite.

Existem também botões de chamada para ação, como abrir um link ou ligar, que servem a outro propósito: levar o cliente para fora da conversa. Neste texto o foco são os dois primeiros, porque são eles que capturam uma decisão dentro do próprio chat.

Os limites exatos (quantidade de botões, de linhas, tamanho dos títulos) e as regras de uso mudam com o tempo e dependem do formato. Confirme sempre na documentação oficial da Meta ou do seu provedor antes de desenhar o fluxo. Há ainda a regra da janela de atendimento: dentro dela você responde com mensagens livres e interativas; fora dela, o contato ativo depende de templates aprovados e de consentimento. Esse tema está detalhado em mensagens ativas no WhatsApp: templates, opt-in e boas práticas.

Quando usar botões, lista ou texto livre?

A pergunta útil não é "qual formato é mais moderno", e sim "quantas respostas válidas existem e o quanto um erro custa". Um guia de decisão simples:

• Use botões quando houver duas ou poucas respostas possíveis e a escolha disparar algo: confirmar um horário, aceitar uma proposta, autorizar o envio de um documento.
• Use lista quando houver um conjunto conhecido de opções semelhantes: unidades, serviços, datas disponíveis, motivos de contato.
• Use texto livre quando o cliente precisar descrever algo: um defeito, uma dúvida técnica, uma situação particular, um pedido fora do padrão.
• Use texto livre mais confirmação em botão quando a IA interpretou uma frase e vai agir. Exemplo: o cliente escreve "quero mudar para sexta de manhã", a IA entende a intenção e responde com um resumo e dois botões, confirmar ou corrigir.
• Não use nenhum dos dois quando o assunto for sensível, emocional ou uma reclamação. Nesses casos, a interface fechada soa burocrática e o melhor é transferir para uma pessoa.

Uma regra prática: se você já sabe de antemão as respostas aceitáveis, ofereça-as. Se precisa ouvir antes de saber, deixe falar.

Como o agente de IA e as mensagens interativas trabalham juntos?

Um agente de IA bem desenhado é bom em entender linguagem solta, mas é a parte menos previsível do sistema. As mensagens interativas fazem o papel inverso: são previsíveis e limitadas. Juntas, dividem o trabalho de forma saudável.

O desenho que costuma funcionar tem quatro movimentos:

• O cliente escreve livremente. A IA identifica a intenção e os dados que já aparecem na frase.
• Se faltar um dado de um conjunto conhecido, o agente pede por lista ou botão em vez de fazer uma pergunta aberta. Isso evita respostas como "pode ser qualquer dia" ou "aquele de sempre".
• Antes de uma ação com efeito (agendar, cancelar, registrar um pedido), o agente apresenta um resumo e pede confirmação por botão.
• A resposta chega ao sistema como identificador. O código valida e executa, e o resultado vai para um registro de decisões.

O ponto central é que a IA propõe e o sistema dispõe. O modelo não deveria inventar opções: as linhas da lista vêm de uma fonte confiável (agenda, catálogo, cadastro) e o modelo apenas escolhe quando mostrá-las. Esse padrão de dividir o que é fluxo determinístico do que exige julgamento aparece também na discussão de guardrails em agentes de IA e no material da Anthropic sobre como construir agentes eficazes, que recomenda começar pela solução mais simples e adicionar autonomia só onde ela se paga.

Passo a passo para desenhar um fluxo interativo

Um roteiro para sair do papel sem cair em menus intermináveis:

• Passo 1, escolha um fluxo: um único caso de uso, como remarcar atendimento ou triar o motivo do contato. Quem quer ver o caso de agenda em detalhe pode consultar agendamento automático no WhatsApp com IA.
• Passo 2, mapeie as respostas válidas: liste, a partir de conversas reais, o que os clientes pedem e quais campos o sistema precisa para executar.
• Passo 3, separe o fechado do aberto: o que tem lista finita vira botão ou lista, o que depende de contexto fica em texto livre.
• Passo 4, defina a fonte das opções: de onde vêm as linhas (agenda, catálogo, tabela de serviços) e quem mantém essa fonte atualizada.
• Passo 5, escreva textos curtos: títulos objetivos, uma descrição só quando ajudar, sem jargão interno da empresa.
• Passo 6, trate a escolha como dado: valide o identificador recebido no servidor e confira se ele pertence às opções que foram realmente enviadas àquela conversa.
• Passo 7, preveja a saída: toda lista precisa de uma opção como "falar com uma pessoa" ou "outro assunto", que leva a texto livre ou a transferência.
• Passo 8, registre: guarde a mensagem enviada, a opção escolhida e a ação executada, para poder revisar erros.

Cenário ilustrativo: remarcação em uma empresa de manutenção

Imagine, como exemplo hipotético, uma empresa de manutenção de equipamentos que recebe pedidos de remarcação no WhatsApp. O cliente escreve: "preciso mudar a visita da semana que vem, não vou estar".

Sem mensagens interativas, o atendimento começaria uma troca longa: qual visita, para qual dia, qual período, em qual endereço. Cada pergunta aberta convida a respostas vagas.

Com o fluxo combinado, o agente identifica a intenção de remarcar e consulta o sistema para achar a visita do cliente. Se houver mais de uma, mostra uma lista com as visitas agendadas. Depois, mostra uma lista com os próximos horários realmente livres, vindos da agenda. Por fim, envia o resumo (visita, nova data, período) com botões para confirmar ou escolher outro horário.

Se o cliente disser algo fora do esperado, como "o técnico quebrou meu portão da última vez", o agente não insiste no menu. Ele reconhece que o assunto é outro, registra o contexto e transfere para uma pessoa. O menu serve ao caminho comum, não prende o cliente nele.

Quais erros e riscos observar?

Alguns problemas aparecem com frequência quando se mistura interface fechada e IA:

• Menus demais: encadear muitas telas de escolha cansa. Se o cliente já informou o dado na frase, o agente deve pular a pergunta.
• Opções inventadas pelo modelo: o texto das linhas deve vir de dados reais. Deixar o modelo gerar horários ou preços é pedir por um erro caro.
• Confiar cegamente no identificador: trate o que chega do webhook como entrada a validar, e o texto livre como entrada não confiável. Um cliente pode escrever instruções disfarçadas de pedido, e a prática de defesa contra isso está descrita no guia da OWASP sobre prevenção de prompt injection.
• Botão antigo, ação nova: um cliente pode tocar numa mensagem de dias atrás. Associe cada interação a um estado da conversa e rejeite escolhas que não fazem mais sentido.
• Dados pessoais em excesso: peça só o necessário para a ação. Em termos de LGPD, defina finalidade, base legal e retenção do histórico, e consulte as orientações da ANPD. Se a decisão automatizada afetar o cliente de forma relevante, vale conhecer o direito de revisão em decisões automatizadas na LGPD.
• Ausência de saída humana: uma lista sem "falar com uma pessoa" transforma conveniência em frustração.

Como aplicamos o método: mapear, limitar, pilotar, transferir

O método que usamos em projetos de agentes de IA no WhatsApp se aplica diretamente a esse tema. Primeiro, mapear: entender o processo atual, quais mensagens chegam e onde há mais ida e volta por falta de clareza. Depois, limitar: definir quais dados e quais ações o agente pode tocar, e quais opções ele pode oferecer. Em seguida, pilotar: escolher um fluxo real, com registro das conversas e um critério de sucesso combinado antes (por exemplo, menos mensagens para concluir a tarefa ou menos correções feitas por pessoas). Por fim, transferir: manter a passagem para um atendente humano e decidir, com os registros em mãos, se vale expandir, ajustar ou parar. Para comparar o piloto com o ponto de partida, o guia de como medir um piloto de automação com IA ajuda a definir métricas e pontos de decisão.

Perguntas frequentes

Botões e listas funcionam fora da janela de atendimento? Em geral, mensagens interativas livres são enviadas dentro da janela de atendimento aberta pelo cliente. Para iniciar contato fora dela, é preciso usar templates aprovados, que podem incluir botões de resposta rápida. Confira as regras vigentes na documentação da Meta e trate o consentimento do cliente com cuidado.

A IA pode gerar as opções da lista sozinha? Não é recomendável para dados que têm consequência, como horários, prazos e valores. As opções devem vir de uma fonte confiável, como agenda ou catálogo, e o modelo decide apenas quando e como apresentá-las. Assim o cliente nunca escolhe algo que não existe.

Botões substituem o texto livre no atendimento? Não. Eles funcionam melhor como complemento: o texto livre captura o contexto e a intenção, e os botões fecham a decisão com precisão. Se o cliente ignorar o menu e escrever, o agente precisa continuar a conversa normalmente ou transferir para uma pessoa.

Como saber se as mensagens interativas melhoraram o atendimento? Compare o fluxo antes e depois com o mesmo critério definido no início do piloto, como quantidade de mensagens até concluir a tarefa, correções feitas por atendentes e conversas transferidas. Revise uma amostra das conversas com os registros de decisão. Se o ganho não aparecer, ajuste as opções ou volte ao texto livre naquele ponto.

Fontes

• Anthropic: Building effective agents
• OWASP: prompt injection prevention
• ANPD: Autoridade Nacional de Proteção de Dados
• Anthropic: Writing effective tools for agents