Evolution API Não Conecta ao WhatsApp: Como Resolver
A instância da Evolution API foi criada, o QR Code apareceu, mas o WhatsApp não conecta — ou conecta e cai pouco depois. Esse é um dos problemas mais comuns de quem está começando. Veja as causas mais frequentes, em ordem de probabilidade.
1. QR Code expira antes de escanear
O QR Code da Evolution API tem validade curta. Se a página demorar para carregar ou você demorar para abrir a câmera do WhatsApp, ele expira. Gere um novo QR Code direto antes de escanear, sem deixar a aba aberta por muito tempo.
2. Sessão antiga corrompida
Se a instância já tentou conectar antes e falhou, pode ter ficado um estado de sessão corrompido. Delete a instância e crie uma nova, em vez de tentar reconectar a mesma:
DELETE /instance/delete/{instanceName} 3. Número já está conectado em outro lugar
O WhatsApp permite apenas uma sessão “Web” ativa por número em determinadas configurações. Se o mesmo número já estiver conectado em outra instância, outro servidor, ou no WhatsApp Web do navegador, a nova conexão pode falhar silenciosamente. Desconecte as demais sessões antes de tentar de novo.
Verifique os logs: docker logs -f nome_do_container_evolution geralmente mostra a causa exata do erro de conexão — vale sempre olhar antes de tentar soluções aleatórias.
4. Conecta mas cai sozinho depois de um tempo
Isso costuma indicar falta de memória no servidor (o processo é encerrado pelo sistema) ou instabilidade de rede do VPS. Confira o uso de RAM com free -h durante o uso normal — se estiver no limite, é hora de considerar um plano com mais memória.
5. Versão desatualizada da Evolution API
O WhatsApp muda seu protocolo interno com frequência, e versões antigas da Evolution API param de funcionar corretamente. Mantenha a imagem Docker sempre atualizada para a versão estável mais recente:
docker compose pull
docker compose up -d Se o problema persistir mesmo depois desses passos, revise a configuração completa no guia de como hospedar a Evolution API em VPS — muitas vezes o problema está em uma variável de ambiente ou na rede Docker entre os containers.