Evolution API: Resolva Problemas Comuns de Conexão

Evolution API: Resolva Problemas Comuns de Conexão e Envio em Seu VPS

A Evolution API é uma solução robusta e amplamente utilizada para integrar o WhatsApp a diversos sistemas, desde CRMs até ferramentas de automação. Por ser uma ferramenta self-hosted, sua implantação e manutenção recaem sobre o usuário, o que pode gerar dúvidas e problemas técnicos. Este artigo foca em como diagnosticar e resolver os cenários mais frequentes que afetam a estabilidade e o funcionamento da Evolution API, como evolution api desconectando sozinha, evolution api não envia mensagem, erro ao criar instância evolution api e evolution api webhook não dispara. Nosso objetivo é guiá-lo na implantação de uma instância estável em seu próprio servidor Linux, garantindo que sua comunicação via WhatsApp flua sem interrupções.

Para rodar a Evolution API em produção de forma confiável, recomendamos um servidor com no mínimo 4GB de RAM e 2 vCPUs. Para cenários com alto volume de mensagens e múltiplos grupos, 8GB de RAM e 4 vCPUs são ideais, garantindo que a aplicação, o banco de dados e o proxy reverso operem sem gargalos. Um espaço de armazenamento de pelo menos 50GB é suficiente para o sistema operacional, Docker e logs.

Diagnóstico Inicial: Verificando Logs e Status da Instância

Antes de mergulhar em soluções específicas, o primeiro passo para qualquer problema com a Evolution API é verificar os logs e o status geral da instância. Uma instância que falha ao iniciar ou que para de funcionar abruptamente frequentemente deixa rastros valiosos nesses registros.

Onde Encontrar os Logs da Evolution API

Se você está utilizando Docker Compose para gerenciar sua instância da Evolution API, os logs de cada container podem ser acessados facilmente através do comando:

docker compose logs evolutionapi

Observe atentamente as mensagens de erro que aparecem. Elas podem indicar problemas com a conexão do banco de dados, falhas de permissão, ou até mesmo recursos insuficientes do servidor. Se a instância da Evolution API está desconectando sozinha, os logs podem revelar o motivo, como um reinício do container devido a falta de memória (OOM Killer).

Status da Instância e Conexão WebSocket

A comunicação entre o cliente (seu sistema) e a Evolution API geralmente ocorre via WebSocket. Uma conexão estável é crucial. Verifique se o WebSocket está ativo e se não há bloqueios por firewalls ou proxies. Ferramentas de monitoramento podem ajudar a identificar quedas na conexão WebSocket.

Resolvendo Erro ao Criar Instância Evolution API

O erro ao criar instância evolution api é um dos problemas mais frustrantes, pois impede o uso da ferramenta desde o início. Geralmente, este erro está associado a configurações incorretas durante a implantação inicial ou a requisitos de sistema não atendidos.

Verificação de Pré-requisitos e Configurações (.env)

A Evolution API utiliza um arquivo .env para gerenciar suas configurações. Certifique-se de que todas as variáveis de ambiente estejam preenchidas corretamente, especialmente:

• MONGO_URL: Conexão com o MongoDB.
• PUBNUB_SUBSCRIBE_KEY e PUBNUB_PUBLISH_KEY: Necessárias para a comunicação em tempo real.
• JWT_SECRET: Uma chave secreta forte para autenticação.
• PORT: A porta na qual a API rodará (geralmente 3000).

Erros comuns incluem URLs de banco de dados mal formatadas ou a ausência de uma chave secreta JWT válida.

Requisitos de Hardware Insuficientes

Como mencionado, rodar a Evolution API, especialmente em produção com Docker, exige recursos adequados. Um servidor com menos de 4GB de RAM pode sofrer com a inicialização de múltiplos containers (API, MongoDB, etc.), levando a falhas na criação da instância. Se você está testando em um ambiente local com poucos recursos, considere aumentar a alocação de memória. Para produção, um VPS Brasil Básico (4GB RAM, 4 vCPUs) é o ponto de partida ideal.

Solucionando Evolução API Desconectando Sozinha

O sintoma de evolution api desconectando sozinha pode ser causado por diversas razões, desde instabilidade na rede até problemas internos da aplicação.

Instabilidade de Rede e Conexão com o WhatsApp

A conexão com os servidores do WhatsApp é a base do funcionamento da Evolution API. Flutuações na rede do seu servidor VPS podem causar desconexões. Verifique a estabilidade da sua conexão com a internet.

Em minha experiência, já ajudei clientes que enfrentavam desconexões frequentes devido a políticas de rede restritivas em seus provedores de VPS, que limitavam o tráfego ou adicionavam latência. Certifique-se de que seu provedor de hospedagem oferece uma conexão estável e com baixa latência para os servidores do WhatsApp.

Gerenciamento de Processos e OOM Killer

Em ambientes Docker, se o consumo de memória ultrapassa o limite alocado para o container ou para o host, o sistema operacional pode encerrar processos para liberar recursos. Isso é conhecido como OOM Killer (Out-Of-Memory Killer). Se a Evolution API e seus dependentes (como o MongoDB) estão consumindo mais RAM do que o disponível, você verá a aplicação desconectando sozinha e reiniciando constantemente. Monitorar o uso de memória com comandos como docker stats é fundamental.

Para evitar isso, otimize o uso de recursos: garanta que o MongoDB não esteja retendo muitos dados em cache desnecessariamente, e considere aumentar a RAM do seu VPS se o consumo estiver consistentemente alto.

Quando a Evolution API Não Envia Mensagem

Este é um dos problemas mais críticos, pois impacta diretamente a funcionalidade central da ferramenta. Vários fatores podem impedir o envio de mensagens.

Verificação de Credenciais e Status do WhatsApp

Primeiramente, certifique-se de que sua instância da Evolution API ainda está conectada ao WhatsApp. Verifique o status no painel da API ou através de requisições específicas. Se a conexão foi perdida, tente reconectar ou reiniciar a instância.

Problemas com o Banco de Dados (MongoDB)

A Evolution API utiliza o MongoDB para armazenar mensagens e dados. Se o MongoDB estiver indisponível, lento ou com problemas de conexão, o envio de mensagens pode falhar. Verifique o status do container do MongoDB (se estiver usando Docker) e os logs dele.

Uma configuração de banco de dados subdimensionada também pode ser a causa. Para cenários de alto tráfego, é recomendável que o MongoDB rode em um servidor separado ou que seu VPS tenha recursos robustos o suficiente para suportar a carga de trabalho do banco de dados junto com a API.

Limites de Uso do WhatsApp e Bloqueios

O WhatsApp impõe limites de envio e pode bloquear números que enviam mensagens em massa de forma não autorizada ou que violam seus termos de serviço. Se você está enviando um grande volume de mensagens rapidamente, ou mensagens que podem ser interpretadas como spam, sua conta pode ser temporariamente ou permanentemente bloqueada.

Use a API de forma responsável, respeitando os limites e enviando mensagens apenas para contatos que consentiram em recebê-las. Se suspeitar de um bloqueio, contate o suporte do WhatsApp Business.

Evolução API Webhook Não Dispara: Causas e Soluções

Webhooks são essenciais para que a Evolution API notifique seu sistema sobre eventos, como recebimento de novas mensagens. Se o evolution api webhook não dispara, a comunicação bidirecional é comprometida.

Configuração Incorreta do URL do Webhook

Verifique no painel da Evolution API se o URL do seu webhook está configurado corretamente. Um erro de digitação, uma porta incorreta, ou a ausência de um protocolo (HTTP/HTTPS) válido são causas comuns.

Problemas de Acessibilidade do Servidor Webhook

O servidor que hospeda o URL do seu webhook precisa estar acessível publicamente pela internet. Se o webhook aponta para um endereço local ou privado, a Evolution API não conseguirá alcançá-lo. Certifique-se de que seu servidor web (onde o webhook será recebido) esteja configurado com um IP público e que as portas necessárias estejam abertas no firewall. Se você precisa expor um serviço interno, um proxy reverso como Nginx pode ser configurado para redirecionar o tráfego externo para o serviço interno. Para mais detalhes sobre como configurar um proxy reverso, confira nosso artigo sobre Docker Troubleshooting.

Certificado SSL/TLS Inválido ou Ausente (HTTPS)

Se o seu URL de webhook usa HTTPS, um certificado SSL/TLS inválido, expirado ou autoassinado pode impedir que a Evolution API estabeleça a conexão. É crucial ter um certificado válido e confiável para o domínio do seu webhook.

Como dica de especialista, sempre utilize um proxy reverso como Nginx ou Caddy para gerenciar os certificados SSL/TLS. Eles facilitam a obtenção e renovação automática de certificados gratuitos via Let's Encrypt. Se você não tem familiaridade com proxy reverso, este guia sobre Typebot: Resolvendo Erros de Deploy e Debug pode ser útil para entender os conceitos.

Passo a Passo: Implantando a Evolution API em um VPS Ubuntu com Docker Compose

Vamos detalhar um processo prático para implantar a Evolution API em um servidor VPS com Ubuntu, utilizando Docker Compose para facilitar o gerenciamento.

1. Pré-requisitos no VPS

Certifique-se de que seu VPS Ubuntu tenha o Docker e o Docker Compose instalados. Se ainda não os possui, siga estes passos:

# Atualizar lista de pacotes
sudo apt update && sudo apt upgrade -y

# Instalar Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Adicionar seu usuário ao grupo docker (para evitar usar sudo em todos os comandos)
sudo usermod -aG docker $USER
newgrp docker # Aplica as mudanças no grupo sem precisar reiniciar

# Instalar Docker Compose Plugin (versão mais recente)
sudo apt install docker-compose-plugin -y

# Verificar instalações
docker --version
docker compose version

2. Criando a Estrutura de Diretórios e Arquivos

Crie um diretório para sua aplicação e navegue até ele:

mkdir evolution-api-deploy
cd evolution-api-deploy

Dentro deste diretório, crie dois arquivos principais: .env para as configurações e docker-compose.yml para definir os serviços.

Arquivo .env

Crie o arquivo .env com suas chaves e configurações. Substitua os valores de exemplo pelos seus:

MONGO_URL=mongodb://mongo:27017/evolution-api
PUBNUB_SUBSCRIBE_KEY=SUA_CHAVE_SUBSCRIBE
PUBNUB_PUBLISH_KEY=SUA_CHAVE_PUBLISH
JWT_SECRET=SEU_SEGREDO_JWT_MUITO_FORTE
PORT=3000
NODE_ENV=production
LOG_LEVEL=info

# Configurações adicionais (opcional, dependendo da sua necessidade)
# DB_USER=seu_usuario_mongo
# DB_PASSWORD=sua_senha_mongo
# DB_NAME=evolution-api

Arquivo docker-compose.yml

Este arquivo define os containers para a Evolution API e o MongoDB:

version: "3.8"

services:
  evolutionapi:
    image: ghcr.io/evolution-api/evolution-api:latest
    container_name: evolutionapi
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    env_file:
      - .env
    depends_on:
      - mongo

  mongo:
    image: mongo:latest
    container_name: evolutionapi_mongo
    restart: unless-stopped
    ports:
      - "27017:27017"
    volumes:
      - ./mongo-data:/data/db
    env_file:
      - .env
    # Se você definiu DB_USER e DB_PASSWORD no .env, descomente e ajuste:
    # environment:
    #   MONGO_INITDB_ROOT_USERNAME: ${DB_USER}
    #   MONGO_INITDB_ROOT_PASSWORD: ${DB_PASSWORD}

volumes:
  mongo-data:
  data:
  logs:

3. Iniciando os Containers

Com os arquivos configurados, inicie os serviços:

docker compose up -d

O comando -d roda os containers em segundo plano. Agora, você pode acessar a Evolution API através do IP do seu servidor na porta 3000 (ou a porta definida em seu arquivo .env).

4. Configurando um Proxy Reverso (Nginx)

Para acessar a Evolution API por um domínio, usar HTTPS e ter mais controle sobre o tráfego, configure um proxy reverso. Instale o Nginx se ainda não o tiver:

sudo apt install nginx -y

Crie um arquivo de configuração para a Evolution API em /etc/nginx/sites-available/:

server {
    listen 80;
    server_name seu_dominio.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'connection';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Habilite o site e teste a configuração do Nginx:

sudo ln -s /etc/nginx/sites-available/evolution-api /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Para configurar HTTPS, você precisará obter um certificado SSL com Let's Encrypt, o que pode ser feito com o Certbot. Siga as instruções do Certbot para automatizar esse processo.

Erros Comuns e Como Evitá-los

• Versões Incompatíveis: Sempre use as versões mais recentes e estáveis do Docker, Docker Compose, Evolution API e MongoDB. Verifique a documentação oficial para compatibilidade.
• Permissões de Arquivos/Diretórios: Certifique-se de que os volumes mapeados (./data, ./logs, ./mongo-data) tenham as permissões de escrita corretas para o usuário do Docker.
• Chaves Secretas Fracas: Utilize senhas e chaves JWT fortes e únicas para a segurança da sua instância.
• Recursos Insuficientes: Não subestime os requisitos de RAM e CPU. Um VPS subdimensionado levará a problemas de estabilidade e performance.

Comparativo de Requisitos da Evolution API

Perguntas Relacionadas

Por que a Evolution API perde a conexão com o WhatsApp?

A perda de conexão pode ocorrer devido a instabilidade na rede do servidor, reinícios inesperados do container da API ou do servidor, ou até mesmo bloqueios impostos pelo WhatsApp por uso indevido ou excessivo.

Como garantir que a Evolution API não desconecte sozinha?

Para evitar desconexões, garanta que seu VPS tenha recursos de RAM e CPU suficientes, que a rede seja estável e que você esteja seguindo as políticas de uso do WhatsApp. Monitorar os logs é crucial para identificar a causa raiz.

O que fazer se a Evolution API não envia mensagens?

Verifique o status da conexão com o WhatsApp, a saúde do banco de dados MongoDB, e se não há limites de envio ou bloqueios ativos na sua conta do WhatsApp. Confira também se as credenciais de API e o JWT estão corretos.

Meu webhook não dispara, o que pode ser?

Verifique se o URL do webhook está correto, se o servidor que o recebe está acessível pela internet pública e se há um certificado SSL/TLS válido (para HTTPS). Um proxy reverso com Nginx pode ajudar a gerenciar isso.

Conclusão e Próximos Passos

Gerenciar a Evolution API em seu próprio VPS pode apresentar desafios, mas com o conhecimento certo, é possível manter uma operação estável e eficiente. Através deste guia, cobrimos os principais problemas de conexão, envio, criação de instância e disparo de webhooks, além de fornecer um tutorial prático de implantação. Lembre-se sempre de monitorar seus logs e os recursos do servidor.

Para garantir a performance e a estabilidade que sua comunicação via WhatsApp exige, a escolha do servidor é fundamental. Rodamos esse exato setup em uma VPS Brasil Básico, que oferece 4GB de RAM e 4 vCPUs a partir de R$ 99/mês, sendo a solução ideal para iniciar com a Evolution API em produção. Descubra como elevar sua automação!

Conheça e contrate seu VPS Brasil Básico agora!