Como montar um agente de IA no WhatsApp

1. Escolha o caminho de acesso ao WhatsApp

Existem três caminhos: Cloud API direto com a Meta, um BSP (provedor oficial) ou bibliotecas não oficiais que automatizam o WhatsApp Web. O terceiro é tentador porque é grátis e rápido, e é exatamente o que derruba o número da empresa. Não use em operação séria.

Cloud API direta dá menor custo e controle total, exigindo que você cuide de verificação de negócio, webhooks e infraestrutura. BSP resolve onboarding e suporte com um markup por conversa. Para quem já tem time técnico, Cloud API direta é o padrão.

2. Webhook: receber sem perder mensagem

A Meta entrega eventos por webhook HTTPS e reenvia quando você não responde rápido. O handler precisa validar a assinatura, responder 200 imediatamente e processar em fila. Processar de forma síncrona gera timeout, reentrega e resposta duplicada pro cliente.

Guarde o identificador da mensagem e descarte duplicatas: a entrega é ao menos uma vez, não exatamente uma vez.

export const POST = async ({ request }) => {
  const raw = await request.text();
  if (!verificarAssinatura(raw, request.headers.get("x-hub-signature-256"))) {
    return new Response("assinatura inválida", { status: 401 });
  }
  const evento = JSON.parse(raw);
  const msg = evento.entry?.[0]?.changes?.[0]?.value?.messages?.[0];
  if (msg && !(await jaProcessada(msg.id))) {
    await fila.enfileirar({ id: msg.id, de: msg.from, tipo: msg.type, msg });
  }
  return new Response("ok"); // sempre 200, sempre rápido
};

3. Debounce: gente escreve em rajada

No WhatsApp o usuário manda "oi", depois "queria saber", depois "do plano de vocês" em três mensagens. Responder cada uma gera três respostas atropeladas e triplica o custo.

A solução é uma janela de agrupamento de 3 a 8 segundos por contato: acumula, reinicia o contador a cada nova mensagem e só então chama o agente com o bloco inteiro. Junto com isso, indicador de digitando e um lock por conversa pra impedir duas execuções simultâneas do mesmo contato.

4. Janela de 24 horas, templates e custo

Depois de uma mensagem do cliente, você tem 24 horas pra responder livremente. Fora dessa janela, só templates aprovados previamente. Isso muda o desenho do produto: follow-up, lembrete e retomada de conversa precisam de template cadastrado e categoria correta.

A cobrança da Meta é por conversa iniciada, variando por categoria — serviço, utilidade, marketing e autenticação. Some isso ao custo de tokens do agente e você chega ao custo real por atendimento, que é o número a comparar com o custo do atendente humano.

• Templates: submeta cedo, aprovação leva de horas a dias e reprovação é comum por texto promocional.
• Nunca dispare marketing em lista fria — é o caminho mais rápido pra qualidade baixa e restrição no número.
• Registre o horário da última mensagem do contato pra saber, a qualquer momento, se a janela está aberta.

5. Áudio, imagem e documento

No Brasil, áudio é a norma. O agente precisa baixar a mídia autenticada pela API, transcrever e tratar o texto como entrada normal. Imagens costumam ser comprovante, print de erro ou foto de produto — vale rodar visão só quando o fluxo exige, porque custa mais.

Guarde a mídia na sua infra: as URLs da Meta expiram, e você vai precisar do arquivo no histórico de atendimento.

6. Handoff humano sem perder contexto

Todo agente de WhatsApp precisa de uma porta de saída: pedido explícito do cliente, tema sensível (jurídico, financeiro, reclamação séria), baixa confiança ou repetição de falha. No handoff, o agente para de responder aquele contato, marca a conversa como humana e entrega resumo, dados coletados e histórico pro atendente.

Defina também o caminho de volta: quem devolve a conversa pro agente, quando e o que o agente já pode assumir como sabido.

7. Integração com CRM e sistemas internos

O valor não está na conversa, está no que ela grava. Cada atendimento deve produzir contato identificado, campos qualificados, estágio de funil e evento no CRM. As mesmas regras de ferramenta valem aqui: escopo por tenant no servidor, idempotência na escrita e log auditável.

É o que transforma o agente de "chatbot simpático" em um canal com número de conversão comparável ao do time comercial.

8. Métricas que importam

Acompanhe taxa de resolução sem humano, tempo até a primeira resposta, taxa de handoff, custo por conversa resolvida e conversão pra reunião ou venda. Métrica de "mensagens enviadas" não diz nada.

Monitore também a qualidade do número na plataforma da Meta: queda de qualidade antecede limite de envio, e limite de envio derruba a operação.