Baileys: o que é e o que muda ao rodar sozinho em produção
Toda vez que alguém investiga como funciona uma API de WhatsApp não oficial, o caminho termina no mesmo lugar: Baileys. É a camada mais baixa da pilha, a peça que efetivamente conversa com os servidores do WhatsApp. Entender o que ela faz — e o que ela deliberadamente não faz — é o que permite decidir entre integrá-la direto no seu código ou consumir uma camada acima.
Este artigo é sobre a biblioteca em si. Se o que você procura é a camada de servidor construída sobre ela, o assunto está em Evolution API: o que é e como funciona.
O que é Baileys
Baileys é uma biblioteca open source em TypeScript que implementa o protocolo do WhatsApp multi-dispositivo. Ela abre uma conexão WebSocket direta com os servidores do WhatsApp e fala o mesmo idioma que o WhatsApp Web fala — mensagens binárias, criptografia ponta a ponta, sincronização de estado.
O detalhe que a torna interessante: não há navegador envolvido. Soluções antigas automatizavam um Chrome headless com Puppeteer ou Selenium, o que consumia centenas de megabytes por sessão e quebrava a cada mudança de interface. Baileys dispensa isso inteiramente. Uma sessão é um WebSocket e um punhado de chaves criptográficas na memória.
Na prática, ela oferece as primitivas:
- Parear um número por QR Code ou código de pareamento
- Manter a sessão viva e reconectar
- Enviar texto, mídia, áudio, documento, localização, botões e listas
- Receber mensagens e eventos em tempo real
- Consultar presença, grupos, contatos e status
O que ela não oferece é tudo o que transforma isso em serviço: não tem API HTTP, não tem painel, não tem banco, não tem fila, não tem autenticação de usuário, não tem isolamento entre clientes.
Como uma sessão realmente funciona
Vale entender o ciclo, porque é dele que saem quase todos os problemas de produção.
O pareamento
Você inicia um socket, o WhatsApp devolve um QR Code, o celular lê. Nesse momento acontece uma troca de chaves: o aparelho autoriza um novo dispositivo vinculado e entrega o material criptográfico que representa essa autorização.
O estado de autenticação
É a parte que mais gente subestima. Uma sessão não é "um token". São credenciais mais um conjunto de chaves de sinalização que muda ao longo do tempo, conforme você troca mensagens com contatos diferentes. A biblioteca oferece um utilitário que guarda tudo isso em arquivos (useMultiFileAuthState), e o material precisa ser persistido a cada alteração.
Se você perde esse estado, perde a sessão. Não existe "recuperar": tem que ler o QR Code de novo, no celular, presencialmente.
Consequência direta: o volume onde esse estado mora é o ativo mais crítico da operação. Container sem volume persistente, disco efêmero, deploy que recria o sistema de arquivos — cada um desses derruba todas as sessões de uma vez.
A reconexão
A conexão cai o tempo todo, por motivo banal: rede oscilou, servidor do WhatsApp reciclou a conexão, o processo reiniciou. A biblioteca emite um evento de atualização de conexão com um motivo, e cabe ao seu código decidir o que fazer com cada motivo.
E os motivos exigem tratamentos opostos. Queda de rede pede reconexão imediata. Conflito de sessão pede espera. Já um encerramento por logout — alguém removeu o aparelho vinculado no celular — significa que a credencial morreu: reconectar em laço nesse caso gera tentativas infinitas que nunca vão funcionar, e ainda apagam o rastro do que aconteceu.
Escrever esse tratamento corretamente, para cada motivo, é o primeiro trabalho de verdade de quem usa a biblioteca direto. As causas de queda no dia a dia e como monitorá-las estão em instância desconectou: causas e como reconectar.
O que você precisa construir em volta
Baileys resolve o protocolo. Uma operação precisa de mais sete camadas, e todas ficam por sua conta:
1. Persistência do estado de autenticação. Em arquivo com volume garantido, ou em banco com um adaptador escrito por você. Com backup — e com restauração testada, porque backup não testado é decoração.
2. Supervisão do processo. Quem reinicia quando o Node morre? Quem garante que uma sessão travada é recriada? Quem impede que duas cópias do mesmo processo abram a mesma sessão em paralelo e entrem em conflito?
3. Uma API HTTP. Baileys é uma biblioteca, não um servidor. Se o seu sistema em PHP precisa mandar uma mensagem, alguém tem que escrever o endpoint, a autenticação por chave, a validação de entrada, o rate limit e os códigos de erro.
4. Multi-sessão com isolamento. Cada número é um socket vivo, com memória própria. Dez números são dez sockets no mesmo processo — e um erro não tratado em um derruba o processo inteiro, levando os outros nove junto.
5. Armazenamento de mídia. Mídia recebida chega criptografada e precisa ser baixada, descriptografada e guardada em algum lugar. Mídia enviada precisa estar acessível. Sem uma política de retenção, o disco enche em semanas.
6. Fila e controle de ritmo. A biblioteca envia tão rápido quanto você mandar. Não existe freio embutido, e nada impede você de disparar em ritmo que derruba o número. A estrutura para isso está em rate limit e fila de mensagens.
7. Acompanhamento de versão do protocolo. Este é o custo recorrente e o que mais assusta quem não previu. O WhatsApp muda o protocolo sem aviso e sem obrigação nenhuma com integrações não oficiais. Quando muda, a biblioteca precisa acompanhar, e você precisa atualizar — às vezes com urgência, às vezes num sábado.
Quando usar Baileys direto faz sentido
Não é uma escolha errada. Ela é a escolha certa em três cenários:
Você está estudando o protocolo. Não existe forma melhor de entender como o WhatsApp funciona por dentro.
É um projeto de um número só, de baixo risco. Um bot pessoal, uma automação interna, um experimento. Se cair na sexta e voltar na segunda, ninguém perde dinheiro.
Você precisa de algo que nenhuma camada acima expõe. Comportamento de protocolo muito específico, controle fino sobre presença ou eventos que as APIs prontas não repassam.
Quando não faz sentido
Quando o WhatsApp é canal de receita. Se pedido, cobrança ou agendamento passam por ali, a pergunta não é "quanto custa a alternativa", é "quanto custa a hora em que ninguém consegue reconectar".
Quando você opera números de terceiros. Agência ou SaaS multi-cliente precisa de isolamento, painel, controle de acesso e cobrança. Construir isso é construir um produto inteiro ao lado do seu.
Quando não há plantão. Sessão cai de madrugada e no fim de semana. Sem alguém de sobreaviso, "auto-hospedado" na prática significa "indisponível até segunda".
O caminho do meio
Entre "escrever tudo em cima da biblioteca" e "usar uma API gerenciada" existe uma escala:
| Abordagem | Você mantém | Você ganha |
|---|---|---|
| Baileys direto | Tudo | Controle total do protocolo |
| Servidor open source auto-hospedado | Infra, atualização, plantão | API HTTP e multi-sessão prontas |
| API gerenciada | Só a sua integração | Painel, monitoramento, suporte |
O Zapixo fica na última linha: a stack não oficial roda gerenciada, e o que chega até você é uma API REST com chave, webhook e painel — sem volume de sessão para cuidar, sem madrugada de atualização. A comparação com a opção auto-hospedada, item a item, está em Evolution API self-hosted.
Resumo
Baileys é uma implementação sólida e elegante do protocolo multi-dispositivo do WhatsApp, e a base honesta de praticamente todo o ecossistema não oficial. O que ela não é — e nunca se propôs a ser — é um serviço pronto.
A pergunta certa antes de adotá-la direto não é "consigo fazer funcionar?". Quase sempre a resposta é sim, em uma tarde. A pergunta é: quem cuida do estado de sessão, da reconexão por motivo, da fila, do disco de mídia e da próxima mudança de protocolo? Se existe uma resposta clara para cada uma, o caminho direto é viável. Se não existe, a camada acima é mais barata do que parece.