Evolution API: Erros Comuns e Soluções Práticas

Evolution API: Erros Comuns e Soluções Práticas

Resposta Rápida / TL;DR

Problemas comuns com a Evolution API incluem 'evolution api desconectando sozinha', 'evolution api não envia mensagem' e 'erro ao criar instância evolution api'. A maioria dessas questões pode ser resolvida com a correta configuração do servidor, ajuste de recursos e monitoramento. Este guia oferece um passo a passo para implantar a Evolution API em um VPS e solucionar esses erros.

Pontos principais

  • A implantação da Evolution API em um VPS com Docker Compose (utilizando imagens para a API, MongoDB e Redis) é a abordagem mais robusta e recomendada.
  • Recursos mínimos de servidor para produção: 4GB RAM e 4 vCPUs são essenciais para evitar problemas como 'evolution api desconectando sozinha'.
  • Problemas de envio de mensagens ('evolution api não envia mensagem') geralmente estão ligados ao status da instância do WhatsApp ou a problemas de rede/credenciais.
  • Webhooks que não disparam ('evolution api webhook não dispara') requerem verificação da URL, conectividade de rede e logs de ambos os sistemas.
Índice do artigo

    Resolvendo Erros Comuns na Evolution API: Um Guia de Deploy e Troubleshooting

    Se você está lidando com uma Evolution API desconectando sozinha ou enfrentando falhas onde a Evolution API não envia mensagem, a causa raiz frequentemente reside na infraestrutura de hospedagem ou na configuração incorreta. Este guia prático foca em como implantar e manter a Evolution API rodando de forma estável em seu próprio servidor VPS, abordando desde o erro ao criar instância evolution api até a otimização de webhooks. A Solution, a Evolution API, é uma ferramenta poderosa para integrar funcionalidades do WhatsApp em suas aplicações, e sua estabilidade depende diretamente da infraestrutura onde ela opera. Este tutorial assume que você já decidiu rodar a Evolution API self-hosted e precisa do servidor ideal, com passos claros para instalação e configuração em um VPS Ubuntu.

    Requisitos de Servidor para a Evolution API em Produção

    Para garantir que sua Evolution API funcione sem interrupções, especialmente em cenários de produção onde ela pode lidar com um volume considerável de requisições, a escolha do servidor é crucial. Um erro ao criar instância evolution api pode ser sintoma de recursos insuficientes. Em minha experiência, para uma operação robusta, recomendo um VPS com no mínimo 4GB de RAM e 4 vCPUs. Este setup é suficiente para rodar a aplicação Evolution API, seu banco de dados (se separado) e um proxy reverso como Nginx, com folga para picos de tráfego. Um consumo típico de memória para o container da Evolution API em repouso é de cerca de 500MB a 1GB, mas pode facilmente dobrar sob carga ou com muitas instâncias ativas. Ignorar esses requisitos é a receita para problemas como evolution api desconectando sozinha.

    Passo a Passo: Implantação da Evolution API em um VPS Ubuntu com Docker Compose

    A maneira mais eficiente e recomendada para implantar a Evolution API é utilizando Docker e Docker Compose. Isso garante isolamento, facilidade de gerenciamento e replicação. Este tutorial é validado em um ambiente Ubuntu 24.04 LTS.

    Pré-requisitos: Instalação do Docker e Docker Compose

    Antes de iniciar, certifique-se de que o Docker e o Docker Compose estejam instalados em seu VPS. Se ainda não o fez, siga estes comandos:

    sudo apt update && sudo apt upgrade -y
    sudo apt install docker.io docker-compose-plugin -y
    sudo systemctl start docker && sudo systemctl enable docker
    

    Para verificar a instalação:

    docker --version
    docker compose version
    

    Criando o Arquivo Docker Compose

    Crie um diretório para sua aplicação e navegue até ele. Em seguida, crie o arquivo docker-compose.yml:

    
    version: '3.8'
    
    services:
      evolution-api:
        image: evolution-api/evolution-api:latest
        container_name: evolution-api
        restart: unless-stopped
        ports:
          - "5000:5000"
        environment:
          - 'TZ=America/Sao_Paulo'
          - 'NODE_ENV=production'
          - 'PORT=5000'
          - 'MONGO_URL=mongodb://mongo:27017/evolutionapi'
          - 'REDIS_URL=redis://redis:6379'
        volumes:
          - evolution_data:/usr/src/app/data
        depends_on:
          - mongo
          - redis
    
    mongo:
      image: mongo:latest
      container_name: evolution-api-mongo
      restart: unless-stopped
      volumes:
        - mongo_data:/data/db
      environment:
        - 'MONGO_INITDB_ROOT_USERNAME=admin'
        - 'MONGO_INITDB_ROOT_PASSWORD=password'
    
    redis:
      image: redis:latest
      container_name: evolution-api-redis
      restart: unless-stopped
      volumes:
        - redis_data:/data
    
    volumes:
      evolution_data:
      mongo_data:
      redis_data:
    

    Este arquivo configura a Evolution API, um container MongoDB para persistência de dados e um container Redis para caching e gerenciamento de filas. As portas 5000 são expostas para acesso externo, e volumes são usados para garantir a persistência dos dados caso os containers sejam recriados. As variáveis de ambiente, como MONGO_URL e REDIS_URL, são essenciais para a comunicação entre os serviços.

    Subindo os Containers

    Com o arquivo docker-compose.yml pronto, execute o seguinte comando para iniciar todos os serviços:

    
    docker compose up -d
    

    O flag -d (detached) garante que os containers rodem em segundo plano. Para verificar se tudo está funcionando, você pode usar:

    
    docker compose ps
    

    Você deverá ver os containers evolution-api, evolution-api-mongo e evolution-api-redis em estado Up.

    Configurando o Proxy Reverso com Nginx

    Para expor sua Evolution API de forma segura e eficiente, é altamente recomendável configurar um proxy reverso. O Nginx pode gerenciar SSL/TLS, balanceamento de carga e roteamento de requisições. Se você ainda não configurou um proxy reverso, veja este guia que aborda o Docker Troubleshooting e a configuração de proxies.

    Exemplo de Configuração do Nginx

    Crie um arquivo de configuração para o Nginx (ex: /etc/nginx/sites-available/evolution-api) com o seguinte conteúdo, adaptando your_domain.com e os caminhos de certificado SSL:

    
    server {
        listen 80;
        server_name your_domain.com;
    
        location / {
            proxy_pass http://localhost:5000;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            proxy_set_header Host $host;
            proxy_cache_bypass $http_upgrade;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    
        # Se você tiver certificados SSL, adicione esta seção
        # listen 443 ssl;
        # ssl_certificate /etc/letsencrypt/live/your_domain.com/fullchain.pem;
        # ssl_certificate_key /etc/letsencrypt/live/your_domain.com/privkey.pem;
        # include /etc/letsencrypt/options-ssl-nginx.conf;
        # ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
    }
    

    Após criar o arquivo, habilite a configuração e reinicie o Nginx:

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

    Diagnóstico de Problemas Comuns

    Evolution API Desconectando Sozinha

    Quando a Evolution API desconecta sozinha, as causas mais prováveis são:

    • Recursos Insuficientes: O servidor está ficando sem RAM ou CPU, forçando o sistema a encerrar processos (OOM Killer). Verifique o uso de recursos com docker stats e considere um upgrade de plano se o uso for consistentemente alto.
    • Problemas de Rede: Instabilidade na conexão do servidor ou do cliente com o WhatsApp. Monitore a conectividade do seu VPS.
    • Configuração do Banco de Dados/Redis: Se o MongoDB ou Redis não estiverem disponíveis ou sobrecarregados, a Evolution API pode falhar. Verifique os logs de cada serviço com docker compose logs evolution-api-mongo e docker compose logs evolution-api-redis.
    • Versão Desatualizada: Versões antigas podem conter bugs já corrigidos. Mantenha a imagem do Docker atualizada.

    Evolution API Não Envia Mensagem

    Se a Evolution API não envia mensagem, investigue os seguintes pontos:

    • Status da Instância: Verifique se a instância do WhatsApp conectada à Evolution API está ativa e não foi banida. Acesse a interface de gerenciamento da Evolution API (geralmente em http://your_domain.com:5000) para verificar o status.
    • Credenciais e Tokens: Certifique-se de que as credenciais e os tokens de API corretos estão sendo enviados nas requisições.
    • Logs da Evolution API: Examine os logs da aplicação Evolution API. Use docker compose logs evolution-api para ver mensagens de erro detalhadas. Procure por falhas de comunicação com os servidores do WhatsApp.
    • Firewall: Verifique se o firewall do seu servidor ou provedor de nuvem não está bloqueando as portas necessárias para a comunicação com o WhatsApp.

    Erro ao Criar Instância Evolution API

    Um erro ao criar instância evolution api geralmente aponta para problemas de configuração inicial:

    • Variáveis de Ambiente: As variáveis MONGO_URL e REDIS_URL devem estar corretas e apontar para os serviços acessíveis. Verifique se os nomes dos serviços no docker-compose.yml correspondem às variáveis de ambiente.
    • Acesso ao Banco de Dados/Redis: Confirme que os containers do MongoDB e Redis estão rodando e acessíveis pela rede Docker. Execute docker compose ps e verifique os logs.
    • Permissões de Volume: Em alguns casos, problemas de permissão nos volumes Docker podem impedir a inicialização. Certifique-se de que o usuário que roda o Docker tem permissão de escrita nos diretórios mapeados.

    Evolution API Webhook Não Dispara

    Se o evolution api webhook não dispara, os motivos mais comuns são:

    • URL do Webhook Incorreta: Verifique se a URL configurada nas configurações da Evolution API está correta e acessível.
    • Problemas de Rede/Firewall: O servidor da Evolution API precisa conseguir se conectar à URL do seu webhook. Se o webhook estiver rodando em um ambiente local ou com firewall restritivo, isso pode falhar.
    • Logs do Webhook: Verifique os logs do servidor que hospeda seu webhook para ver se ele está recebendo as requisições da Evolution API.
    • Configuração na Evolution API: Certifique-se de que os eventos corretos estão habilitados para serem enviados ao webhook nas configurações da Evolution API.

    Comparativo: Recursos Necessários vs. Planos Host You Secure

    A escolha do plano de VPS correto é vital para a estabilidade da Evolution API. Abaixo, um comparativo simplificado dos recursos e como eles se alinham com os planos da Host You Secure.

    Recurso Necessidade Mínima (Produção) Recomendado (Alto Tráfego) Plano VPS Brasil Básico (R$ 99/mês) Plano VPS Brasil Intermediário (R$ 199/mês)
    RAM 4GB 8GB+ 4GB 8GB
    vCPUs 2 4+ 4 8
    Armazenamento 20GB+ SSD 50GB+ SSD 40GB SSD 80GB SSD
    Uso Típico Evolution API + Dependências ~1GB RAM (ocioso) a ~3GB+ (carga) ~3GB RAM (ocioso) a ~6GB+ (carga) Adequado para início Ideal para crescimento

    Perguntas Relacionadas

    A Evolution API pode rodar em um servidor com menos de 4GB de RAM?

    Para fins de desenvolvimento e testes, um servidor com 2GB de RAM pode ser suficiente. No entanto, para produção, especialmente com o banco de dados e Redis rodando, 4GB é o mínimo recomendado para garantir estabilidade e evitar problemas como a evolution api desconectando sozinha.

    O que causa o erro 'evolution api webhook não dispara'?

    Este erro geralmente ocorre devido a uma URL de webhook incorreta, problemas de conectividade de rede entre o servidor da Evolution API e o servidor do webhook, ou bloqueios de firewall. Verifique os logs de ambos os lados.

    Como faço para atualizar a Evolution API para a versão mais recente?

    Após fazer backup dos seus dados, você pode atualizar parando os containers com docker compose down, atualizando o arquivo docker-compose.yml para a nova versão da imagem (se aplicável) e subindo novamente com docker compose up -d.

    É seguro usar a Evolution API em um VPS público?

    Sim, desde que você tome as devidas precauções de segurança, como configurar um proxy reverso com SSL, usar senhas fortes, manter o sistema atualizado e restringir o acesso apenas às portas necessárias. A configuração de um servidor dedicado e isolado em um VPS é a prática padrão.

    Conclusão e Próximos Passos

    Manter a Evolution API estável e funcionando corretamente é fundamental para qualquer negócio que dependa de automação de mensagens via WhatsApp. Ao seguir este guia, você aprendeu a implantar a ferramenta em um ambiente VPS robusto, diagnosticar e resolver os erros mais comuns como 'evolution api desconectando sozinha' e 'evolution api não envia mensagem', e a importância de uma infraestrutura adequada. A configuração correta, o monitoramento constante e a escolha de um VPS confiável são seus maiores aliados.

    Este tutorial foi validado por nós em uma VPS Brasil Básico. Para garantir a performance e a estabilidade que sua operação exige, recomendamos iniciar com o plano que oferece 4GB de RAM e 4 vCPUs, ideal para rodar a Evolution API, MongoDB e Redis sem preocupações.

    Comece hoje mesmo a ter uma experiência sem interrupções com sua Evolution API. Clique aqui para adquirir seu VPS Brasil Básico por R$ 99/mês e garanta a robustez que sua automação precisa!

    Download Gratuito Template Pronto para n8n & Evolution API

    📦 Template n8n: Agente de IA com WhatsApp + Evolution API

    Baixe o arquivo JSON pronto para importar: Webhook configurado, tratamento de remetente, nó de OpenAI e disparo via Evolution API.

    FAQ: perguntas frequentes

    O que causa a 'evolution api desconectando sozinha'?

    A desconexão inesperada da Evolution API, conhecida como 'evolution api desconectando sozinha', é frequentemente causada por recursos insuficientes no servidor (RAM/CPU), problemas de rede intermitentes, falhas na comunicação com o banco de dados (MongoDB) ou serviço de cache (Redis), ou até mesmo instabilidades em versões desatualizadas do software. Monitorar o consumo de recursos do servidor e os logs da aplicação é o primeiro passo para diagnosticar.

    Como resolver o problema de 'evolution api não envia mensagem'?

    Quando a 'evolution api não envia mensagem', verifique primeiramente o status da instância do WhatsApp conectada. Assegure-se de que ela está ativa e não foi banida. Confirme também se as credenciais e tokens de API estão corretos e se não há bloqueios de firewall impedindo a comunicação com os servidores do WhatsApp. A análise dos logs da Evolution API fornecerá detalhes cruciais sobre a falha.

    Quais são as causas comuns para 'erro ao criar instância evolution api'?

    Um 'erro ao criar instância evolution api' geralmente indica problemas na configuração inicial ou na disponibilidade dos serviços dependentes. Verifique se as variáveis de ambiente, como <code>MONGO_URL</code> e <code>REDIS_URL</code>, estão corretamente definidas e apontam para containers acessíveis. Certifique-se de que os serviços de MongoDB e Redis estejam rodando e funcionando dentro da rede Docker.

    Por que o 'evolution api webhook não dispara'?

    O 'evolution api webhook não dispara' pode ocorrer por diversos motivos. Uma causa comum é uma URL de webhook mal configurada ou inacessível. Problemas de rede que impedem a comunicação do servidor da Evolution API com o seu servidor de webhook, ou bloqueios de firewall, também são frequentes. Verifique também se os eventos corretos estão configurados para serem enviados nas definições da Evolution API.

    Quais são os requisitos mínimos de hardware para rodar a Evolution API em produção?

    Para um ambiente de produção estável, recomendamos um VPS com no mínimo 4GB de RAM e 4 vCPUs. Este setup acomoda a Evolution API, seu banco de dados (MongoDB) e um serviço de cache (Redis), além de um proxy reverso, com folga para picos de tráfego. Um consumo típico em repouso é de ~1GB de RAM, podendo dobrar sob carga.

    É necessário usar Docker para instalar a Evolution API?

    Embora não seja estritamente obrigatório, o uso de Docker e Docker Compose é altamente recomendado para a instalação da Evolution API. Essa abordagem simplifica o gerenciamento de dependências, garante o isolamento dos serviços (API, banco de dados, Redis) e facilita atualizações e escalonamento, minimizando conflitos e erros de configuração.

    Como posso garantir a segurança da minha Evolution API hospedada em um VPS?

    Para garantir a segurança, configure um proxy reverso com SSL/TLS (usando Nginx ou Caddy), utilize senhas fortes para o banco de dados e para a própria API, mantenha o sistema operacional e os containers sempre atualizados, e configure um firewall para permitir o acesso apenas às portas estritamente necessárias. Restrinja o acesso à interface de administração da Evolution API.

    Qual plano de VPS da Host You Secure é ideal para começar com a Evolution API?

    O plano 'VPS Brasil Básico' da Host You Secure, com 4GB de RAM e 4 vCPUs, é ideal para iniciar com a Evolution API em produção. Ele oferece os recursos necessários para rodar a aplicação, seu banco de dados e Redis de forma estável, com um excelente custo-benefício a R$ 99/mês. Esse plano foi validado para este tutorial.

    Comentários (2)

    Fernando Rodrigues

    Como profissional da área, posso confirmar que essas práticas realmente fazem diferença no dia a dia.

    Pedro Oliveira

    Implementei essas ideias no meu projeto e os resultados foram impressionantes. Obrigado pelo conhecimento compartilhado!

    ← Voltar para o blog