O que é a Evolution API?
A Evolution API é um software open-source que conecta um número de WhatsApp a sistemas próprios, como CRM, agente de IA ou site. Ela oferece uma API para enviar e receber mensagens e mídias e encaminha cada evento recebido para um webhook seu. Você hospeda no seu servidor, sem mensalidade de plataforma.
Na prática, ela funciona como uma ponte. De um lado fica o WhatsApp, conectado por QR Code como no WhatsApp Web; do outro, o seu código, que recebe as mensagens, decide o que responder e envia a resposta de volta pela mesma API. É essa ponte que permite colocar um agente de IA para atender leads no WhatsApp.
Por ser open-source, a Evolution API é popular no Brasil entre agências, desenvolvedores e quem monta automações de atendimento. A contrapartida é que ela não é a API oficial da Meta, o que traz cuidados específicos de uso, explicados mais adiante neste guia. Entender esses cuidados antes de começar evita perder o número no meio da operação e ter de refazer a configuração.
- Software open-source e gratuito; o custo é a hospedagem.
- Conecta o número por QR Code, como o WhatsApp Web.
- Envia e recebe mensagens, mídias e eventos por API.
- Entrega cada mensagem recebida a um webhook do seu sistema.
Como a Evolution API funciona na prática
O fluxo começa com a instalação da Evolution API num servidor, normalmente em containers Docker. Depois você cria uma instância, que representa um número de WhatsApp, e conecta esse número lendo o QR Code com o celular. A partir daí, a instância fica ativa e pronta para enviar e receber mensagens.
Cada mensagem que chega gera um evento enviado ao webhook que você configurou, um endereço do seu backend que recebe os dados em tempo real. O backend processa a mensagem, por exemplo enviando o texto para um modelo de IA, e devolve a resposta chamando a API da instância. Todo o ciclo acontece em poucos segundos.
- Instalação: servidor próprio, geralmente com Docker.
- Instância: cada número de WhatsApp conectado.
- Webhook: endereço que recebe os eventos em tempo real.
- Resposta: o seu sistema chama a API para enviar a mensagem de volta.
Evolution API vs API oficial do WhatsApp Business
A dúvida mais comum é escolher entre a Evolution API e a API oficial do WhatsApp Business, oferecida pela Meta. As duas permitem automatizar o WhatsApp, mas têm propostas diferentes: uma é software livre, flexível e sem custo por conversa; a outra é homologada, com regras de template e cobrança definidas pela Meta.
Não existe uma resposta única. Para um agente que responde quem chamou você, a Evolution API costuma resolver com custo menor. Para disparos ativos em escala e operações que precisam de máxima estabilidade e conformidade, a API oficial é o caminho correto. A escolha depende do tipo de uso, do volume esperado e de quanto risco operacional a empresa aceita assumir.
- Custo — Evolution API: software gratuito, você paga só a hospedagem; API oficial: cobrança definida pela Meta conforme o tipo de conversa.
- Conformidade — Evolution API: não é oficial e exige uso cuidadoso; API oficial: homologada pela Meta.
- Disparo ativo — Evolution API: não recomendada para envio em massa; API oficial: permitido com templates aprovados.
- Flexibilidade — Evolution API: controle total da infraestrutura; API oficial: segue as regras e os limites da plataforma.
- Uso ideal — Evolution API: atendimento a quem pediu contato; API oficial: escala e campanhas dentro das regras.
Como instalar e configurar a Evolution API, passo a passo
A instalação exige um servidor com acesso à internet, onde a Evolution API roda em Docker junto com um banco de dados. A documentação oficial do projeto traz os arquivos de configuração e as variáveis necessárias. Quem não tem experiência com servidores pode pedir ao Claude Code para conduzir a instalação, explicando cada comando antes de executar.
Depois de instalada, a configuração segue sempre a mesma lógica: criar a instância, conectar o número, apontar o webhook e testar. O teste é a etapa mais negligenciada: mande mensagens reais de outro número e confira se o evento chega ao backend e se a resposta volta antes de ligar qualquer automação para clientes.
- 1. Prepare um servidor com Docker e siga a documentação oficial do projeto.
- 2. Defina a chave de acesso da API e guarde-a fora do código.
- 3. Crie uma instância e conecte um número dedicado pelo QR Code.
- 4. Configure o webhook apontando para o seu backend.
- 5. Teste com mensagens reais de outro número antes de ligar a automação.
Evolution API com agentes de IA
O uso mais comum hoje é como canal de um agente de IA. A Evolution API recebe a mensagem, o backend envia o texto para um modelo como Gemini, OpenAI ou Anthropic junto com as instruções do agente, e a resposta volta para o cliente pelo WhatsApp. O agente pode qualificar o lead, tirar dúvidas e enviar o link de pagamento.
Montar essa integração do zero envolve backend, prompt, histórico de conversa e regra de passagem para humano. O Claude Code encurta o caminho: você descreve o comportamento do agente em português e ele cria o webhook, o backend e as instruções, pedindo aprovação antes de cada alteração. Alunos da ZX LAB já aplicam esse modelo: Bruno A. colocou um agente de IA no WhatsApp qualificando leads para um cliente do ramo imobiliário.
- Evolution API como canal: recebe e envia as mensagens.
- Backend leve, como um Cloudflare Worker ou uma Supabase Edge Function, chama o modelo de IA.
- O modelo de IA interpreta a mensagem e segue as instruções do agente.
- Uma regra de fallback chama uma pessoa da equipe quando necessário.
Limites, cuidados e risco de banimento
Por não ser a API oficial, a Evolution API exige disciplina. Usá-la para spam ou para disparo em massa a pessoas que nunca falaram com você é o caminho mais rápido para ter o número restrito ou banido pelo WhatsApp. O risco se concentra no uso abusivo, e não no atendimento de quem pediu contato.
Outros cuidados são operacionais. A instância pode desconectar e precisa de monitoramento; o software precisa ser atualizado; e a chave de acesso da API deve ficar protegida, porque quem tem essa chave consegue enviar mensagens pelo seu número. Um número banido precisa ser trocado, então nunca use o seu número pessoal.
- Nunca use o número pessoal; separe um número dedicado.
- Evite disparo em massa não solicitado e foque em quem pediu contato (opt-in).
- Monitore a conexão da instância e mantenha o software atualizado.
- Proteja a chave de acesso da API e o endereço do webhook.
Quanto custa e quando não usar a Evolution API
O software é gratuito. O custo vem da hospedagem, que pode ser um servidor simples ou a mesma máquina que já roda outros serviços, e do modelo de IA, se houver um agente conectado. Com o plano gratuito do Gemini, dá para validar o agente antes de pagar por API, e o gasto cresce junto com o volume de conversas.
A Evolution API não é a melhor escolha para todos os casos. Se você precisa enviar campanhas ativas em escala, se a empresa exige conformidade formal com a Meta ou se não há ninguém para monitorar a instância, a API oficial do WhatsApp Business tende a ser mais adequada, mesmo com custo por conversa.
- Software: gratuito e open-source.
- Hospedagem: servidor próprio, com custo que varia conforme a estrutura.
- Não use para campanhas de disparo ativo em massa.
- Prefira a API oficial quando conformidade formal e escala forem requisitos.
WhatsApp Oficial: Automatize Disparos em Massa com IA (Meta API)
A ZX LAB usa a Evolution API, auto-hospedada, como parte da infraestrutura que conecta agentes de IA ao WhatsApp na própria operação: os leads de tráfego pago são respondidos em segundos e passam para o vendedor só quando a qualificação está completa. Rafael Castro, fundador da ZX LAB, usa o Claude Code para montar e ajustar esses agentes e ensina o método aos mais de 15 mil alunos da escola.