A maioria dos "agentes de IA no WhatsApp" que eu vejo por aí nunca sai da demo. Funciona no vídeo do LinkedIn, responde bonito no ambiente controlado — e desaba no primeiro contato com cliente real. Este post é o oposto disso: é o que eu aprendi colocando agentes de verdade no ar, atendendo, vendendo e resolvendo 24 horas por dia.
Se você quer um bot pra postar, não precisa ler. Se você quer um agente que aguenta produção, senta que lá vem.
Antes de tudo: você precisa da WABA, não do WhatsApp comum
Existe uma diferença que derruba 90% dos projetos logo no começo. O WhatsApp que você usa no celular — e até o WhatsApp Business do app — não é feito para automação em escala. A ferramenta certa é a WhatsApp Business API (WABA), a API oficial da Meta.
Com a WABA você ganha três coisas que não existem no app:
- Envio e recebimento programático via webhook e endpoints REST, sem depender de um celular ligado.
- Múltiplos atendentes e automação no mesmo número, sem a limitação de sessão única.
- Templates aprovados para iniciar conversas de forma legítima (mais sobre isso já já).
O caminho não-oficial — bibliotecas tipo Baileys que emulam o WhatsApp Web — funciona pra protótipo, mas é uma bomba-relógio: banimento de número, quebra a cada atualização do protocolo, zero garantia. Para qualquer coisa séria, é WABA. Ponto.
A janela de 24 horas: a regra que mais gente ignora
Aqui está o conceito que separa quem entende de quem só leu a documentação por cima.
A Meta divide as mensagens em dois mundos:
- Dentro da janela de 24h — depois que o cliente te manda uma mensagem, abre uma janela de 24 horas em que você pode responder livremente, com texto, mídia, o que quiser. É a conversa "de serviço".
- Fora da janela — passou 24h sem mensagem do cliente, ou você quer ser o primeiro a falar? Aí você só pode iniciar com um template aprovado (HSM — Highly Structured Message).
Ignorar isso é a causa nº1 de "minha mensagem não chega". Não é bug, é regra. Seu agente precisa saber em que estado a conversa está e escolher entre resposta livre e template — automaticamente.
Na prática, eu modelo isso como uma máquina de estados simples por contato:
NOVA → só template pode abrir
ABERTA_24H → resposta livre liberada (guardo o timestamp da última msg do cliente)
EXPIRADA → voltou pra template
Cada mensagem recebida no webhook renova o timestamp. Antes de qualquer envio proativo, eu checo a janela. Simples, mas é o que mantém a operação viva.
Templates HSM: onde a burocracia encontra a conversão
Todo template que inicia conversa precisa ser aprovado pela Meta antes de rodar. Eles têm categorias (marketing, utility, authentication) e a categoria muda o preço e a tolerância a rejeição.
O que eu aprendi no couro:
- Escreva o template pensando na aprovação, não só no cliente. Promessa vaga, gatilho de urgência exagerado e "clique aqui" solto derrubam a aprovação. Utility bem escrito passa fácil.
- Variáveis são posicionais (
{{1}},{{2}}). Documente o que cada uma significa no seu código, porque seis meses depois você não vai lembrar. - Tenha fallback de template. Se um template for pausado por qualidade, sua operação não pode parar. Eu mantenho variações aprovadas de reserva.
A qualidade do número (o famoso quality rating verde/amarelo/vermelho) sobe e desce conforme os clientes marcam como spam ou bloqueiam. Template ruim derruba o rating, rating ruim derruba o limite de envio. É um ciclo — e ele te obriga a ser relevante.
A arquitetura mínima de um agente que aguenta produção
Um agente de WhatsApp que funciona de verdade não é "webhook → OpenAI → resposta". Essa versão ingênua quebra no primeiro cliente que manda três mensagens seguidas, um áudio e uma foto. A arquitetura real tem camadas:
1. Ingestão (webhook) Recebe o payload da Meta, valida a assinatura, e — isto é crucial — responde 200 na hora. O processamento é assíncrono, numa fila. Se você processar de forma síncrona, a Meta reenvia o webhook achando que falhou, e você processa a mesma mensagem duas vezes.
2. Normalização Texto, áudio, imagem, documento, localização, botão clicado — tudo vira um formato interno único. Áudio passa por transcrição (STT) antes de chegar no LLM. O agente não deveria saber nem se importar se a origem foi voz ou texto.
3. Agregação de mensagens (debounce) Cliente real não manda um parágrafo. Ele manda "oi", depois "queria saber", depois "sobre o plano de vocês" — três webhooks em cinco segundos. Se você responder cada um, o agente parece um esquizofrênico. Eu junto mensagens numa janela curta (uns 3–8 segundos de silêncio) antes de acionar o LLM. Muda tudo na naturalidade.
4. O cérebro (LLM + contexto + ferramentas) Aqui mora a inteligência: histórico da conversa, dados do cliente (do CRM/ERP), e as ferramentas que o agente pode chamar — consultar um pedido, abrir um chamado, agendar visita. O LLM não é o produto; ele é o orquestrador que decide qual ferramenta usar.
5. Entrega Escolhe janela vs. template, respeita rate limits, e registra tudo. Status (enviado/entregue/lido/falhou) volta por webhook e alimenta a lógica.
Fallback de LLM: o dia que o provedor cai (e ele cai)
Se seu agente depende de um único provedor de LLM, ele tem a disponibilidade do elo mais fraco. Provedores caem, ficam lentos, retornam erro 529. Em produção, com clientes esperando resposta em segundos, isso é inaceitável.
Eu rodo com fallback em cascata: um modelo primário, e se ele falhar ou estourar o timeout, cai automaticamente pro secundário, depois pro terciário — de provedores diferentes. O cliente nunca sabe. A regra é: nenhum ponto único de falha na resposta.
Isso também me dá liberdade de otimizar custo: modelo mais barato para intenções simples, modelo mais capaz só quando a conversa exige raciocínio. A maior parte das mensagens é "qual meu boleto?" — não precisa do modelo topo de linha pra isso.
Ferramentas (tools): onde o agente para de ser papo e vira produto
Um agente que só conversa é um chatbot melhorado. Um agente que age é software. A diferença são as ferramentas.
No meu call center de IA para provedores, o agente não "fala sobre" a segunda via — ele consulta o ERP, gera o boleto e manda o PIX dentro da conversa. Ele não "explica como abrir um chamado" — ele abre. Isso exige conectar o LLM às APIs reais do negócio (CRM, ERP, gateway de pagamento) via function calling, com validação rigorosa de cada chamada.
Regra de ouro: toda ferramenta que muda estado no mundo real precisa de confirmação explícita e log. O LLM pode alucinar; a camada de ferramentas não pode. Ela valida, confirma com o cliente quando o passo é irreversível, e registra tudo.
O que separa demo de produção — o resumo honesto
- Idempotência: a mesma mensagem vai chegar duas vezes. Trate por
message_id. - Observabilidade: se você não loga cada decisão do agente, você não debuga nada. Correlation ID por conversa, do webhook à resposta.
- Human handoff: o agente precisa saber a hora de passar pra um humano — e passar com o contexto inteiro, não jogando o cliente pro início.
- Custo por conversa: meça. Um agente descontrolado chamando o modelo caro em loop queima orçamento sem você ver.
- Resiliência: fila, retry, fallback. Produção não perdoa "ah, o provedor caiu".
Comece pelo problema, não pela tecnologia
O erro mais comum não é técnico. É construir o agente antes de saber o que ele resolve. Eu sempre começo pela pergunta: qual conversa, repetida mil vezes por mês, está consumindo o time humano? É ali que a IA paga por si. Segunda via, status de pedido, agendamento, dúvida recorrente. Automatize a conversa que já acontece — não a que você imagina que vai acontecer.
Um agente de WhatsApp em produção não é um projeto de IA. É um produto de negócio que por acaso usa IA no núcleo. Trate assim e ele vai pro ar. Trate como demo e ele fica na demo.
Construo agentes de IA e produtos conversacionais em produção — do diagnóstico ao deploy. Se você tem uma operação no WhatsApp que precisa escalar sem contratar mais gente, me chama.