Como configurar Evolution API + n8n em VPS para WhatsApp Business

Introdução

A comunicação digital evoluiu rapidamente, e o WhatsApp Business tornou-se um canal essencial para vendas, suporte e marketing. No entanto, gerenciar essas interações manualmente pode se tornar um gargalo operacional à medida que sua base de clientes cresce. A solução reside na automação inteligente, conectando a robustez da Evolution API com a flexibilidade do n8n.

Neste tutorial técnico, explicaremos como configurar uma infraestrutura completa em uma VPS (Virtual Private Server). Uniremos a capacidade da Evolution API de gerenciar conexões WebSocket com o WhatsApp ao poder do n8n para orquestrar fluxos de trabalho complexos. Essa combinação permite criar desde simples chatbots até sistemas avançados de CRM automatizado.

Ao final deste guia, você terá domínio sobre a configuração Evolution API, entenderá como estruturar o ambiente n8n WhatsApp Business e estará preparado para implementar uma integração WhatsApp Business escalável. Prepararemos sua VPS, instalaremos as ferramentas necessárias e construiremos um fluxo de dados seguro e eficiente.

Pré-requisitos

Antes de iniciar a configuração da Evolution API e do n8n, é fundamental garantir que seu ambiente atenda aos requisitos técnicos necessários para uma operação estável. A falta de algum desses componentes pode impedir o funcionamento correto da automação.

node -v
npm -v

docker -v

1. VPS com Linux: Você precisa de uma VPS com sistema operacional Linux (Ubuntu 20.04+, Debian 11+, ou CentOS/Rocky Linux). Certifique-se de ter acesso root ou permissões sudo. Para ambientes de produção, recomenda-se pelo menos 2 vCPUs e 4GB de RAM para garantir performance estável.
2. Node.js e npm: O n8n roda nativamente sobre o Node.js. Embora o Docker possa ser usado, a instalação via NVM (Node Version Manager) oferece maior controle sobre as versões. Verifique a instalação com os comandos acima.
3. Docker e Docker Compose: Embora opcional para instalações manuais do n8n, o Docker é altamente recomendado para a Evolution API e para facilitar backups e atualizações do n8n. Instale-o em sua VPS e valide com docker -v.
4. Conta WhatsApp Business: Você deve ter um número de telefone ativo vinculado ao WhatsApp Business. Este número será escaneado via QR Code para estabelecer a conexão com os servidores do Meta.
5. Acesso SSH Seguro: Familiaridade com terminal Linux é obrigatória. Você precisará gerenciar serviços, configurar firewalls e editar arquivos de configuração diretamente no servidor.

Garanta que seu firewall (UFW ou Firewalld) esteja configurado para permitir apenas as portas necessárias, mantendo sua infraestrutura segura desde o início da VPS configuração.

Instalação do n8n

O n8n é uma ferramenta de automação "fair-code" que permite conectar APIs e serviços. Para uma instalação profissional em VPS, utilizaremos o Node Version Manager (NVM) para garantir que a versão do Node.js seja gerenciada corretamente, evitando conflitos de dependências.

ssh usuario@ip-da-vps

sudo apt update && sudo apt upgrade -y

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
source ~/.bashrc
nvm install node

node -v
npm -v

npm install n8n -g

n8n start

1. Conexão SSH: Conecte-se à sua VPS usando um cliente SSH seguro. Isso garante que você tenha controle total sobre o sistema operacional.
2. Atualização do Sistema: Execute sudo apt update para garantir que os pacotes do sistema estejam atualizados, reduzindo riscos de vulnerabilidades conhecidas.
3. Instalação do Node.js via NVM: O NVM permite instalar múltiplas versões do Node.js. Este comando baixa e instala o NVM, depois você carrega o script no shell atual com source ~/.bashrc e instala a versão LTS do Node.
4. Verificação de Versão: Confirme que o node e o npm estão instalados corretamente. O n8n requer uma versão recente do Node.js (geralmente 18+).
5. Instalação Global do n8n: O comando npm install n8n -g instala o binário do n8n em todo o sistema, permitindo que você o execute de qualquer diretório.
6. Inicialização: Execute n8n start. Por padrão, o n8n iniciará na porta 5678. Para produção, recomenda-se usar um gerenciador de processos como PM2 ou systemd para manter o serviço rodando em segundo plano.

O n8n estará acessível no seu navegador através do endereço http://ip-da-vps:5678. Certifique-se de liberar a porta 5678 no firewall da sua VPS. Para maior segurança em produção, configure um domínio e um proxy reverso (Nginx ou Traefik) com certificado SSL.

Configuração da Evolution API

A Evolution API atua como a ponte entre o WhatsApp e seu servidor de automação. Ela gerencia a sessão do WhatsApp, o recebimento de mensagens em tempo real (via WebSocket) e o envio de comandos HTTP. A configuração Evolution API requer atenção especial aos detalhes de segurança e roteamento.

1. Acesso ao Painel: Acesse a interface administrativa da sua Evolution API instalada na VPS. Geralmente, isso é feito via navegador na porta padrão da instalação (ex: 8080 ou 4000).
2. Credenciais de Acesso: No menu principal, localize a seção de configurações globais ou de instância. Clique em Gerar Token de Acesso. Este token é a chave mestra para autenticar suas requisições HTTP. Armazene-o em um local seguro; ele não será exibido novamente.
3. Configuração de Webhooks: Esta é a parte crítica da integração API WhatsApp. Vá até a seção de Webhooks ou Configurações de Evento. Você deve informar ao Evolution API onde enviar os dados das mensagens recebidas. Insira a URL pública do seu n8n, por exemplo: https://seu-dominio.com/webhook.
4. Seleção de Eventos: Marque os eventos que deseja capturar. Para uma automação completa, selecione messages.upsert (nova mensagem recebida), messages.update (status da mensagem) e, se necessário, eventos de conexão.
5. Teste de Conectividade: Salve as configurações. O Evolution API tentará validar a URL do webhook. Certifique-se de que sua VPS possui um domínio válido com SSL ativo, pois o WhatsApp exige conexões HTTPS seguras para webhooks.

Aviso: A Evolution API utiliza WebSockets para manter a conexão aberta com o WhatsApp. Garanta que sua VPS tenha uma conexão de rede estável e baixa latência para evitar desconexões frequentes da sessão do WhatsApp.

Integração com WhatsApp

Com a Evolution API rodando e configurada, o próximo passo é criar o fluxo no n8n que processará as mensagens. Esta etapa define como seu sistema n8n WhatsApp Business reagirá aos inputs dos clientes.

1. Criação do Workflow: Acesse a interface do n8n em seu navegador. Clique em "Workflows" e depois em "Create New". Dê um nome descritivo ao seu fluxo, como "Automação WhatsApp Entrada".
2. Gatilho HTTP: Adicione um novo nó clicando em "+". Pesquise por HTTP Webhook. Configure-o para receber requisições POST. Copie a URL gerada pelo n8n; você precisará colar essa URL na configuração de Webhooks da Evolution API (passo anterior).
3. Recebendo os Dados: O nó HTTP Webhook do n8n receberá o payload JSON enviado pela Evolution API. Explore o nó para ver a estrutura dos dados recebidos, que inclui informações como from (número de origem), body (texto da mensagem) e timestamp.
4. Processamento Lógico: Adicione nós de lógica (Switch, IF, Code) para interpretar a mensagem. Por exemplo, se a mensagem for "OI", o sistema pode responder com um menu de opções.
5. Envio de Resposta: Para responder ao cliente, você precisará usar um nó HTTP Request ou o nó nativo da Evolution API (se disponível na versão do n8n). Configure-o da seguinte maneira:

   {
       "to": "{{ $json.from }}",
       "type": "text",
       "message": "Obrigado pelo contato! Como podemos ajudar?"
   }

   • Method: POST
   • URL: A URL base da sua Evolution API (ex: http://localhost:8080/v1/messages/send-text).
   • Headers: Adicione o cabeçalho de autenticação: Authorization: Bearer SEU_TOKEN_DE_AUTENTICAÇÃO.
   • Body: Envie os dados JSON formatados conforme a documentação da API.
6. Ativação: Salve o workflow e clique em "Activate". O n8n agora estará escutando as requisições. Volte ao painel da Evolution API e verifique se o status do webhook está "Ativo".

Ao seguir esses passos, você estabelece uma via de mão dupla: a Evolution API recebe as mensagens do WhatsApp e as encaminha ao n8n, que processa a lógica e envia a resposta de volta através da mesma API.

Verificação

A fase de verificação é crucial para garantir que a integração WhatsApp Business esteja robusta e pronta para uso real. Testes unitários e de integração devem ser realizados antes de expor o sistema aos clientes finais.

1. Monitoramento no n8n: Acesse o painel do n8n e vá para a aba "Executions". Envie uma mensagem de teste pelo WhatsApp para o número conectado. Verifique se o workflow foi acionado e se o nó HTTP Webhook recebeu os dados corretamente.
2. Resposta Automática: Se seu fluxo estiver configurado para responder, aguarde alguns segundos. A resposta deve aparecer no seu WhatsApp. Se não aparecer, verifique os logs do nó de envio (HTTP Request) para identificar erros 401 (não autorizado) ou 404 (não encontrado).
3. Teste com Postman/curl: Para isolar problemas, teste a API diretamente. Use o terminal da sua VPS ou o Postman para simular uma requisição:

   curl -X POST https://seu-dominio.com/v1/messages/send-text \
   -H "Authorization: Bearer SEU_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"to": "55SEUNUMERO", "type": "text", "message": "Teste de integração"}'

   Se a resposta for um JSON com status "success", a API está funcionando corretamente.
4. Verificação de Logs: Se algo falhar, verifique os logs do n8n (n8n ou pm2 logs) e os logs da Evolution API. Erros comuns incluem tokens expirados, URLs de webhook inalcançáveis ou problemas de formatação JSON.

Uma verificação bem-sucedida confirma que o ciclo completo de comunicação está operando. Recomendamos realizar testes diários nas primeiras semanas de operação para identificar instabilidades na conexão do WhatsApp.

Troubleshooting

Problemas podem ocorrer durante a VPS configuração ou manutenção. Abaixo, listamos os erros mais comuns e suas soluções práticas.

Erro de Conexão com WhatsApp (QR Code expirado)

Se o status da instância mostrar "Desconectado", o token de sessão pode ter expirado. Acesse o painel da Evolution API, clique em "Reset Session" ou gere um novo QR Code. O n8n continuará funcionando, mas não enviará mensagens até que a conexão seja restabelecida.

Webhook não recebe dados

Verifique se a URL do webhook no n8n é pública e acessível via HTTPS. Firewalls da VPS podem bloquear a entrada. Use ferramentas como ngrok temporariamente para testar se o n8n está recebendo os dados localmente antes de expor ao mundo.

Erro 401 Unauthorized na API

O token de autenticação está incorreto ou expirado. Regere o token no painel da Evolution API e atualize a variável de ambiente ou configuração no nó HTTP do n8n. Nunca compartilhe seu token publicamente.

n8n não inicia ou consome muita RAM

O n8n pode ser intensivo em memória. Se sua VPS tiver poucos recursos, considere otimizar os workflows, removendo nós desnecessários ou limitando o histórico de execuções nas configurações do n8n.

Perguntas frequentes

É necessário pagar pela Evolution API?

A versão open-source da Evolution API é gratuita para uso em sua própria VPS. No entanto, você pode precisar de serviços de terceiros para hospedagem ou suporte avançado. Verifique sempre a licença do software que você está utilizando.

Posso usar o n8n na nuvem em vez de uma VPS?

Sim, o n8n Cloud é uma opção válida. No entanto, usar uma VPS própria oferece maior controle sobre os dados, latência reduzida e custo fixo previsível, desde que você gerencie a segurança e as atualizações.

Como escalar o sistema para milhares de mensagens?

Para alta escala, considere usar Docker Compose para orquestrar múltiplas instâncias da Evolution API (load balancing) e configurar o n8n com um banco de dados externo (PostgreSQL) em vez do SQLite padrão, que é limitado para alto volume.

A Evolution API suporta envio de imagens e documentos?

Sim. A API suporta diversos tipos de mídia. No nó HTTP Request do n8n, você deve alterar o tipo para image ou document e enviar o link da URL da mídia ou o arquivo em base64, conforme a documentação da API.

Conclusão

A configuração bem-sucedida da Evolution API e do n8n em sua VPS representa um passo significativo na maturidade digital da sua empresa. Ao dominar essa integração WhatsApp Business, você transforma o WhatsApp de uma ferramenta de comunicação caótica em um canal estruturado e automatizado.

Lembre-se de que a estabilidade depende da manutenção contínua: monitore os logs, atualize as versões do Node.js e do n8n periodicamente e mantenha seus tokens seguros. A automação não é um "configure e esqueça", mas sim uma ferramenta viva que deve ser ajustada conforme seu negócio evolui.

Se você busca infraestrutura de alta performance para hospedar essas soluções sem preocupações com downtime ou manutenção de servidor, a Toda Solução oferece VPS otimizadas e suporte técnico especializado. Garanta que sua automação tenha a base sólida que merece.