Evolution API: Resolvendo Erros de Conexão e Instância

Evolution API: Resolvendo Erros de Conexão e Instância

Resposta Rápida / TL;DR

Para resolver problemas com a Evolution API, comece verificando os logs do servidor onde ela está hospedada, garantindo que os requisitos de RAM (mínimo 4GB para produção) e CPU sejam atendidos. Verifique também a configuração do banco de dados, a conectividade de rede e se o webhook está corretamente configurado e acessível.

Pontos principais

  • A Evolution API requer um VPS com no mínimo 4GB de RAM e 4 vCPUs para produção estável, especialmente com banco de dados e proxy reverso.
  • Utilizar Docker Compose simplifica a implantação e o gerenciamento da Evolution API e seu banco de dados PostgreSQL em um VPS.
  • Erros comuns como instância desconectando ou webhook não disparando são frequentemente resolvidos com verificação de logs, recursos do servidor e configurações de rede/SSL.
  • Manter um token de autenticação forte e URLs de webhook corretas é crucial para a segurança e funcionalidade da API.
Índice do artigo

    Resolvendo Erros Comuns na Evolution API: Guia de Implantação e Troubleshooting

    A Evolution API, quando rodando em seu próprio servidor VPS, oferece controle total e escalabilidade para suas automações WhatsApp. No entanto, como qualquer software self-hosted, você pode encontrar desafios. Este guia foca em como implantar a Evolution API em um VPS Ubuntu, detalhando a solução para problemas 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. Assumimos que você já decidiu utilizar a Evolution API e agora precisa de um ambiente estável para rodá-la. Para um funcionamento robusto, recomendamos um servidor com no mínimo 4GB de RAM e 4 vCPUs, como o nosso plano VPS Brasil Básico, que nossos clientes utilizam com sucesso para esta stack.

    Passo a Passo: Implantação da Evolution API em VPS Ubuntu

    Implantar a Evolution API em um VPS com Ubuntu é um processo direto, especialmente quando utilizamos Docker e Docker Compose. Esta abordagem garante isolamento, facilidade de gerenciamento e atualizações mais limpas. Para um ambiente de produção, além da Evolution API, você também precisará de um banco de dados (geralmente PostgreSQL) e um proxy reverso (Nginx é uma escolha comum) para gerenciar conexões e certificados SSL.

    1. Pré-requisitos no Servidor

    Antes de iniciar a instalação, certifique-se de que seu servidor VPS atende aos requisitos mínimos e que as ferramentas essenciais estão instaladas. Para a Evolution API rodar de forma estável em produção, com banco de dados e proxy, recomendamos:

    • RAM: Mínimo de 4GB. Para mais de 10 instâncias ou alto volume de mensagens, 8GB ou mais são ideais.
    • CPU: Mínimo de 4 vCPUs.
    • Armazenamento: Mínimo de 30GB SSD, com espaço adicional para logs e backups.
    • Sistema Operacional: Ubuntu 20.04 LTS ou superior.
    • Software Essencial: Docker e Docker Compose (versão plugin).

    Para instalar o Docker e o Docker Compose plugin no Ubuntu, execute os seguintes comandos:

    # Atualizar lista de pacotes
    sudo apt update
    
    # Instalar pacotes necessários
    sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
    
    # Adicionar chave GPG oficial do Docker
    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
    
    # Adicionar repositório Docker
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
    
    # Instalar Docker Engine e Docker Compose Plugin
    sudo apt update
    sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
    
    # Verificar instalação
    docker --version
    docker compose version
    

    2. Configuração do Docker Compose

    Crie um diretório para a sua aplicação Evolution API e, dentro dele, crie o arquivo docker-compose.yml. Este arquivo definirá os serviços necessários: a Evolution API e um banco de dados PostgreSQL. Para garantir que a Evolution API funcione corretamente, é crucial que o banco de dados esteja configurado e acessível antes da API iniciar.

    version: '3.8'
    
    services:
      evolution-api:
        image: revolutoin/evolution-api:latest
        container_name: evolution-api
        restart: unless-stopped
        ports:
          - "5000:5000"
        environment:
          NODE_ENV: "production"
          PORT: "5000"
          API_URL: "http://localhost:5000"
          TOKEN_APP: "SEU_TOKEN_SEGURO_AQUI"
          DATABASE_URL: "postgresql://user:password@db:5432/evolution_api"
          WEBHOOK_URL: "https://seu-dominio.com/webhook"
          # Outras variáveis de ambiente podem ser necessárias dependendo da sua configuração
        depends_on:
          - db
        volumes:
          - evolution-data:/usr/src/app/files
    
      db:
        image: postgres:14
        container_name: evolution-api-db
        restart: unless-stopped
        environment:
          POSTGRES_DB: "evolution_api"
          POSTGRES_USER: "user"
          POSTGRES_PASSWORD: "password"
        ports:
          - "5432:5432"
        volumes:
          - evolution-db-data:/var/lib/postgresql/data
    
    volumes:
      evolution-data:
      evolution-db-data:
    

    Atenção: Substitua SEU_TOKEN_SEGURO_AQUI por um token forte e único. Ajuste user, password e evolution_api no DATABASE_URL para corresponder às credenciais e nome do banco de dados que você definir para o serviço db. O WEBHOOK_URL deve apontar para o endpoint público onde você deseja receber os eventos. A porta 5000 é a padrão da Evolution API. Para produção, é recomendado expor a API através de um proxy reverso como Nginx, que cuidará da porta 80/443 e SSL.

    3. Executando a Aplicação

    Navegue até o diretório onde você salvou o arquivo docker-compose.yml e execute o seguinte comando para subir os containers:

    docker compose up -d
    

    O flag -d executa os containers em modo detached (background). Para verificar o status dos containers, use:

    docker compose ps
    

    E para ver os logs em tempo real, especialmente em caso de problemas:

    docker compose logs -f evolution-api
    docker compose logs -f db
    

    Resolver problemas como erro ao criar instância evolution api geralmente envolve verificar os logs do container evolution-api e do container db para identificar falhas de conexão ou configuração.

    Troubleshooting: Evolução API Desconectando Sozinha e Não Enviando Mensagens

    Quando a evolution api desconecta sozinha, as causas mais comuns são:

    • Recursos Insuficientes: Falta de RAM ou CPU no servidor VPS. Um servidor com menos de 4GB de RAM pode ter o container da Evolution API ou do banco de dados encerrado pelo sistema operacional (OOM Killer).
    • Problemas de Rede: Instabilidade na conexão entre o VPS e os servidores do WhatsApp.
    • Configurações Incorretas: Variáveis de ambiente mal configuradas no docker-compose.yml ou no arquivo .env, como tokens inválidos ou URLs incorretas.
    • Versão Desatualizada: Bugs em versões mais antigas da Evolution API. Mantenha sempre a imagem mais recente ou uma versão estável conhecida.

    Para a questão de evolution api não envia mensagem:

    • Instância Desconectada: A instância do WhatsApp pode ter se desconectado. Verifique o status da instância através da API ou do dashboard.
    • Token Inválido: O token de autenticação da API pode ter expirado ou sido revogado.
    • Rate Limiting: O WhatsApp pode estar limitando o envio de mensagens se um volume muito alto for enviado em curtos períodos.
    • Formato da Mensagem: Erros na formatação dos dados enviados na requisição de envio de mensagem (ex: número de telefone no formato incorreto, tipo de mídia não suportado).

    Se você está enfrentando problemas persistentes, considere consultar nosso artigo sobre Evolution API: Erros Comuns e Soluções VPS para um aprofundamento em cenários específicos.

    Configurando Webhooks e Tratando Erros de Instância

    O evolution api webhook não dispara é uma queixa frequente. As causas mais comuns incluem:

    • URL do Webhook Incorreta: Verifique se a WEBHOOK_URL configurada no ambiente da Evolution API está correta, acessível publicamente e se não há erros de digitação.
    • Firewall Bloqueando: O firewall do seu VPS ou do servidor onde o webhook está hospedado pode estar bloqueando a conexão de entrada na porta configurada (geralmente 80 ou 443).
    • Certificado SSL Inválido: Se você usa HTTPS para o webhook, um certificado SSL inválido ou expirado impedirá que a Evolution API se conecte.
    • Lógica do Webhook: O próprio endpoint do webhook pode estar com erros, não respondendo corretamente ou demorando demais para processar a requisição, levando a um timeout. Teste seu endpoint com ferramentas como Postman.
    • Erro ao Criar Instância: Se a instância não foi criada corretamente, os webhooks associados a ela não dispararão. Verifique os logs de criação da instância. Um erro ao criar instância evolution api pode estar diretamente ligado à configuração do banco de dados ou a problemas de rede que impedem a comunicação com os servidores do WhatsApp.

    Para garantir que sua infraestrutura de automação seja robusta, é fundamental ter um servidor confiável. Ferramentas como o N8N, que podem ser integradas com a Evolution API, também requerem uma configuração adequada. Se você ainda não configurou o proxy reverso, veja este guia para entender como um bom setup de rede pode evitar muitos problemas.

    Comparativo: Requisitos de Servidor para Evolution API

    Escolher o VPS correto é crucial para a estabilidade da Evolution API. Abaixo, uma comparação dos requisitos típicos:

    Componente Ambiente de Desenvolvimento/Teste Produção (1-5 Instâncias) Produção (5-15 Instâncias)
    RAM 2GB 4GB 8GB+
    vCPUs 2 4 6+
    Armazenamento (SSD) 15GB 30GB+ 50GB+
    Banco de Dados Pode ser compartilhado ou em contêiner separado Contêiner dedicado (PostgreSQL recomendado) Contêiner dedicado ou instância gerenciada
    Proxy Reverso Opcional Nginx/Caddy (essencial para produção) Nginx/Caddy (essencial)
    Consumo Típico (API ociosa) ~200MB RAM ~300-500MB RAM ~600-800MB RAM

    Note que o consumo de RAM listado para a API é apenas para o contêiner da aplicação em si. O consumo total do servidor incluirá o sistema operacional, o banco de dados, o proxy reverso e outros serviços. Por isso, para produção com 5 instâncias, 4GB de RAM no VPS total é um ponto de partida seguro, garantindo que todos os componentes tenham recursos suficientes.

    Perguntas Relacionadas

    Por que minha Evolution API está lenta?

    A lentidão geralmente indica gargalos de recursos. Verifique o uso de CPU e RAM no seu VPS. Se estiverem constantemente altos, você pode precisar de um plano de VPS com mais recursos ou otimizar seu banco de dados e configurações da API. Uma rede instável entre o servidor e o WhatsApp também pode causar lentidão.

    Como faço para atualizar a Evolution API?

    Se você usou Docker Compose, o processo é simples: navegue até o diretório do seu docker-compose.yml, execute docker compose pull para baixar a nova imagem, e então docker compose up -d para reiniciar os contêineres com a versão atualizada. Verifique os logs após a atualização para garantir que tudo subiu corretamente.

    O que fazer se a Evolution API não reconhece a conexão do WhatsApp?

    Isso geralmente está ligado a problemas de instância. Verifique se o QR code foi escaneado corretamente, se o token de autenticação da API está válido e se não há bloqueios de rede impedindo a comunicação com os servidores do WhatsApp. Reiniciar a instância e os contêineres da Evolution API e do banco de dados pode resolver problemas temporários.

    É seguro usar a Evolution API em um VPS compartilhado?

    Embora tecnicamente possível, não é recomendado para ambientes de produção. Um VPS dedicado oferece mais segurança, isolamento de recursos e controle sobre a configuração. Em um VPS compartilhado, o desempenho e a segurança podem ser afetados por outros usuários.

    Conclusão e Recomendação

    A Evolution API é uma ferramenta poderosa, e com a configuração correta em um VPS robusto, você pode evitar a maioria dos problemas comuns. Desde a implantação inicial com Docker Compose até o troubleshooting de desconexões, mensagens não enviadas ou webhooks inativos, a chave está em monitorar os logs, garantir recursos adequados e configurar corretamente as variáveis de ambiente.

    Para rodar a Evolution API com estabilidade e performance em produção, com banco de dados e proxy reverso, recomendamos o plano VPS Brasil Básico. Nossos clientes rodam essa mesma stack em uma VPS Brasil Básico, que oferece 4GB de RAM e 4 vCPUs, ideal para iniciar suas automações WhatsApp de forma confiável. Não deixe que problemas técnicos atrasem suas operações.

    Conheça o VPS Brasil Básico e garanta a estabilidade da sua operação hoje mesmo!

    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

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

    Para um ambiente de produção com a Evolution API, banco de dados e proxy reverso, recomendamos um mínimo de 4GB de RAM. Este valor garante que o sistema operacional, os contêineres Docker e os serviços essenciais operem sem problemas. Para cenários com mais de 5 instâncias ou alto volume de mensagens, 8GB ou mais são aconselháveis para manter a performance e evitar instabilidade.

    O que causa o erro 'erro ao criar instância evolution api'?

    Este erro geralmente aponta para problemas na comunicação com os servidores do WhatsApp ou falhas na configuração do banco de dados. Verifique se o token de autenticação está correto, se a URL da API está acessível e se o PostgreSQL está rodando e acessível pela Evolution API. Revise os logs de ambos os contêineres (API e DB) para identificar a causa raiz.

    Como resolver 'evolution api desconectando sozinha'?

    A desconexão frequente pode ser causada por falta de recursos no servidor VPS (RAM insuficiente é a principal causa), instabilidade na rede, problemas de configuração (tokens, URLs) ou bugs em versões desatualizadas da API. Certifique-se de que seu VPS atende aos requisitos mínimos de 4GB RAM e 4 vCPUs para produção e que sua conexão com a internet é estável.

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

    Verifique se a <code>WEBHOOK_URL</code> configurada está correta, acessível publicamente e se o certificado SSL (se usar HTTPS) é válido. Certifique-se de que firewalls no seu VPS ou no servidor do webhook não estão bloqueando a requisição. Também é crucial que a instância da Evolution API esteja conectada e funcionando corretamente para que os eventos sejam enviados.

    Qual a diferença entre rodar a Evolution API em desenvolvimento e produção?

    Em desenvolvimento, você pode usar configurações mais simples e menos recursos (ex: 2GB RAM). Em produção, é essencial um ambiente robusto com recursos dedicados (mínimo 4GB RAM, 4 vCPUs), banco de dados separado, proxy reverso para segurança e alta disponibilidade, e monitoramento constante para garantir estabilidade e performance.

    Como configurar o Nginx como proxy reverso para Evolution API?

    Crie um arquivo de configuração no Nginx (ex: `/etc/nginx/sites-available/evolution-api`) definindo o `server_name` para seu domínio, e `proxy_pass` para `http://localhost:5000` (ou a porta onde a Evolution API está rodando). Ative o site, configure SSL e reinicie o Nginx. Isso protege sua API e permite acesso via `seudominio.com`.

    É possível usar a Evolution API sem Docker?

    Sim, é possível instalar a Evolution API diretamente no sistema operacional host. No entanto, usar Docker e Docker Compose é a abordagem recomendada para produção. Ela simplifica o gerenciamento de dependências, isola a aplicação, facilita atualizações e rollbacks, e garante um ambiente mais consistente e fácil de replicar.

    O que o token `TOKEN_APP` na configuração da Evolution API faz?

    O `TOKEN_APP` é uma chave de autenticação secreta que você define. Ela é usada para proteger o acesso à sua instância da Evolution API. Qualquer requisição feita à API deve incluir este token em um cabeçalho de autorização (ex: `Authorization: Bearer SEU_TOKEN_SEGURO_AQUI`). Isso garante que apenas aplicações autorizadas possam interagir com sua instância.

    ← Voltar para o blog