São 22.200 buscas por “evolution api” todo mês no Brasil, e quase nenhuma vem de curiosidade acadêmica. Quem digita isso está montando uma operação de WhatsApp: um SaaS de atendimento, uma agência conectando clientes, um time comercial cansado de responder tudo na mão. A Evolution API virou a porta de entrada padrão desse mundo porque é gratuita, aberta e resolve em uma tarde o que a burocracia da API oficial parece levar semanas para liberar. O que quase ninguém conta é o que acontece depois da tarde em que tudo funcionou.
TL;DR: A Evolution API é uma API REST open source (licença Apache 2.0) para integrar WhatsApp a sistemas, CRMs e automações. Ela opera em dois modos: via Baileys, que simula o WhatsApp Web por engenharia reversa e é gratuito, e via Cloud API oficial da Meta, que é a conexão homologada. O modo Baileys é o mais usado e o mais frágil: o próprio repositório oficial avisa que ele “depende da versão web do WhatsApp e pode ter limitações”. O custo real não está na licença, e sim na VPS, na manutenção e no risco de banimento do número. Para operação comercial séria, o caminho maduro em 2026 é a API oficial, que no modo coexistência mantém o aplicativo do celular funcionando junto.
Neste guia: o que é · como funciona por dentro · os dois modos de conexão · o que dá para construir · instalação em 6 passos · custo real · é oficial? · segurança e LGPD · comparativo · coexistência · problemas comuns · erros de arquitetura · um cenário completo · glossário
O que é a Evolution API?
A Evolution API é uma API REST brasileira e open source que expõe o WhatsApp para outros sistemas: você sobe o serviço em um servidor, cria uma instância, conecta um número e passa a enviar e receber mensagens por chamadas HTTP e webhooks. O repositório oficial do projeto (2026) a descreve como uma API “pronta para produção” para WhatsApp e outros canais, licenciada sob Apache 2.0 com condições adicionais de proteção de marca, construída em Node.js 20+ com TypeScript e banco PostgreSQL ou MySQL via Prisma.
Na prática, ela é o motor invisível de boa parte das automações de WhatsApp no Brasil: bots de atendimento, notificações de pedido, integrações com n8n, Chatwoot e Typebot, disparos de CRM. A diferença dela para uma plataforma pronta é a mesma diferença entre um motor e um carro: a Evolution API entrega o motor, e a carroceria, o painel e a manutenção ficam por sua conta.
Como a Evolution API funciona por dentro
Quem vai operar a ferramenta por meses ganha muito em entender as quatro peças que a compõem, porque todo diagnóstico futuro passa por saber qual delas falhou.
A primeira é a instância: a unidade básica da Evolution API, que representa um número de WhatsApp conectado. Cada instância guarda a própria sessão (as credenciais criptográficas que a plataforma da Meta reconhece como “um dispositivo pareado”), o próprio estado de conexão e as próprias configurações de integração. Um servidor roda quantas instâncias a memória aguentar, e é essa multi-instância nativa que fez a ferramenta dominar o uso em agências.
A segunda é a persistência: sessões, contatos e mensagens ficam no banco (PostgreSQL ou MySQL, via Prisma, conforme a ficha técnica do repositório). É por isso que backup de banco não é paranoia: perder o banco é perder as sessões, e perder as sessões é reconectar todos os números por QR code, um a um.
A terceira são os eventos: tudo o que acontece no número (mensagem recebida, status de entrega, conexão caiu, contato atualizado) vira um evento que a Evolution API empurra para fora por webhook, e opcionalmente por WebSocket ou fila (RabbitMQ) em ambientes maiores. A sua automação inteira é uma consumidora desses eventos; quando eles param, ela para junto, em silêncio.
A quarta são os endpoints: a interface REST pela qual os seus sistemas mandam ordens. Os grupos que você vai usar no dia a dia:
| Grupo de endpoints | O que faz | Uso típico |
|---|---|---|
| Instância | Criar, conectar (QR), status, reiniciar, logout | Provisionamento e monitoramento |
| Mensagem | Enviar texto, mídia, áudio, botões, listas, enquetes, reações | O coração da automação |
| Chat | Marcar como lido, presença (“digitando…”), arquivar, buscar histórico | Comportamento natural no atendimento |
| Grupo | Criar grupos, gerenciar participantes, convites | Comunidades e turmas (exclusivo do modo não oficial) |
| Integrações | Chatwoot, Typebot, webhook, WebSocket, RabbitMQ | Conectar o ecossistema sem middleware próprio |
Um detalhe de segurança que muita instalação ignora: a API inteira é protegida por uma chave (apikey) definida na configuração, e cada instância pode ter a sua. Quem tem a chave e a URL controla os seus números de WhatsApp, com tudo o que isso implica. Voltamos a esse ponto na seção de segurança e LGPD.
Os dois modos de conexão (e por que essa escolha define tudo)
A documentação do projeto distingue dois caminhos de conexão, e essa escolha define o risco da operação inteira.
O primeiro é o modo Baileys: uma biblioteca que reproduz o protocolo do WhatsApp Web por engenharia reversa (a relação exata entre biblioteca e produto está em Evolution API ou Baileys). Você escaneia um QR code, o servidor passa a se comportar como um “WhatsApp Web turbinado” e tudo funciona sem pagar nada à Meta. É o modo que popularizou a ferramenta, porque não exige cadastro empresarial, aprovação de templates nem cartão de crédito.
O segundo é o modo Cloud API: a Evolution API atua como camada de conveniência sobre a API oficial da Meta. Aqui o número está registrado na plataforma do WhatsApp Business, as mensagens seguem as regras e os preços oficiais, e não existe QR code envolvido.
O detalhe que muita gente descobre tarde: o aviso sobre o primeiro modo está no próprio repositório oficial da Evolution API (2026), que declara que o método Baileys “depende da versão web do WhatsApp e pode ter limitações em comparação com as APIs oficiais”. Quando o mantenedor do projeto escreve isso na página inicial, não é modéstia. É aviso de arquitetura: tudo que a Meta mudar no protocolo do WhatsApp Web quebra primeiro quem depende de engenharia reversa.
O que dá para construir com ela
O ecossistema é o ponto mais forte do projeto, e é honesto reconhecer isso. Com a Evolution API no ar, você conecta:
- n8n e Make, para automações visuais: um lead preenche formulário, recebe mensagem, cai no funil. O caminho detalhado está em como integrar a Evolution API ao n8n, e o fluxo de produção pronto em template de atendimento com n8n.
- Chatwoot, para transformar o número em uma caixa de entrada multiagente, integração que destrinchamos em Evolution API + Chatwoot.
- Typebot e construtores de fluxo, para bots de qualificação.
- Qualquer sistema próprio, via REST e webhooks: envio de mídia, botões, listas, presença (“digitando…”), grupos.
É um canivete suíço de verdade. A pergunta que separa o entusiasmo da operação madura não é “o que dá para fazer?”, e sim “o que acontece com tudo isso quando a conexão cai numa sexta-feira à noite?”.
Da instalação à primeira mensagem: o caminho em seis passos
O passo a passo abaixo é o esqueleto de qualquer instalação séria. Os nomes exatos de variáveis e comandos mudam entre versões, então trate isto como mapa e o repositório oficial como fonte da verdade da sua versão.
- Prepare a máquina. VPS com Docker e Docker Compose, 4 GB de RAM como piso confortável, domínio apontado e certificado TLS no proxy reverso. O dimensionamento honesto está em quanto custa a VPS.
- Suba a stack pelo Compose oficial. API, banco e Redis como serviços separados. Antes do primeiro start, defina no ambiente pelo menos: a chave de autenticação da API, a URL pública do servidor e a string de conexão do banco. Chave fraca aqui é porta aberta para o seu WhatsApp.
- Crie a instância via endpoint de criação (ou pelo manager, a interface administrativa que acompanha o projeto), dando a ela um nome que você não vai se arrepender de ver em log às 2h da manhã.
- Conecte o número: gere o QR code da instância e escaneie com o celular do número, como num pareamento de WhatsApp Web. Se o QR não vier, o diagnóstico em ordem de probabilidade está em Evolution API não gera QR code.
- Configure o webhook apontando para o consumidor (seu backend ou n8n), assinando apenas os eventos que vai usar, e valide com uma mensagem de teste real nos dois sentidos.
- Instale a rotina antes do primeiro cliente: backup agendado do banco, monitor de status com alerta e o registro da versão instalada. É a diferença entre operar e torcer.
Tempo realista para quem já conhece Docker: uma tarde, incluindo os testes. O erro clássico é parar no passo 4, com a primeira mensagem enviada e a euforia correspondente, e nunca executar o passo 6: a instalação sem rotina funciona perfeitamente até a primeira sexta-feira à noite.
Quanto custa a Evolution API de verdade?
A licença é gratuita. O custo mora em três lugares que não aparecem na página do GitHub.
Infraestrutura. A Evolution API precisa de um servidor rodando 24/7, com banco de dados e, em produção séria, Redis e proxy. Pegue como premissa de cálculo uma VPS intermediária de mercado no Brasil, na faixa de R$ 50 a R$ 150 por mês, mais o tempo de quem configura Docker, SSL, backup e monitoramento. Os números detalhados, com cenários por porte, estão em quanto custa manter a Evolution API.
Manutenção. Atualização de versão, incompatibilidade após release, instância que não gera QR code, webhook que para de responder. Cada um desses eventos consome horas de alguém técnico, e essas horas raramente entram na planilha de custo do projeto. Se a operação é de uma agência que atende clientes, essa conta multiplica pelo número de instâncias.
Risco. No modo Baileys, o número opera fora dos termos da plataforma. Banimento não é questão de “se”, é distribuição de probabilidade: volume alto, mensagens para contatos frios e denúncias de spam elevam a chance, como mapeamos em por que o WhatsApp bane números. O custo de um ban não é a multa que não existe; é o funil comercial parado e o histórico de conversas de clientes preso num número morto.
Do outro lado da balança, a API oficial cobra por mensagem desde 1º de julho de 2025 (atualização de preços publicada pela Meta), com mensagem de marketing no Brasil a US$ 0,0625, mensagens de utilidade gratuitas dentro da janela de atendimento de 24 horas e mensagens de serviço gratuitas desde novembro de 2024. Para a maioria das operações de atendimento e vendas, em que o cliente chama primeiro, a conta mensal da API oficial fica bem menor do que o folclore sugere.
Evolution API é oficial? É segura?
Resposta direta, do jeito que ela precisa ser dada: a Evolution API em si é um software legítimo e open source, mas o modo Baileys, que é o mais usado, não é uma conexão oficial nem homologada pela Meta. O modo Cloud API, dentro da mesma ferramenta, é oficial, porque quem responde pela conexão é a plataforma da Meta.
Sobre segurança, a distinção honesta tem duas camadas. A do software: o projeto é auditável, tem comunidade ativa e não há nada de malicioso nele. A da operação: um número conectado por engenharia reversa pode ser desconectado ou banido a qualquer atualização do protocolo, sem aviso e sem canal de recurso formal, porque não existe contrato entre você e a Meta cobrindo aquela conexão. Já escrevemos a análise completa dessa fronteira em Evolution API: riscos e alternativa oficial, e ela continua válida: o risco não está no código, está no modelo de conexão.
Segurança e LGPD: onde moram os dados (e as responsabilidades)
O argumento de venda do self-hosted é também a sua responsabilidade jurídica: as conversas dos seus clientes (e dos clientes deles, no caso de agências) ficam no seu banco, no seu servidor. Perante a LGPD, quem opera a instância assume papel de operador ou controlador desses dados pessoais, com o que a lei atribui a esses papéis: base legal para o tratamento, segurança adequada, resposta a titulares e comunicação de incidentes.
Quatro pontos concentram o risco prático. O primeiro é a apikey: quem a possui, junto com a URL, envia e lê mensagens em nome dos números conectados. Chave em repositório público, em log de n8n compartilhado ou em print de tutorial interno é o vazamento mais bobo e mais comum do ecossistema; rotacione periodicamente e restrinja o acesso por rede quando possível. O segundo são os logs: em modo verboso, conteúdo de mensagem vai parar em arquivo sem criptografia nem política de retenção; defina o nível de log de produção com essa consciência. O terceiro é o backup: banco com histórico de conversas precisa de backup criptografado e com acesso controlado, senão a cópia de segurança vira a segunda superfície de vazamento. O quarto é o contrato: agência que opera números de clientes deve refletir esse tratamento de dados no contrato e no aviso de privacidade do cliente final, porque na dúvida a responsabilidade sobe a cadeia até quem opera, tema que tratamos em API do WhatsApp e LGPD.
E existe o ponto desconfortável que fecha a seção: para clientes corporativos com área de compliance, a frase “os dados trafegam por uma conexão não homologada pela plataforma” costuma encerrar a conversa antes de qualquer criptografia ser discutida. Nesses contratos, a conexão oficial não é preferência técnica: é pré-requisito de procurement.
Comparativo: modo Baileys, Cloud API e plataforma pronta
| Critério | Evolution API (Baileys) | Evolution API (Cloud API) | Plataforma pronta com API oficial |
|---|---|---|---|
| Custo de licença | R$ 0 | R$ 0 + tarifas Meta por mensagem | Assinatura mensal + tarifas Meta |
| Infraestrutura | VPS própria, 24/7, por sua conta | VPS própria, 24/7, por sua conta | Inclusa, gerida pelo fornecedor |
| Risco de banimento | Real e permanente, sem canal de recurso | Baixo (regras oficiais) | Baixo (regras oficiais) |
| Estabilidade da conexão | Depende do protocolo web, quebra em atualizações | Estável (SLA da Meta) | Estável (SLA da Meta + suporte) |
| Manutenção técnica | Sua equipe | Sua equipe | Fornecedor |
| App do celular continua? | Sim (é a mesma sessão web) | Não no modo clássico; sim com coexistência | Sim, com coexistência nativa |
| Para quem faz sentido | Teste, projeto pessoal, validação | Dev com equipe própria | Operação comercial, agência, revenda |
A saída madura: API oficial com modo coexistência
Durante anos, o argumento imbatível contra migrar para a API oficial era prático: conectar o número na plataforma da Meta significava abrir mão do aplicativo no celular, e nenhum dono de operação aceita perder o WhatsApp de bolso. Esse argumento morreu. Segundo a documentação oficial da Meta para desenvolvedores (2025), o modo coexistência permite conectar um número do WhatsApp Business à Cloud API mantendo o aplicativo funcionando: o app segue para conversas do dia a dia, a API assume volume e automação, e o histórico fica sincronizado entre os dois, com importação de até 180 dias de conversas individuais no onboarding.
Há requisitos e limites documentados: aplicativo WhatsApp Business na versão 2.24.17 ou superior, número operando com vazão fixa de 20 mensagens por segundo, grupos fora da sincronização e recursos como listas de transmissão e mensagens temporárias desativados no número conectado. O passo a passo dessa decisão, incluindo quando ela não vale a pena, está em migrar da Evolution API para a API oficial com coexistência.
Aqui entra o nosso interesse declarado: o Cubo Suite é uma plataforma conversacional white label com CRM, automação e construtor de páginas, e tem integração nativa com a API oficial do WhatsApp nos dois formatos, o tradicional e o de coexistência. Nós vendemos exatamente a alternativa ao “faça você mesmo”. Por isso mesmo, a recomendação honesta tem limite: se o seu caso é um projeto pessoal, um estudo ou uma validação de ideia, a Evolution API em VPS barata é imbatível e você não precisa de plataforma nenhuma. A conta muda quando existe cliente pagando, meta de vendas ou marca de agência em cima da operação.
Problemas comuns: o que quebra com mais frequência
Três sintomas dominam os fóruns e os grupos de suporte do ecossistema, e cada um tem diagnóstico próprio:
- QR code que não aparece ou não conecta: quase sempre versão desatualizada, cache da instância ou incompatibilidade após release. Diagnóstico completo em Evolution API não gera QR code.
- Instância que desconecta sozinha: sessão web derrubada pelo servidor da Meta, celular âncora sem internet ou memória insuficiente na VPS. Causas e correções em Evolution API desconectando.
- Webhook mudo: eventos que param de chegar depois de atualização, geralmente por mudança de payload entre versões.
O padrão por trás dos três sintomas merece ser dito sem rodeio: nenhum deles é bug raro. São o custo recorrente de operar sobre um protocolo que não foi feito para isso.
Erros de arquitetura que custam caro (e não aparecem como bug)
Os problemas da seção anterior são técnicos e têm correção. Os cinco abaixo são decisões de desenho, invisíveis até o dia em que cobram, e recorrentes o suficiente para merecerem lista própria.
1. Tudo na mesma VPS. Evolution API, n8n, Chatwoot e banco dividindo 4 GB: economiza dezenas de reais e cria um ponto único de falha para a operação inteira. O reinício que resolve um serviço derruba os outros três, e o pico de mídia de um cliente estrangula o atendimento de todos.
2. O número principal como cobaia. Conectar o número comercial consolidado da empresa (ou do cliente) para “testar a automação” inverte a lógica de risco: o experimento roda justamente sobre o ativo que não pode cair. Teste em número descartável; promova a arquitetura, nunca o improviso.
3. Resposta automática sem trava de direção. O fluxo que responde a tudo, incluindo às próprias mensagens, produz a rajada infinita que já queimou reputação de muita operação no primeiro dia. A trava fromMe é a primeira linha de qualquer automação, como insistimos no template de atendimento.
4. Atualizar na sexta, sem backup, em produção. A combinação completa do desastre: mudança de payload entre versões, fim de semana pela frente e nenhum caminho de volta. Janela controlada, backup imediato antes, teste do caminho crítico depois. Sempre.
5. Tratar a instância como fonte da verdade. O histórico que só existe no banco da instância morre com o banimento ou a corrupção do banco. A fonte da verdade do relacionamento com o cliente deve morar num sistema de registro (CRM), com a instância como canal, nunca como arquivo.
Um cenário completo: a agência que cresceu com a ferramenta
Para amarrar o guia, um cenário declaradamente hipotético, com premissas explícitas, que condensa a trajetória que vemos se repetir. Pegue uma agência de marketing com 6 clientes ativos e um sócio técnico.
Mês 1: o sócio sobe a Evolution API numa VPS de R$ 90, conecta o número de um cliente piloto e integra ao n8n em um fim de semana (8 horas). O custo percebido é zero; o entusiasmo, total. Mês 3: seis números conectados, primeira onda coletiva de desconexões após mudança de protocolo. Cinco horas de plantão num sábado, seis clientes avisados um a um, tudo volta ao ar. A agência registra o incidente como azar. Mês 5: o número do cliente de maior faturamento é banido na véspera do lançamento dele. Análise solicitada pelo aplicativo, retorno em 24 horas, número recuperado; a campanha atrasa dois dias e a relação comercial nunca mais é a mesma. Mês 6: o sócio faz a conta que este guia propõe: infraestrutura mais 10 horas mensais de operação contra o custo de migrar os números críticos para a API oficial com coexistência, que preserva o aplicativo de cada cliente. Os cinco números com receita relevante migram; o de teste fica.
A moral do cenário não é “a ferramenta falhou”: tecnicamente, ela se comportou como o desenho prevê. É que o modelo de risco do modo não oficial não cabia dentro do contrato que a agência tinha com os clientes, e essa incompatibilidade só ficou visível no mês 5, o mês mais caro possível para descobri-la.
Glossário rápido
- Instância: unidade da Evolution API que representa um número de WhatsApp conectado, com sessão e configurações próprias.
- Baileys: biblioteca open source que implementa o protocolo do WhatsApp Web por engenharia reversa; base do modo gratuito.
- Sessão: credenciais criptográficas que fazem a plataforma reconhecer a instância como dispositivo pareado; morrem no logout, no ban ou na corrupção do banco.
- Pareamento (QR code): o vínculo entre o celular do número e a instância, idêntico ao do WhatsApp Web.
- Webhook: a entrega de eventos da instância para o seu sistema via HTTP; o sistema nervoso de qualquer automação.
- Cloud API: a API oficial do WhatsApp operada pela Meta, com registro empresarial, templates e tarifas publicadas.
- Coexistência: modalidade documentada pela Meta (2025) em que o número opera na Cloud API mantendo o aplicativo WhatsApp Business ativo, com histórico individual sincronizado.
- Janela de 24h: período após a última mensagem do cliente em que a empresa responde livremente na API oficial, sem template e sem custo.
- Template: mensagem pré-aprovada pela Meta, exigida para contato ativo fora da janela na API oficial.
A Evolution API funciona com a API oficial do WhatsApp?
Sim. Além do modo Baileys, o projeto suporta a Cloud API da Meta como canal de conexão. Nesse arranjo, a Evolution API vira uma camada de conveniência sobre a conexão oficial: as regras, os preços e a estabilidade passam a ser os da plataforma da Meta.
A Evolution API envia mensagens para grupos?
Sim: gestão e envio em grupos é recurso do modo Baileys, e um dos poucos exclusivos dele, porque a API oficial não cobre grupos (nem a coexistência os sincroniza, pela documentação da Meta). Operação dependente de grupos é o caso legítimo mais forte para permanecer no modo não oficial, com o risco correspondente.
Quantas instâncias cabem numa VPS?
Depende de RAM e do volume de mídia: como premissa prática, uma máquina de 4 GB opera confortavelmente poucas instâncias ativas (2 a 5, conforme o movimento); acima disso, os sintomas de saturação (QR que não gera, desconexões em pico) aparecem antes de qualquer monitor formal avisar.
A Evolution API tem painel de atendimento?
Ela inclui um manager administrativo para criar e conectar instâncias, não uma caixa de entrada de conversas. Atendimento com equipe exige acoplar uma interface (o Chatwoot é o par clássico) ou operar via integrações, e é aí que a stack começa a crescer.
Dá para conectar IA e agentes na Evolution API?
Sim: via n8n, Typebot e integrações do ecossistema, é comum acoplar modelos de linguagem para qualificação e resposta automática. A camada de IA herda a fundação sobre a qual roda: agente brilhante sobre conexão instável responde brilhantemente até a sessão cair.
Usar Evolution API pode banir meu número?
No modo Baileys, sim, o risco existe e é permanente, porque a conexão opera fora dos termos da plataforma. Volume alto para contatos frios e denúncias de spam aumentam a probabilidade. No modo Cloud API não existe esse vetor, porque a conexão é homologada.
Preciso de VPS para rodar a Evolution API?
Para produção, sim: o serviço precisa ficar no ar 24/7 com banco de dados e memória suficientes. Rodar em máquina local serve para teste, não para operação. O dimensionamento por porte está no nosso artigo de custos.
Qual a diferença entre Evolution API e Z-API?
As duas expõem WhatsApp via API, mas o modelo é diferente: a Evolution API é open source e auto-hospedada (você paga infraestrutura, não licença), e a Z-API é um serviço comercial pago por instância. O comparativo completo está em Evolution API vs Z-API.
Vale a pena usar Evolution API em agência?
Para validar um serviço, sim. Para operar dezenas de clientes, a conta de manutenção e o risco de ban por número raramente fecham: cada instância é uma VPS de responsabilidade sua e um número que pode cair. Nesse cenário, plataforma com API oficial e coexistência costuma custar menos do que as horas técnicas que o open source consome.
Se a sua operação já passou da fase de teste e o WhatsApp virou canal de receita, o caminho de menor arrependimento é conectar a API oficial com coexistência e deixar a engenharia reversa para os projetos em que cair não custa nada. As demais rotas de saída, por perfil de problema, estão em alternativas à Evolution API.
Deixe um comentário