WACrew

Blog

Baileys: como funciona a biblioteca de WhatsApp Web, para desenvolvedores

Guia do Baileys para desenvolvedores. Como a biblioteca conecta ao WhatsApp Web por WebSocket, sessão, eventos, JIDs e LID, exemplo de bot e os cuidados para não perder a conta.

Por Rodrigo Sumioshi 6 min de leitura
Neste artigo
  1. O que é o Baileys
  2. Instalação
  3. Como a conexão funciona
  4. Um bot mínimo, linha por linha
  5. JIDs: como o WhatsApp identifica cada conversa
  6. Cuidados para não perder a conta
  7. Baileys direto ou uma camada em cima?
  8. Resumo

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 printQRInTerminal está descontinuada. Você recebe o campo qr em connection.update e 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.
  • fromMe evita 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:

TipoFormatoExemplo
Pessoa (telefone)[país][número]@s.whatsapp.net5511999999999@s.whatsapp.net
Pessoa (LID)[id]@lid123456789012345@lid
Grupo[id]@g.us123456789-123345@g.us
Statusstatus@broadcastfixo

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:

  1. Converse com quem já fala com você. Mandar mensagem em volume para quem nunca falou com você é o principal gatilho de bloqueio.
  2. Ritmo de pessoa. Responder sempre em dois segundos, sem "digitando", não parece gente.
  3. Nada de disparo em massa. A documentação desencoraja isso explicitamente.
  4. 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.