Por que, na minha experiência, as bibliotecas de WhatsApp sempre acabam quebrando

Este texto traz a minha visão pessoal, sem crítica a nenhum projeto ou desenvolvedor.
Ela vem do que vivi em integrações de larga escala usando bibliotecas populares como Baileys, Whatsmeow e WPPConnect.

Ao longo dos anos, percebi que, independente da linguagem ou do autor, os mesmos problemas se repetem.
E, na minha opinião, o motivo é estrutural.

1. O WhatsApp nunca foi uma API pública

Tudo começa pelo fato de que o WhatsApp não é uma API pública oficial.
Todas as libs que conhecemos hoje foram criadas a partir de engenharia reversa sobre o WhatsApp Web.

O próprio README do Baileys afirma que se trata de uma “implementação não oficial da API do WhatsApp Web”, enquanto o Whatsmeow também descreve-se como “uma biblioteca Go para o WhatsApp Web multidevice baseada em engenharia reversa”.

Artigos como o da Devzery reforçam isso:

“Baileys é uma biblioteca não oficial e está sujeita a quebras sempre que o WhatsApp muda seu protocolo.”

Ou seja:

• Não há documentação pública nem contrato de API.
• Qualquer atualização da Meta pode quebrar compatibilidade.
• As libs precisam “descobrir” o que mudou manualmente.

E isso acontece com frequência: mudanças como a migração de jid para lid causaram falhas globais relatadas pela comunidade (digisac).

2. Falta de isolamento e previsibilidade de estado

Outro problema comum que já enfrentei é o gerenciamento de estado local.
A maioria das libs mantém as credenciais da sessão em arquivos (auth.json, session.data, etc.), o que funciona bem para bots únicos, mas quebra em ambientes com múltiplas instâncias.

Na prática, isso causa:

• Corrupção de sessão quando duas instâncias usam o mesmo arquivo.
• Race conditions em reconexões.
• Desconexões aleatórias (“logged out”).

Esse tipo de falha é amplamente relatado pela comunidade, como:

Problemas de sincronização de estado:

• LTHash mismatches: falhas na sincronização do estado do aplicativo que causam inconsistências nos dados
• Failed to store LID-PN mapping: erros ao armazenar mapeamentos de identificadores, quebrando a comunicação

Problemas de conexão e autenticação:

• QR Code scanning failures: falhas recorrentes ao escanear códigos QR para autenticação
• Session corruption: corrupção de sessões quando múltiplas instâncias acessam os mesmos arquivos
• Unexpected disconnections: desconexões inesperadas após chamadas manuais de Disconnect()

Problemas de funcionalidade:

• Group description modification errors (409): erros ao modificar descrições de grupos pela segunda vez
• Incorrect pairing code events: eventos incorretos ao inserir códigos de pareamento
• Messages sent to own number: mensagens sendo enviadas para o próprio número em vez do destinatário

Problemas de dados:

• GetAllContacts returning deleted contacts: função retornando contatos já deletados
• Profile picture info failures: falhas ao obter informações de fotos de perfil causando desconexões

Essas falhas vêm de uma arquitetura não distribuída e da falta de coordenação entre instâncias.

3. Escalabilidade reativa

Muitos times tentam escalar essas libs usando Redis, filas e workers (e isso é ótimo), mas não resolve a raiz do problema, que é a ausência de coordenação nativa entre instâncias.

Em setups reais, isso leva a:

• múltiplos pods disputando a mesma sessão;
• duplicação de mensagens;
• instabilidades intermitentes.

A própria comunidade tentou endereçar isso via extensões como projetos de armazenamento Redis para Baileys,
mas até esses projetos reconhecem limitações, pois o core da lib não foi desenhado para lock distribuído nem fencing.

O resultado é o que chamo de escalabilidade reativa: você adiciona componentes externos tentando corrigir um design que não nasceu para ser distribuído.

4. Dependência de eventos e schemas voláteis

O WhatsApp muda constantemente sua estrutura interna.
Campos surgem, desaparecem ou trocam de nome, e as libs precisam “adivinhar” o novo formato.

Cada atualização do WhatsApp Web exige:

• engenharia reversa dos novos pacotes binários;
• atualização dos schemas locais;
• e publicação de uma nova versão da lib.

Essas quebras são visíveis em repositórios como:

• Baileys - Issue #1559 “Message schema changed unexpectedly”

Sem um contrato formal, toda mudança vira um incêndio comunitário.

5. Falta de observabilidade

Poucas dessas libs oferecem métricas ou logs estruturados que ajudem a entender o que está acontecendo em tempo real.
Quando algo quebra, o log padrão mostra apenas "disconnected".

Isso torna impossível responder perguntas como:

• Quantas sessões estão realmente ativas?
• Qual o tempo médio entre reconexões?
• Há padrões de erro por região?

Há tentativas de melhorar isso, como a feature request de métricas no Whatsmeow (#921),
mas ainda não existe uma camada de telemetria padronizada no ecossistema.

E sem telemetria, não existe previsibilidade.

6. Quando a Meta muda, tudo quebra em cascata

Esse é o ponto mais delicado que já presenciei em operações reais.

O WhatsApp muda o protocolo →
as libs quebram →
os gateways caem →
e cada empresa tenta corrigir por conta própria.

Em 2024, por exemplo, uma alteração no handshake do WebSocket causou falhas simultâneas em múltiplos projetos.
Isso pode ser visto nos commits e discussões do Baileys entre fevereiro e abril de 2024,
um período em que diversos PRs de correção foram mesclados em sequência.

Essas ondas de instabilidade mostram que a comunidade inteira depende do mesmo ponto frágil:
um protocolo proprietário que muda sem aviso.

7. O problema é estrutural

Com base em tudo que vivi, posso dizer que corrigir bugs não basta:
o desafio é repensar a arquitetura.

Falta às libs:

• isolamento de falhas (actor model, supervision tree);
• coordenação distribuída (ownership + fencing tokens);
• observabilidade nativa (metrics, traces);
• mecanismos automáticos de mitigação de mudanças (circuit breakers adaptativos e fallbacks inteligentes quando a Meta alterar contratos);
• canary-driven monitoring
• contract-driven development (CDD)
• feature-flag first
• observability-driven engineering
• chaos & mutation testing
• policy-based mitigation
• human-in-the-loop for code-gen

Esses conceitos existem em sistemas como Kafka, NATS JetStream e Erlang OTP,
mas ainda são raros no ecossistema de bibliotecas para WhatsApp.

Minha conclusão

Na minha opinião, baseada no que vivi, o problema não está nas bibliotecas.
Elas são incríveis pelo que entregam, considerando as limitações.
O que falta é uma camada de infraestrutura resiliente, capaz de lidar com mudanças, sincronizar estado e escalar com previsibilidade.

Enquanto isso não existir,
as integrações com o WhatsApp continuarão sendo como um castelo de areia:
impressionante quando está de pé, mas vulnerável à próxima onda.

Este texto reflete minha experiência pessoal e profissional, operando grandes volumes de sessões WhatsApp em produção.
Fica como convite à reflexão sobre como projetar integrações mais estáveis.