O Baileys é a biblioteca que está por baixo de boa parte das APIs de WhatsApp não oficiais do mercado. Evolution API, vários bots de atendimento e o próprio WACrew usam ele para falar com o WhatsApp. Se você vai construir algo nessa linha, entender como ele funciona evita muita surpresa em produção.
Este guia explica o funcionamento, mostra um bot mínimo em TypeScript e lista os cuidados que a própria documentação pede. Tudo foi conferido no README do projeto e no guia novo em baileys.wiki.
O que é o Baileys
Segundo o próprio projeto, o Baileys é uma biblioteca em TypeScript, baseada em WebSockets, para interagir com a API do WhatsApp Web. Na prática, ele se conecta ao WhatsApp como mais um aparelho vinculado da sua conta, do mesmo jeito que o WhatsApp Web no navegador.
A diferença para soluções antigas é que não existe navegador no meio. Nada de Selenium nem Chromium aberto em segundo plano. O Baileys fala direto com os servidores do WhatsApp pelo WebSocket, o que economiza memória e deixa o processo mais estável.
Dois avisos aparecem logo no começo da documentação. O projeto não tem vínculo com o WhatsApp, e os mantenedores não apoiam uso que viole os termos de serviço, como spam, disparo em massa ou monitoramento escondido.
Instalação
O Baileys pede Node.js 20 ou mais novo e trava a instalação em versões antigas. A documentação usa o pacote com escopo.
npm install @whiskeysockets/baileys @hapi/boom
O @hapi/boom é usado para ler o código de erro quando a conexão cai. Existe também a versão "edge", instalada direto do GitHub, com as correções mais recentes e sem garantia de estabilidade.
Como a conexão funciona
O ciclo de vida tem três peças: o estado de autenticação, o socket e os eventos.
1. Estado de autenticação. Quando você vincula o aparelho, o WhatsApp entrega credenciais e chaves de criptografia (o protocolo Signal). Elas precisam ser salvas, senão você escaneia o QR de novo a cada reinício. O utilitário useMultiFileAuthState guarda tudo numa pasta:
import makeWASocket, { useMultiFileAuthState } from "@whiskeysockets/baileys";
const { state, saveCreds } = await useMultiFileAuthState("auth_info_baileys");
A própria documentação recomenda tratar essa pasta como segredo. Ela contém chaves de longa duração da sua conta, então fica fora do repositório e no .gitignore. Para produção, o README sugere usar o utilitário como modelo e gravar o estado num banco de dados.
2. Socket. É a conexão em si. Você cria com o estado de autenticação:
const sock = makeWASocket({ auth: state });
3. Eventos. Tudo o que acontece chega por sock.ev.on(...). Os três que todo projeto usa:
connection.update: QR code, conexão aberta, conexão fechada;messages.upsert: mensagens novas;creds.update: as credenciais mudaram e precisam ser salvas.
Um bot mínimo, linha por linha
Este exemplo segue o quickstart oficial. Ele conecta, mostra o QR no terminal, reconecta quando cai e responde quem mandar mensagem:
import makeWASocket, { DisconnectReason, useMultiFileAuthState } from "@whiskeysockets/baileys";
import { Boom } from "@hapi/boom";
import qrcode from "qrcode-terminal";
async function conectar() {
const { state, saveCreds } = await useMultiFileAuthState("auth_info_baileys");
const sock = makeWASocket({ auth: state });
sock.ev.on("connection.update", ({ connection, lastDisconnect, qr }) => {
if (qr) qrcode.generate(qr, { small: true });
if (connection === "close") {
const codigo = (lastDisconnect?.error as Boom)?.output?.statusCode;
if (codigo !== DisconnectReason.loggedOut) conectar(); // caiu, mas não foi logout
}
});
sock.ev.on("messages.upsert", async ({ type, messages }) => {
if (type !== "notify") return; // ignora sincronização de histórico
for (const m of messages) {
if (m.key.fromMe) continue;
await sock.sendMessage(m.key.remoteJid!, { text: "Recebi sua mensagem." });
}
});
sock.ev.on("creds.update", saveCreds);
}
conectar();
Pontos que merecem atenção:
- O QR vem no evento. A opção antiga
printQRInTerminalestá descontinuada. Você recebe o campoqremconnection.updatee desenha como quiser. type: "notify"separa mensagem nova de mensagem que veio da sincronização do histórico. Sem esse filtro, o bot responde conversas antigas quando conecta.fromMeevita que o bot responda a si mesmo.messagesé uma lista. A documentação recomenda sempre percorrer todas, porque um evento pode trazer várias de uma vez.
Na primeira execução, abra o WhatsApp no celular, vá em Aparelhos conectados, toque em Conectar um aparelho e escaneie. Nas próximas, a sessão salva é reaproveitada. Se preferir não escanear, existe o código de pareamento de 8 dígitos, digitado no celular.
JIDs: como o WhatsApp identifica cada conversa
Todo destino no Baileys é um JID, no formato local@servidor. Os mais comuns:
| Tipo | Formato | Exemplo |
|---|---|---|
| Pessoa (telefone) | [país][número]@s.whatsapp.net | 5511999999999@s.whatsapp.net |
| Pessoa (LID) | [id]@lid | 123456789012345@lid |
| Grupo | [id]@g.us | 123456789-123345@g.us |
| Status | status@broadcast | fixo |
O LID é a pegadinha atual. O WhatsApp passou a identificar pessoas em grupos por um identificador opaco, que esconde o número de telefone. Segundo o guia, esse é o identificador padrão no Baileys 7. A mesma pessoa pode aparecer como telefone numa conversa individual e como LID num grupo. Se o seu sistema guarda histórico por contato, precisa juntar os dois, senão a pessoa vira duas.
Cuidados para não perder a conta
O Baileys não é a API oficial. A conta pode ser restringida se o uso parecer automação abusiva. Alguns cuidados que reduzem o risco:
- Converse com quem já fala com você. Mandar mensagem em volume para quem nunca falou com você é o principal gatilho de bloqueio.
- Ritmo de pessoa. Responder sempre em dois segundos, sem "digitando", não parece gente.
- Nada de disparo em massa. A documentação desencoraja isso explicitamente.
- Guarde o estado com cuidado. Perder as chaves derruba a sessão, e chaves desatualizadas impedem a entrega das mensagens.
O texto sobre API de WhatsApp não oficial e banimento compara o que cada projeto diz sobre esse risco.
Baileys direto ou uma camada em cima?
Usar o Baileys direto dá controle total, mas você assume reconexão, armazenamento de sessão, fila de envio, mídia e a fusão de LID com telefone. Por isso existem projetos que embrulham a biblioteca.
- APIs HTTP como Evolution API e WAHA expõem o Baileys (ou outro motor) como serviço REST com webhooks. A comparação está em WAHA ou Evolution API.
- Aplicações prontas como o WACrew usam o Baileys por baixo e entregam painel, histórico, transcrição de áudio e um servidor MCP para agentes de IA. No WACrew, o Baileys fica isolado atrás de adaptadores, então o resto do código não depende dos detalhes da biblioteca.
Resumo
O Baileys conecta ao WhatsApp como um aparelho vinculado, direto por WebSocket, sem navegador. Você salva o estado de autenticação, cria o socket e reage aos eventos connection.update, messages.upsert e creds.update. Fique de olho no LID, filtre mensagens de sincronização e trate o uso com o cuidado que uma conta pessoal merece.
Se a ideia é rodar isso o dia inteiro, o guia como hospedar um bot de WhatsApp 24 horas mostra as opções de servidor.



