--- title: "Por que, na minha experiência, as bibliotecas de WhatsApp sempre acabam quebrando" slug: whatsapp-libs-problemas date: 2025-10-20 category: "Arquitetura" tags: ["whatsapp", "arquitetura", "mensageria", "infraestrutura", "estabilidade", "engenharia"] readTime: "6 min" excerpt: "Um olhar pessoal e técnico sobre os motivos pelos quais integrações com o WhatsApp vivem em constante instabilidade — com base em experiências reais em projetos de larga escala." url: https://eliseu.dev/blog/whatsapp-libs-problemas --- # Por que, na minha experiência, as bibliotecas de WhatsApp sempre acabam quebrando Este texto não é uma crítica a nenhum projeto ou desenvolvedor. É apenas **a minha visão pessoal**, baseada em **experiências reais** com 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, não pontual. ## 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](https://github.com/WhiskeySockets/Baileys) afirma que se trata de uma *"implementação não oficial da API do WhatsApp Web"*, enquanto o [Whatsmeow](https://github.com/tulir/whatsmeow) também descreve-se como *"uma biblioteca Go para o WhatsApp Web multidevice baseada em engenharia reversa"*. Artigos como o da [Devzery](https://www.devzery.com/post/baileys-library-unofficial-whatsapp-web-api-for-typescript-js) 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](https://digisac.com.br/jid-lid-no-whatsapp/)). ## 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](https://github.com/tulir/whatsmeow/issues?q=LTHash)** — falhas na sincronização do estado do aplicativo que causam inconsistências nos dados - **[Failed to store LID-PN mapping](https://github.com/tulir/whatsmeow/issues?q=LID-PN)** — erros ao armazenar mapeamentos de identificadores, quebrando a comunicação **Problemas de Conexão e Autenticação:** - **[QR Code scanning failures](https://github.com/WhiskeySockets/Baileys/issues?q=QR+code)** — falhas recorrentes ao escanear códigos QR para autenticação - **[Session corruption](https://github.com/WhiskeySockets/Baileys/issues?q=session)** — corrupção de sessões quando múltiplas instâncias acessam os mesmos arquivos - **[Unexpected disconnections](https://github.com/tulir/whatsmeow/issues?q=disconnect)** — desconexões inesperadas após chamadas manuais de `Disconnect()` **Problemas de Funcionalidade:** - **[Group description modification errors (409)](https://github.com/tulir/whatsmeow/issues?q=409)** — erros ao modificar descrições de grupos pela segunda vez - **[Incorrect pairing code events](https://github.com/tulir/whatsmeow/issues?q=pairing)** — eventos incorretos ao inserir códigos de pareamento - **[Messages sent to own number](https://github.com/tulir/whatsmeow/discussions/637)** — mensagens sendo enviadas para o próprio número em vez do destinatário **Problemas de Dados:** - **[GetAllContacts returning deleted contacts](https://github.com/tulir/whatsmeow/issues?q=GetAllContacts)** — função retornando contatos já deletados - **[Profile picture info failures](https://github.com/tulir/whatsmeow/issues?q=profile+picture)** — falhas ao obter informações de fotos de perfil causando desconexões Essas falhas não são bugs simples — são **efeitos de arquitetura não distribuída** e falta de coordenação entre instâncias. ## 3. Escalabilidade reativa, não planejada 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"](https://github.com/WhiskeySockets/Baileys/issues/1559) 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)](https://github.com/tulir/whatsmeow/issues/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](https://github.com/WhiskeySockets/Baileys/commits/master/?since=2024-02-01&until=2024-04-30) 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, não de código Com base em tudo que vivi, posso dizer que o desafio não é "corrigir bugs", mas **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 em experiências reais —, o problema **não são as bibliotecas**. Elas são incríveis pelo que entregam, considerando as limitações. Mas 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. > Não é uma crítica, mas um convite à reflexão sobre **como projetar integrações mais estáveis e conscientes** para o futuro.