Baileys is the library under a good part of the unofficial WhatsApp APIs out there. Evolution API, a lot of support bots and WACrew itself use it to talk to WhatsApp. If you are building something along those lines, understanding how it works saves you a lot of surprises in production.
This guide explains how it works, shows a minimal bot in TypeScript and lists the precautions the documentation itself asks for. Everything was checked against the project README and the newer guide at baileys.wiki.
What Baileys is
In the project's own words, Baileys is a WebSocket-based TypeScript library for interacting with the WhatsApp Web API. In practice it connects to WhatsApp as one more linked device on your account, the same way WhatsApp Web does in a browser.
The difference from older approaches is that there is no browser in the middle. No Selenium, no Chromium running in the background. Baileys talks directly to WhatsApp's servers over the WebSocket, which saves memory and makes the process more stable.
Two warnings show up right at the start of the docs. The project is not affiliated with WhatsApp, and the maintainers do not condone use that violates the terms of service, such as spam, bulk messaging or covert monitoring.
Installation
Baileys requires Node.js 20 or newer and refuses to install on older versions. The docs use the scoped package:
npm install @whiskeysockets/baileys @hapi/boom
@hapi/boom is used to read the error code when the connection drops. There is also an "edge" build, installed straight from GitHub, with the latest fixes and no stability guarantee.
How the connection works
The lifecycle has three pieces: the auth state, the socket and the events.
1. Auth state. When you link the device, WhatsApp hands over credentials and encryption keys (the Signal protocol). They must be saved, or you will scan the QR code again on every restart. The useMultiFileAuthState helper stores everything in a folder:
import makeWASocket, { useMultiFileAuthState } from "@whiskeysockets/baileys";
const { state, saveCreds } = await useMultiFileAuthState("auth_info_baileys");
The documentation recommends treating that folder as a secret. It holds long-lived keys for your account, so it stays out of the repository and in .gitignore. For production, the README suggests using the helper as a model and storing the state in a database.
2. Socket. The connection itself, created with the auth state:
const sock = makeWASocket({ auth: state });
3. Events. Everything that happens arrives through sock.ev.on(...). The three every project uses:
connection.update: QR code, connection open, connection closed;messages.upsert: new messages;creds.update: credentials changed and need to be saved.
A minimal bot, line by line
This example follows the official quickstart. It connects, prints the QR code in the terminal, reconnects when the connection drops and replies to anyone who writes:
import makeWASocket, { DisconnectReason, useMultiFileAuthState } from "@whiskeysockets/baileys";
import { Boom } from "@hapi/boom";
import qrcode from "qrcode-terminal";
async function connect() {
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 code = (lastDisconnect?.error as Boom)?.output?.statusCode;
if (code !== DisconnectReason.loggedOut) connect(); // dropped, but not a logout
}
});
sock.ev.on("messages.upsert", async ({ type, messages }) => {
if (type !== "notify") return; // skip history sync
for (const m of messages) {
if (m.key.fromMe) continue;
await sock.sendMessage(m.key.remoteJid!, { text: "Got your message." });
}
});
sock.ev.on("creds.update", saveCreds);
}
connect();
Things worth noticing:
- The QR code comes in the event. The old
printQRInTerminaloption is deprecated. You get theqrfield inconnection.updateand render it however you like. type: "notify"separates new messages from messages that came in through history sync. Without that filter, the bot replies to old chats when it connects.fromMestops the bot from answering itself.messagesis an array. The docs recommend always looping over all of them, because one event can carry several.
On the first run, open WhatsApp on your phone, go to Linked devices, tap Link a device and scan. After that, the saved session is reused. If you would rather not scan, there is an 8-character pairing code you type on the phone.
JIDs: how WhatsApp identifies each chat
Every destination in Baileys is a JID, in the form local@server. The common ones:
| Type | Format | Example |
|---|---|---|
| Person (phone) | [country][number]@s.whatsapp.net | 14155550123@s.whatsapp.net |
| Person (LID) | [id]@lid | 123456789012345@lid |
| Group | [id]@g.us | 123456789-123345@g.us |
| Status | status@broadcast | fixed |
The LID is the current gotcha. WhatsApp started identifying people in groups with an opaque identifier that hides the phone number, and according to the guide it is the default identifier in Baileys 7. The same person can show up as a phone number in a direct chat and as a LID in a group. If your system keeps history per contact, it has to merge the two, or one person turns into two.
Precautions that keep the account alive
Baileys is not the official API. The account can be restricted if usage looks like abusive automation. A few habits lower the risk:
- Talk to people who already talk to you. Messaging strangers at volume is the main trigger for a ban.
- Human pacing. Always replying in two seconds, with no "typing", does not look like a person.
- No bulk messaging. The documentation explicitly discourages it.
- Store the auth state carefully. Losing the keys kills the session, and stale keys stop messages from being delivered.
The guide to WhatsApp automation without getting banned goes deeper into the rules.
Baileys directly or a layer on top?
Using Baileys directly gives you full control, but you own reconnection, session storage, the send queue, media and merging LIDs with phone numbers. That is why there are projects that wrap the library.
- HTTP APIs like Evolution API and WAHA expose Baileys (or another engine) as a REST service with webhooks. The comparison is in WAHA vs Evolution API, and a wider list is in open-source WhatsApp APIs.
- Ready-made applications like WACrew use Baileys underneath and deliver a panel, history, voice note transcription and a WhatsApp MCP server for AI agents. In WACrew, Baileys sits behind adapters, so the rest of the code does not depend on the library's details.
Summary
Baileys connects to WhatsApp as a linked device, directly over a WebSocket, with no browser. You save the auth state, create the socket and react to connection.update, messages.upsert and creds.update. Keep an eye on LIDs, filter history-sync messages and treat the account with the care a real number deserves.
Next steps: turn this into an agent with building a Baileys AI agent, or see how Baileys compares with the Go library behind lharries/whatsapp-mcp in whatsmeow vs Baileys.



