Evolution API: Resolvendo Erros de Instância e Webhook

Evolution API: Resolvendo Erros Comuns de Instância e Webhook

A Evolution API é uma ferramenta poderosa para integrar o WhatsApp em suas aplicações, mas como qualquer sistema self-hosted, pode apresentar desafios. Se você se depara com a mensagem "evolution api desconectando sozinha", "evolution api não envia mensagem", "erro ao criar instância evolution api" ou "evolution api webhook não dispara", este guia é para você. Vamos focar em como implantar e manter a Evolution API rodando de forma estável em um servidor VPS, abordando os problemas mais frequentes com soluções práticas.

Veja a infraestrutura: VPS para Evolution API no Brasil para colocar este projeto no ar.

Para garantir a estabilidade da Evolution API em produção, recomendamos um ambiente com no mínimo 4GB de RAM e 4 vCPUs. Um servidor robusto é crucial, pois a API gerencia conexões WebSocket, processa mensagens e interage com um banco de dados. Este tutorial foi validado em uma VPS Brasil Básico da Host You Secure, que oferece exatamente essas especificações (4GB RAM, 4 vCPUs) por R$ 99/mês, sendo ideal para iniciar.

Diagnóstico e Correção de Instâncias Instáveis

Uma instância da Evolution API que se desconecta inesperadamente é um dos problemas mais frustrantes. As causas comuns incluem instabilidade na rede, esgotamento de recursos no servidor, conflitos de porta ou configurações incorretas do banco de dados.

1. Verificação de Recursos do Servidor

O primeiro passo é monitorar o uso de RAM e CPU do seu servidor. Se a memória estiver constantemente alta ou o CPU em 100%, a instância pode ser reiniciada ou falhar ao responder. Utilize comandos como htop ou top para visualizar o consumo de recursos em tempo real. Se o consumo estiver consistentemente acima de 80%, considere um upgrade no seu plano de VPS.

2. Logs da Evolution API

Os logs são seus melhores amigos. Eles fornecem informações detalhadas sobre o que está acontecendo. Para acessar os logs, você precisa verificar a saída do container Docker onde a Evolution API está rodando. Se você está usando Docker Compose, o comando docker compose logs evolutionapi (substitua 'evolutionapi' pelo nome do seu serviço) mostrará os logs em tempo real.

Procure por mensagens de erro como "Out of Memory", "Connection refused", "Database connection error" ou quaisquer outras indicações de falha. Esses logs podem apontar diretamente para a causa do problema, seja um problema de conexão com o banco de dados, uma porta já em uso ou um erro interno da aplicação.

3. Conexão com o Banco de Dados

A Evolution API depende de um banco de dados para persistir informações e gerenciar a conexão. Certifique-se de que as credenciais de conexão (host, porta, usuário, senha, nome do banco) estejam corretas nas variáveis de ambiente do seu arquivo .env. Verifique também se o servidor do banco de dados está acessível a partir do servidor onde a API está rodando e se não há firewalls bloqueando a comunicação.

Solucionando Problemas de Envio de Mensagens

Quando a "evolution api não envia mensagem", o problema pode estar na própria API, na conexão com o WhatsApp ou na configuração do servidor.

1. Status da Instância e Conexão WhatsApp

Verifique o status da instância através do painel da Evolution API ou via API (geralmente em /instance/state/{instance_name}). Se a instância estiver "disconnected" ou "closed", você precisa resolver isso primeiro. Um QR Code válido e escaneado pelo seu WhatsApp Business é essencial. Se o QR Code expirar, um novo precisa ser gerado e escaneado.

2. Verificação de Webhooks de Envio

Quando você envia uma mensagem, a API pode retornar um webhook com o status do envio. Monitore esses webhooks para entender se a mensagem chegou ao "WhatsApp Gateway" ou se falhou antes disso. Se o problema for no recebimento do webhook pela sua aplicação, o problema pode estar na configuração do seu endpoint ou no firewall do servidor que hospeda sua aplicação.

3. Limitações do WhatsApp e Bloqueios

O WhatsApp tem políticas rígidas contra spam e uso indevido. Enviar um volume muito alto de mensagens em um curto período pode levar a bloqueios temporários ou permanentes da sua conta. Certifique-se de que seu uso esteja em conformidade com os Termos de Serviço do WhatsApp Business API. Se você suspeita de um bloqueio, verifique os logs da Evolution API e os status de conexão.

Depurando Erros na Criação de Instância e Webhooks

O "erro ao criar instância evolution api" geralmente aponta para configurações iniciais incorretas ou falta de permissões. Já a falha no disparo do "evolution api webhook não dispara" requer uma análise focada na comunicação entre a API e sua aplicação.

1. Configuração do Arquivo `.env` e Permissões

Um "erro ao criar instância evolution api" pode ser causado por variáveis de ambiente mal configuradas no arquivo .env. Verifique se o nome da instância, as credenciais do banco de dados e as portas estão corretas. Certifique-se também de que o diretório de dados da Evolution API (geralmente um volume Docker) tenha as permissões de escrita corretas para o usuário sob o qual o processo está rodando.

Um exemplo de arquivo .env para rodar a Evolution API com Docker Compose pode parecer assim:

POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_USER=evolution
POSTGRES_PASSWORD=evolutionpassword
POSTGRES_DB=evolution
APP_PORT=3000
INSTANCE_NAME=myinstance
WEBHOOK_URL=http://your-app-server.com/webhook

# Outras configurações opcionais, como JWT, etc.
JWT_SECRET=your_jwt_secret_here

2. Configuração e Teste de Webhooks

Para depurar um "evolution api webhook não dispara", a primeira etapa é garantir que a URL do webhook esteja configurada corretamente na Evolution API e que o servidor onde sua aplicação de webhook está hospedada esteja acessível publicamente (ou via túnel). Use ferramentas como ngrok para expor um servidor local e testar a recepção do webhook diretamente. Verifique os logs da sua aplicação de webhook para ver se alguma requisição está chegando.

Se você está usando Nginx como proxy reverso, certifique-se de que as configurações de proxy estejam corretas para encaminhar as requisições para o serviço da Evolution API e, crucialmente, que as requisições de webhook enviadas pela Evolution API consigam alcançar seu destino. Uma configuração comum para proxy reverso Nginx para Evolution API:

server {
    listen 80;
    server_name evolution.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000; # Porta onde a Evolution API está rodando
        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 sua aplicação de webhook também está rodando em um contêiner Docker, certifique-se de que a URL do webhook aponte para o endereço IP público do servidor ou um domínio acessível, e não para o IP interno do contêiner, a menos que a rede Docker esteja configurada para isso.

Passo a Passo: Implantando Evolution API em um VPS Ubuntu

Vamos implantar a Evolution API usando Docker e Docker Compose em um servidor Ubuntu. Este método simplifica o gerenciamento e garante que todas as dependências estejam isoladas.

Pré-requisitos

• Um servidor VPS com Ubuntu (recomendado 22.04 LTS ou superior).
• Acesso SSH ao servidor.
• Docker e Docker Compose instalados. Se não tiver, siga este guia rápido: Docker Troubleshooting: Soluções Rápidas para instalar o Docker e o plugin do Docker Compose.

1. Crie um Diretório para a Aplicação

Crie um diretório onde os arquivos de configuração da Evolution API serão armazenados:

sudo mkdir /opt/evolution-api
cd /opt/evolution-api

2. Crie o Arquivo `.env`

Crie um arquivo chamado `.env` neste diretório e adicione as configurações necessárias. Ajuste as credenciais do banco de dados e a URL do webhook conforme seu ambiente.

# /opt/evolution-api/.env
POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_USER=evolution
POSTGRES_PASSWORD=your_strong_password
POSTGRES_DB=evolution
APP_PORT=3000
INSTANCE_NAME=myinstance
WEBHOOK_URL=http://your-public-domain.com/your-webhook-path
JWT_SECRET=a_very_secure_secret_key

3. Crie o Arquivo `docker-compose.yml`

Crie o arquivo docker-compose.yml para definir os serviços da Evolution API e do PostgreSQL.

# /opt/evolution-api/docker-compose.yml
version: '3.8'

services:
  evolutionapi:
    image: evolutionapi/evolutionapi:latest
    container_name: evolutionapi
    ports:
      - "3000:3000"
    volumes:
      - ./:/usr/src/app
      - /opt/evolution-api/data:/usr/src/app/data # Volume para persistência de dados
    env_file:
      - .env
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: postgres:14
    container_name: evolutionapi_db
    volumes:
      - /opt/evolution-api/postgres-data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: evolution
      POSTGRES_PASSWORD: your_strong_password
      POSTGRES_DB: evolution
    ports:
      - "5432:5432"
    restart: unless-stopped

4. Inicie os Contêineres

Execute o seguinte comando para iniciar a Evolution API e o banco de dados PostgreSQL:

cd /opt/evolution-api
docker compose up -d

O comando -d roda os contêineres em segundo plano. Use docker compose logs -f evolutionapi para visualizar os logs em tempo real e verificar se tudo iniciou corretamente.

5. Configuração do Proxy Reverso (Nginx)

Para acessar a Evolution API externamente (por exemplo, em evolution.yourdomain.com), você precisará configurar um proxy reverso. Se você ainda não configurou o Nginx, veja este guia para configurar o proxy reverso. Crie um arquivo de configuração em /etc/nginx/sites-available/evolution-api:

server {
    listen 80;
    server_name evolution.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000; 
        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;
    }
}

Habilite o site e reinicie o Nginx:

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

Agora você deve conseguir acessar a Evolution API através do seu domínio.

Perguntas Relacionadas

O que causa a mensagem "evolution api desconectando sozinha"?

Essa mensagem geralmente indica que a conexão WebSocket foi perdida. As causas mais comuns são instabilidade na rede do servidor, esgotamento de recursos (RAM/CPU), conflitos de porta ou problemas de configuração do banco de dados que levam a API a travar e reiniciar.

Como faço para o webhook da Evolution API disparar corretamente?

Para que um webhook dispare, a URL configurada na API deve estar acessível publicamente e sem bloqueios de firewall. Verifique os logs da Evolution API e da sua aplicação de webhook para identificar se a requisição está sendo enviada e recebida. Certifique-se de que a URL esteja correta e que o serviço esteja rodando.

Quais são os requisitos mínimos de servidor para Evolution API?

Para produção, recomendamos um servidor com no mínimo 4GB de RAM e 4 vCPUs. Para ambientes de desenvolvimento ou testes com pouca carga, 2GB de RAM podem ser suficientes, mas não são recomendados para uso contínuo e com múltiplos usuários.

Como resolver "erro ao criar instância evolution api"?

Esse erro geralmente aponta para um problema na configuração inicial. Verifique se as variáveis de ambiente no arquivo `.env` estão corretas, especialmente as credenciais do banco de dados e o nome da instância. Certifique-se também de que as permissões de escrita no diretório de dados da API estejam configuradas corretamente.

Comparativo de Soluções para Problemas Comuns

Conclusão: Mantenha Sua Evolution API Ativa e Confiável

Resolver problemas de instabilidade, envio de mensagens e webhooks na Evolution API é fundamental para o sucesso de suas integrações. Com as ferramentas de diagnóstico corretas, como a análise de logs e o monitoramento de recursos do servidor, você pode identificar e corrigir a maioria dos problemas rapidamente. A adoção de um ambiente de hospedagem robusto, como o oferecido pela Host You Secure, é o primeiro passo para garantir a confiabilidade.

Este tutorial demonstrou como implantar a Evolution API em um VPS Linux usando Docker e Docker Compose, abordando desde a configuração inicial até a resolução de erros comuns. Lembre-se que a manutenção e o monitoramento contínuos são essenciais para evitar futuras interrupções.

Para começar a usar a Evolution API sem dores de cabeça com infraestrutura, recomendamos o plano VPS Brasil Básico da Host You Secure. Este tutorial foi validado por nós em uma VPS Brasil Básico, que oferece 4GB de RAM e 4 vCPUs por apenas R$ 99/mês. Garanta a estabilidade e performance que sua automação WhatsApp merece.

Conheça o plano VPS Brasil Básico e implante sua Evolution API hoje mesmo! por R$ 99/mês