aqui no Ratos de IA (o canal no YouTube, a newsletter e os cursos de IA que a gente faz junto com a DobraLabs, nosso laboratório de tecnologia e IA), o whatsapp é peça central: é onde chegam alunos, leads e o grupo da comunidade. e foi por ele que a gente aprendeu a lição mais cara sobre a evolution api. se tu quer ligar o teu whatsapp num agente de ia, essa é a história que eu queria ter lido antes.
a gente tomou um soft-ban (um bloqueio parcial e silencioso do número) no nosso número em julho de 2026, mandando mensagem de boas-vindas em massa pela evolution api. e o pior nem foi o bloqueio: a api continuava respondendo “enviado”, com id de mensagem e tudo, enquanto o whatsapp rejeitava a entrega em silêncio. a evolution api é um programa de código aberto que liga um número de whatsapp num servidor, como se fosse um whatsapp web, pra automação e agente de ia conversarem com ele. ela é ótima pra ler conversa, ouvir áudio e resumir grupo, e arriscada pra disparar mensagem pra lista. abaixo tem o que é, a diferença pra api oficial, o que a gente aprendeu tomando ban e o jeito que a gente usa hoje.
o que é a evolution api
a evolution api se descreve como uma API REST de código aberto pra whatsapp e outros canais de mensagem, mantida pela Evolution Foundation. na prática, tu instala ela num servidor, lê um QR code com o celular (igual tu faz pra abrir o whatsapp web) e pronto: as mensagens que chegam nesse número ficam disponíveis pra qualquer programa que fale com a api. inclusive o teu agente.
alguns detalhes que estão no próprio repositório:
- a opção grátis usa a biblioteca Baileys, que funciona em cima do whatsapp web. o README avisa que ela “pode ter limitações em comparação com as APIs oficiais”.
- ela também conecta na Cloud API oficial da meta, e aí o aviso é outro: vale a política da meta e pode ter custo por mensagem.
- tem integração pronta com Typebot e Chatwoot, e usa a OpenAI pra transformar áudio em texto.
- a licença é Apache 2.0, com condições extras de marca.
pra quem não sabe, API é a porta que um programa abre pra outro programa conversar com ele. sem a evolution, o teu agente não tem como “entrar” no whatsapp; com ela, ele lê o grupo como tu leria.
evolution api ou api oficial do whatsapp: a diferença
o whatsapp tem uma api oficial, a WhatsApp Cloud API, que é da meta e é feita pra empresa mandar mensagem em escala. as duas resolvem problemas diferentes:
| evolution api (Baileys) | WhatsApp Cloud API (oficial) | |
|---|---|---|
| como conecta | teu número como um whatsapp web, por QR code | número registrado na plataforma da meta |
| custo | grátis (tu paga só o servidor) | por mensagem entregue, por categoria e país |
| mensagem ativa pra cliente | sem regra formal, e é aí que mora o risco de ban | só com modelo de mensagem aprovado pela meta |
| ler grupo | lê | não é o caso de uso dela |
| risco de bloqueio | existe, maior se dispara em massa | baixo, se segue as regras |
| melhor pra | ler, resumir, transcrever áudio, uso interno | boas-vindas de compra, aviso, atendimento em escala |
sobre o custo da oficial: segundo a página de preços da meta, a cobrança é por mensagem entregue desde 1º de julho de 2025, conforme a categoria (marketing, utilidade, autenticação, serviço) e o país do contato. e desde 1º de outubro de 2026 as mensagens de serviço voltaram a ser cobradas, com 1.000 grátis por mês pra cada número.
o risco de ban, contado por quem tomou
os termos de serviço do whatsapp proíbem, com essas palavras, “mensagens em massa, mensagens automáticas, discagem automática e afins”, e qualquer uso “por meios automatizados” não autorizado. a evolution, no modo Baileys, é exatamente um meio automatizado não oficial. então o ban é sempre uma possibilidade, e o tamanho do risco depende do que tu faz com ela.
o nosso caso: a gente usava a evolution pra mandar a mensagem de boas-vindas pra quem comprava curso. cada compra, uma mensagem automática pra um número que nunca tinha falado com o nosso, e com o volume de vendas isso virou boas-vindas em massa. o número tomou soft-ban em julho de 2026. o que doeu foi o silêncio: a api respondia “enviado” com id de mensagem, e o whatsapp rejeitava a entrega. durou mais de 4 dias, e reiniciar ou recriar a conexão não resolveu.
o que a gente fez:
- boas-vindas foram pra api oficial. desde 15 de julho de 2026, a mensagem sai pela Cloud API, de um número só de disparo, com modelo aprovado pela meta. um detalhe que custou caro: modelo comum não aceita senha nem código (a meta joga pra categoria de autenticação e rejeita), então a mensagem manda uma “chave de entrada” e os detalhes vão por e-mail. e número brasileiro precisa do 9º dígito.
- a evolution ficou só pra leitura. é o uso em que ela brilha.
no episódio 41 do Ratos de IA (o vídeo semanal do canal com as novidades de IA), eu resumi do jeito que a gente pensa: “a gente usa pra ler e, quando precisa mandar mensagem ativamente pra contatos, aí sim usa a API oficial e paga lá pro WhatsApp pra não ter problemas”. e o aviso de sempre: conectar API não oficial no teu whatsapp é por tua conta e risco.
o que a gente faz com a evolution hoje (só leitura)
ler é onde a evolution economiza mais tempo. uns usos reais nossos:
“lê o que o fulano falou no grupo”. a gente tem uma skill (um pacote de instruções que ensina o agente a fazer uma tarefa específica) que conecta o Claude e o Codex nos nossos whatsapps. aí dá pra pedir “lê o que o cliente mandou ontem e me ajuda a responder”, e o agente lê, ouve o áudio e conversa em cima, sem ninguém ficar tirando print.
resumo diário do grupo da Comunidade. todo dia às 7h, uma automação lê as últimas 24 horas do grupo da Comunidade Ratos (o grupo dos nossos alunos), transcreve os áudios com o Whisper (o modelo de transcrição de áudio da OpenAI), e o Claude separa o que foi conversa, o que foi material (prompt, skill, arquivo) e o que ensinou alguma coisa. sai um resumo de volta no grupo, e os materiais vão pro repositório da Comunidade na plataforma, onde dá pra consultar depois.
um rato pra marcar nos grupos. a gente tem um número só pra isso, ligado na evolution e na Ratoeira, o portal que a gente fez pra rodar Claude Code, Codex e Grok num servidor pelo navegador. quando alguém reporta um bug no grupo de quem está testando a Ratoeira, eu marco esse número na mensagem ou encaminho pra ele, e isso abre uma conversa de investigação na Ratoeira. depois eu só volto quando o sino de notificações da Ratoeira avisa que tem resposta.
lead que chegou pelo zap. o nosso CRM lê os whatsapps ligados e a IA separa o que é lead do resto da conversa, avisando o time por e-mail.
repara que nenhum desses manda mensagem pra lista. o mais perto disso é o resumo, que vai pro próprio grupo uma vez por dia.
as receitas da Comunidade
a gente transformou esse caminho em receitas: um passo a passo escrito pro teu agente, que tu manda pro Claude Code ou pro Codex (os agentes de programação da Anthropic e da OpenAI, que rodam comandos no teu computador ou servidor) e ele te guia, uma etapa por vez. estão na Comunidade Ratos:
- ler whatsapp com evolution api na VPS. o agente instala a evolution numa VPS tua (servidor alugado que fica ligado o tempo todo; Ubuntu 24.04 limpo, 2 GB de memória ou mais), junto com um banco Postgres pras conversas, um Redis de cache e um porteiro que cuida do HTTPS. são 6 etapas, uns 20 minutos. a receita só termina quando o agente leu, de verdade, uma mensagem que chegou no teu número. e tem regra escrita pro agente: nunca disparar mensagem em lote, e mensagem avulsa só com o teu ok pra aquela mensagem.
- resumo diário do grupo de whatsapp. roda na mesma VPS e manda, todo dia num horário, o resumo do grupo: os assuntos, o que foi combinado, as perguntas que ficaram sem resposta e o que foi dito nos áudios. quem lê e escreve é o Gemini, no plano grátis. a receita avisa antes: no plano grátis o Google pode usar o conteúdo pra melhorar os produtos dele, então grupo com dado de cliente ou paciente vai melhor no plano pago, que custa centavos por resumo.
- atendente de whatsapp com ia. pluga na evolution da primeira receita, tem modo simulação pra testar sem responder ninguém de verdade e aprende com a equipe. esse responde quem chamou, que é bem diferente de disparar pra lista.
e se tu não quer servidor
nem todo mundo precisa da evolution. se o objetivo é só o teu agente ler o teu whatsapp no teu computador, tem caminho mais leve:
- no Mac: a skill whatsapp no mac lê o cache que o aplicativo do whatsapp salva numa pasta local, transcreve os áudios na tua máquina e te diz o que o cliente pediu. não conecta nada em servidor nenhum.
- wacli: uma ferramenta de linha de comando, feita em Go, mais leve que a evolution, que a gente comentou no episódio 41. também é não oficial, então vale o mesmo cuidado.
e se a ideia é automatizar o que acontece depois de ler (salvar lead, mandar pra planilha, abrir tarefa), vale ler o post sobre n8n ou agente de ia antes de escolher a ferramenta. pra visão de negócio, a DobraLabs escreveu sobre o agente pessoal da meta no whatsapp e o que isso muda pro atendimento.
em uma frase
a evolution api é a forma mais simples de dar whatsapp pro teu agente de ia, e ela é ótima enquanto tu usa pra ler, ouvir e resumir. na hora de mandar mensagem pra quem não te chamou, troca pra api oficial e paga a meta: o ban que a gente tomou ensinou isso do jeito caro.