# 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, 14 de novembro de 2026. Original: https://wacrew.com.br/blog/baileys-whatsapp/

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](https://wacrew.com.br/agente-de-ia-whatsapp/) 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](https://github.com/WhiskeySockets/Baileys) e no guia novo em [baileys.wiki](https://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.

```bash
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:

```ts
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:

```ts
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:

```ts
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:

| 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:

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](https://wacrew.com.br/api-whatsapp-nao-oficial-risco/) 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](https://wacrew.com.br/waha-vs-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](https://wacrew.com.br/servidor-mcp-whatsapp/) 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](https://wacrew.com.br/blog/hospedar-bot-whatsapp-24-horas/) mostra as opções de servidor.
