Uma instância da Evolution API pode cair por rede, sessão corrompida, mudança no cliente web, versão incompatível, limite de recursos ou restrição do próprio WhatsApp. Não existe uma única “mudança da Meta em janeiro” que explique todos os casos. O diagnóstico precisa separar falha técnica de restrição da conta.
A Evolution oferece integrações por mais de um motor. A própria documentação do projeto distingue conexões baseadas em Baileys e integrações com a API oficial. Baileys reproduz o protocolo do WhatsApp Web e não equivale à WhatsApp Business Platform.
Primeiro: registre o sintoma real
- processo reinicia: investigue memória, CPU, banco, Redis, disco e logs do container;
- socket fecha e reconecta: observe código de desconexão, rede e concorrência de sessões;
- QR volta a aparecer: a sessão pode ter sido invalidada ou removida no aparelho;
- aplicativo mostra restrição: pare automações e siga o fluxo oficial de recurso;
- mensagens chegam, mas não saem: verifique webhook, fila, credencial e regras de envio.
Faça backup do banco e da configuração antes de atualizar. Não apague sessão, volume ou instância como primeira tentativa: isso destrói evidência e pode obrigar novo pareamento.
Causas técnicas frequentes
Versão e protocolo
Clientes não oficiais dependem de mudanças no WhatsApp Web. Uma atualização pode exigir nova versão do conector. Compare sua versão com as notas e issues do repositório, sem presumir que o relato de outro ambiente é a mesma causa.
Mais de uma sessão
Duas instâncias tentando usar a mesma identidade podem invalidar estado ou produzir comportamento intermitente. Confirme processos duplicados, réplicas e volumes montados.
Infraestrutura
Memória esgotada, banco lento, Redis indisponível, proxy com timeout e disco cheio aparecem para o usuário como “WhatsApp caiu”. Correlacione o horário da desconexão com métricas e logs.
Webhook e fila
Uma instância conectada pode parecer parada quando o webhook falha ou a fila acumula. Teste recebimento, persistência, processamento e envio como etapas separadas.
Quando há restrição da conta
O WhatsApp informa que aplicativos não oficiais e automação ou envio em massa não autorizados violam seus termos e podem resultar em restrições temporárias ou permanentes. Veja as páginas oficiais sobre aplicativos não oficiais e automação ou mensagens em massa não autorizadas.
- interrompa disparos e rotinas automáticas;
- não tente parear repetidamente em vários servidores;
- registre a mensagem exata exibida no aplicativo;
- use o recurso oferecido pelo próprio WhatsApp;
- revise origem dos contatos, opt-in, frequência e conteúdo;
- planeje migração se o uso é comercial e contínuo.
API oficial versus conexão por WhatsApp Web
| Critério | WhatsApp Business Platform | Conector via Web |
|---|---|---|
| Canal autorizado | Sim, conforme conta e políticas | Não equivale à plataforma oficial |
| Templates | Exigidos em conversas iniciadas pela empresa quando aplicável | Não cria autorização para envio |
| Webhooks | Contratados e documentados pela Meta | Dependem do projeto e da sessão Web |
| Risco operacional | Ligado a qualidade, política e configuração | Inclui mudanças do cliente Web e restrição por uso não autorizado |
A escolha não deve considerar apenas custo de mensagem. Inclua risco de perder o número, indisponibilidade, suporte, qualidade do opt-in e custo de migração.
Roteiro de diagnóstico sem apagar dados
- confirme saúde do processo e dependências;
- capture logs no minuto da falha;
- identifique o código de desconexão;
- verifique se existe outra sessão ativa;
- teste webhook e fila de forma isolada;
- confira a mensagem no aparelho;
- faça backup;
- só então avalie atualização, novo pareamento ou migração.
Fontes e limite da análise
Usamos a documentação da Evolution API e as orientações oficiais do WhatsApp sobre apps não oficiais e automação não autorizada. Sem logs, versão e código de desconexão não é possível atribuir a causa de uma instância específica.