Quem monta automação de atendimento no Brasil esbarra sempre na mesma parede: o WhatsApp. A combinação de Evolution API e n8n é o atalho que a maioria dos brasileiros adota para derrubar essa parede, sem depender da Cloud API oficial da Meta nem pagar por conversa. O passo a passo abaixo cobre a instalação com Docker, a criação da instância, a conexão do número por QR Code e o envio de texto e mídia direto do n8n.
O que é a Evolution API e por que ela é o atalho do brasileiro para WhatsApp no n8n
A Evolution API é uma API REST open-source, com licença Apache 2.0, mantida pela Evolution Foundation. A arquitetura dela suporta o Baileys, biblioteca que fala direto com o WhatsApp, e também a Cloud API oficial da Meta. Ou seja: dá para começar com número comum via QR Code e, se um dia precisar do caminho oficial, a ferramenta já conversa com ele.
Na prática, você ganha endpoints REST para criar instância, obter QR Code e enviar mensagens, com as famílias sendText e sendMedia. A própria arquitetura oficial lista o n8n entre as integrações nativas de chatbot, ao lado de Typebot, Chatwoot, OpenAI, Dify e Flowise. O casamento entre as duas ferramentas é documentado, não gambiarra.
A n8n chega a publicar um template oficial de assistente de WhatsApp usando o node da Evolution API, respondendo texto, áudio e imagens, com memória de conversa via Redis. Serve de referência depois que você dominar o básico daqui.
Requisitos e onde rodar: Docker em VPS ou Proxmox, banco de dados e a API key global
Antes de tudo, a lista do que você precisa:
- Um servidor com Docker — uma VPS simples ou um container/VM no Proxmox resolve.
- n8n self-hosted. Isso é obrigatório: o node da comunidade da Evolution API não funciona no n8n Cloud.
- Um número de WhatsApp dedicado à automação, de preferência separado do seu número pessoal.
- O arquivo
.envcom a API key global e as configurações de banco de dados, conforme a documentação oficial.
Sobre o banco de dados e a API key global: tudo é configurado no .env, e os nomes exatos das variáveis mudam entre versões da API. Não vou inventar lista aqui — copie o exemplo do repositório oficial da Evolution API no GitHub, que é a fonte certa.
Instalação com Docker: a imagem oficial e o .env
A instalação oficial recomendada é via Docker. Baixe a imagem e suba o container apontando para o seu .env:
docker pull evoapicloud/evolution-api:latest
docker run -p 8080:8080 --env-file .env evoapicloud/evolution-api:latestCrie o arquivo .env na mesma pasta de onde vai rodar o comando. Nele ficam a API key global, que é a chave que o n8n vai usar para autenticar, e as definições de banco de dados da sua instalação.
Sobre versões: a última estável da linha 2.x é a v2.3.7. As builds 2.4.0-rc1 e 2.4.0-rc2 são release candidates, listadas como pré-lançamento. Se preferir travar numa versão específica em vez do latest, confira a tag exata na página de releases do projeto.
Instalando o node da comunidade n8n-nodes-evolution-api no n8n
O node chama-se n8n-nodes-evolution-api, está na versão 1.0.4 no npm e é gratuito. Ele é compatível com Evolution API v2.2 ou superior, então a v2.3.7 atende sem problema.
No seu n8n, instale o pacote pela área de Community Nodes, buscando pelo nome exato. Repito o aviso porque é o erro mais comum: esse node só existe em instâncias self-hosted. Se o seu n8n é o Cloud, ele não vai aparecer na busca — esse limite está no template oficial publicado pela n8n.
Depois de instalar, crie a credencial do node apontando para a URL da sua Evolution API, na porta 8080 do container, e para a API key global que você definiu no .env. Com a credencial salva, o resto do fluxo é arrastar nó.
Criando a instância e conectando o número pelo QR Code
Com a API no ar, o próximo passo é criar uma instância. A instância é o contêiner lógico do seu número: cada uma tem nome, token próprio e sessão de WhatsApp atrelada. A criação e a obtenção do QR Code seguem o padrão REST da API, documentado no repositório oficial.
Gerado o QR Code, abra o WhatsApp do número que você vai usar na automação e leia o código, como faz ao conectar o app no desktop. Em segundos a instância aparece como conectada e o número já responde pela API.
Um aviso honesto: usuários relataram que, a partir do fim de julho de 2026, o pareamento por QR Code de novas instâncias falhava na v2.3.7, por causa do Baileys 7.0.0-rc.9, com correção encaminhada no Baileys em setembro de 2026. O acompanhamento está na issue #2737 do repositório do Baileys. Se o seu QR não conectar, comece por ali e pela página de releases.
Enviando mensagem de texto: o nó em ação com remoteJid e messageText
No n8n, adicione o node da Evolution API e escolha a operação de envio de texto, a família sendText. Dois campos fazem todo o trabalho:
- remoteJid: o destino da mensagem, no formato de JID do WhatsApp. Confira o formato exato na documentação da API para a sua versão antes de montar o fluxo.
- messageText: o corpo da mensagem que será entregue.
Um fluxo mínimo de teste: um nó que define o remoteJid e o messageText, ligado ao node da Evolution API, já entrega mensagem na tela do celular. Para um assistente que responde mensagens recebidas, o padrão é o webhook receber a mensagem, o fluxo extrair o JID do remetente e devolver a resposta com sendText — é a lógica do template oficial da n8n citado lá no começo.
Enviando mídia (imagem, áudio, vídeo e documento) e os cuidados com a sessão
Para mídia, a lógica é a mesma, trocando o envio para a família sendMedia, que cobre imagem, áudio, vídeo e documento. Os campos da operação variam conforme o tipo de envio; explore o node no n8n ou a documentação da API para preencher cada um certinho.
Detalhe de versão que vale registrar: o suporte nativo a GIF sem conversão para vídeo, com os campos gifPlayback e gifAttribution, entrou na 2.4.0-rc1. Como essa build ainda é release candidate, não conte com GIF nativo na linha estável em produção.
Cuidados para não perder a sessão ou o número
- Persista os dados da sessão: se o container cair e perder a sessão, você refaz o QR Code do zero.
- Evite disparo em massa agressivo. Número conectado via QR é um número comum, e comportamento de robô pesado pode custar o número.
- Mantenha a API atualizada. Boa parte das correções de conexão vem do Baileys e chega junto com as releases novas.
Na prática: como uso isso aqui
Eu rodo a Evolution API com um fork que eu mesmo fiz e mantenho, tanto com Docker no ZimaOS quanto em CT no Proxmox. O motivo de manter um fork veio justamente daquele problema de julho de 2026: o QR da 2.3.7 caiu pra mim também, e cuidar da manutenção por conta própria foi a forma que achei de resolver sem ficar refém de release alheia.
Os nodes da Evolution no n8n, esses sim, nunca me deram erro — texto e mídia funcionam de boa. Minha leitura de quem está começando: a Evolution API é grátis e open-source, e quem tem um pequeno conhecimento consegue usar bem. Quem não quer dor de cabeça ou não tem esse conhecimento pode ir para a EvoGO ou para a API oficial da Meta, só que aí entra um custo a mais.
Problemas comuns e como resolver
O QR Code gera mas não conecta
Provavelmente é o problema de pareamento da v2.3.7 com o Baileys 7.0.0-rc.9, relatado de fim de julho a setembro de 2026. Acompanhe a issue do Baileys e a página de releases para pegar a build com a correção.
O node não aparece no n8n
Seu n8n é o Cloud. O node da comunidade da Evolution API só está disponível em instâncias self-hosted, sem exceção.
Autenticação falha ao testar o node
Confira se a API key global configurada no .env é exatamente a mesma usada na credencial do n8n, e se a URL aponta para a porta correta da sua instalação.
As mensagens não saem
Verifique duas coisas: a instância está conectada (sessão viva) e a versão da sua Evolution API é v2.2 ou superior, requisito mínimo do node 1.0.4.
Conclusão
Evolution API rodando em Docker, com o node da comunidade no n8n, é um stack barato e poderoso para WhatsApp: custo de infraestrutura, custo zero de licença, e envio de texto e mídia em minutos de configuração. O preço cobrado é em conhecimento de Docker e em atenção às atualizações, principalmente num ano em que o próprio Baileys deu sustos de conexão. Se você já roda n8n self-hosted, vale cada minuto investido — e se ficou alguma dúvida no caminho, deixa nos comentários que eu respondo.
Perguntas frequentes
A Evolution API funciona no n8n Cloud?
Não. O node da comunidade n8n-nodes-evolution-api só está disponível em instâncias self-hosted do n8n, conforme o template oficial publicado pela n8n.
Qual versão da Evolution API devo instalar?
A última estável da linha 2.x é a v2.3.7. As builds 2.4.0-rc1 e 2.4.0-rc2 são release candidates, indicadas só para quem aceita o risco de pré-lançamento.
O QR Code falhou ao conectar o número. É bug?
Pode ser. Entre o fim de julho e setembro de 2026 houve falha de pareamento na v2.3.7 por causa do Baileys 7.0.0-rc.9, com correção encaminhada no Baileys. Acompanhe a issue #2737 do repositório do Baileys e a página de releases da Evolution API.
