Evolution API + n8n: como integrar, onde quebra e quando não usar

Evolution API com n8n é provavelmente a dupla mais montada da automação brasileira em 2026, e o motivo é econômico antes de ser técnico: as duas ferramentas são open source, rodam na mesma VPS e juntas substituem, no papel, um SaaS de atendimento inteiro. Um formulário que dispara mensagem, um funil que qualifica lead com IA, uma notificação de pedido: tudo isso vira um fluxo visual arrastando nós. A integração funciona. O que este artigo acrescenta ao entusiasmo é o mapa do que ela exige para continuar funcionando.

TL;DR: A integração Evolution API + n8n se monta em três peças: a instância conectada na Evolution API, o webhook apontando eventos para o n8n e as chamadas HTTP (ou o node de comunidade) devolvendo ações para a API. O caminho feliz leva uma tarde. Os pontos de atrito recorrentes: payload que muda entre versões, loop de eco quando o fluxo responde à própria mensagem e a fragilidade herdada do modo de conexão, porque o fluxo mais bem desenhado do mundo para de rodar quando a instância desconecta.

A arquitetura em três peças

Antes do passo a passo, o desenho. A Evolution API mantém a sessão do WhatsApp e expõe duas interfaces: eventos que saem (mensagem recebida, status, conexão) e endpoints que recebem ordens (enviar texto, mídia, marcar como lido). O n8n ocupa o meio: recebe os eventos por webhook, decide com a lógica do fluxo e responde chamando os endpoints. Quem entende esse triângulo resolve sozinho 80% dos problemas de integração, porque todo sintoma cai numa das três pontas: o evento não saiu, a lógica não decidiu ou a ordem não chegou.

Passo a passo enxuto (o que realmente importa em cada etapa)

1. Instância no ar. Crie a instância na Evolution API e conecte o número. Se o QR code não aparecer, resolva antes de tocar no n8n; a causa quase nunca está no fluxo, como detalhamos em Evolution API não gera QR code.
2. Webhook global ou por instância. Aponte o webhook para a URL do seu n8n (nó Webhook em modo produção, não em modo teste, erro clássico de primeira integração) e selecione só os eventos que o fluxo usa. Assinar todos os eventos “para garantir” enche o n8n de execução inútil e esconde os eventos que importam.
3. Credencial de envio. No n8n, guarde a URL base e a apikey da Evolution API em credencial, não chumbada no nó HTTP. Existe node de comunidade para Evolution API que abstrai os endpoints; ele acelera, mas amarra você ao ritmo de atualização do node. Chamada HTTP direta dá mais trabalho e mais controle.
4. Primeiro fluxo de verdade. O clássico: webhook recebe mensagem, um IF separa “primeira mensagem do contato” do resto, e o caminho de primeira mensagem responde com saudação e pergunta de qualificação. Vinte minutos de montagem, e você tem o esqueleto de um SDR automático.

Os três atritos que aparecem depois da primeira semana

Payload que muda entre versões. A estrutura do JSON de eventos da Evolution API já mudou entre releases, e fluxo n8n referencia campo por caminho exato. Uma atualização de versão pode quebrar silenciosamente cada expressão $json.data... do seu fluxo. Regra prática: fixe a versão da Evolution API em produção e atualize em janela controlada, testando os fluxos críticos antes.

Loop de eco. Quando a instância envia mensagem, a própria API pode emitir evento dessa mensagem enviada. Fluxo que não filtra a direção (fromMe) responde à própria resposta, e o resultado é uma metralhadora de mensagens para o cliente. Todo fluxo de resposta precisa do filtro de direção logo depois do webhook. Quem já pagou esse mico não esquece; quem ainda não montou o filtro está devendo um pedido de desculpas futuro.

A dependência da instância viva. Este é o atrito estrutural: o n8n executa quando o evento chega. Instância desconectada não emite evento, e o fluxo não falha, simplesmente não roda. Nenhum alerta nativo diferencia “ninguém escreveu hoje” de “a conexão caiu às 9h”. Monitorar o evento de conexão e alertar em canal separado é obrigatório em produção, e as causas da queda estão em Evolution API desconectando.

Onde essa stack brilha e onde ela é a escolha errada

Para automação interna e notificação transacional (pedido saiu, boleto vence, lembrete de agenda), a dupla é difícil de bater: custo marginal zero por mensagem e liberdade total de lógica. Para atendimento comercial com equipe, a história muda, porque n8n não é caixa de entrada: não tem fila, atribuição de conversa, visão de quem respondeu o quê. Aí o arranjo comum é acoplar um Chatwoot na frente, como descrevemos em Evolution API + Chatwoot, e a stack vira três peças auto-hospedadas para manter de pé, cada uma com sua atualização e seu jeito de quebrar.

É nesse ponto que a conta de arquitetura merece ser refeita. O trio Evolution + n8n + Chatwoot entrega o que uma plataforma pronta entrega, ao custo de você ser o integrador e o plantonista das três peças, sobre uma conexão que o próprio repositório da Evolution API (2026) descreve como sujeita a limitações por depender da versão web do WhatsApp. A alternativa de regime, com automação e caixa de entrada na mesma plataforma sobre API oficial (mantendo o app do celular pelo modo coexistência, documentado pela Meta em 2025), é o que o Cubo Suite entrega com conexão nativa. Interesse declarado. O critério de escolha honesto: se a automação é interna e tolera queda, fique na stack aberta; se ela conversa com cliente pagante, o custo do plantão entra na conta.

Conheça o CRM white label →

Existe node oficial da Evolution API no n8n?

Existe node de comunidade mantido pelo ecossistema, instalável no n8n self-hosted. Ele abstrai endpoints e acelera a montagem, com o custo de depender do ritmo de atualização do mantenedor. Chamadas HTTP diretas aos endpoints funcionam sempre e dão controle total.

O n8n precisa estar na mesma VPS da Evolution API?

Não. Precisam apenas se enxergar por HTTPS. Na prática, muita operação junta as duas na mesma máquina por custo, o que amarra os dois serviços ao mesmo ponto único de falha: a VPS que reinicia derruba o fluxo e a sessão juntos.

Como evitar que o fluxo responda à própria mensagem?

Filtrando a direção do evento logo após o webhook: mensagens marcadas como enviadas pela própria instância (fromMe) não devem entrar no caminho de resposta automática. É o primeiro IF de qualquer fluxo de atendimento.

A integração para de funcionar quando a Evolution API atualiza?

Pode parar: mudanças de payload entre versões quebram expressões que referenciam campos por caminho exato. Fixe a versão em produção e atualize em janela controlada, testando os fluxos críticos.