Baileys: a WebSockets library for the WhatsApp Web API

The problem Baileys solves for TypeScript services

WhatsApp's own interface is a browser client. If a backend service needs to read or send messages on an account, the obvious route is browser automation: run a headless Chromium, keep the session alive, and scrape the DOM. That route ties your service to a browser process, a page layout you do not control, and a memory footprint far larger than the messaging logic itself.

Baileys takes the other route. It speaks the WhatsApp Web protocol directly over a WebSocket from a TypeScript library, so the unit of deployment is a Node process rather than a browser. The package.json describes it as "A WebSockets library for interacting with WhatsApp Web", and the README frames it as a TypeScript library for the WhatsApp Web API. The audience is therefore backend and tooling engineers: people wiring WhatsApp into an existing service, a bot, or an internal dashboard where a browser dependency would be awkward.

The repository topics list bun, deno, nodejs, reverse-engineering, typescript and websockets. That mix is honest about what this is. It is a client for a protocol that was not published for third parties, and the reverse-engineering topic is part of the package's identity rather than a footnote.

How the WebSocket protocol layer and WAProto fit together

The architecture is visible in the repository layout. src/ holds the library, WAProto/ holds the protobuf definitions, and proto-extract/ and scripts/ hold the tooling that keeps the generated types in step with the protocol. The npm package ships lib/**/*, WAProto/**/* and engine-requirements.js, so a consumer gets the compiled output and the protobuf artifacts, not the TypeScript sources.

WhatsApp Web messages are protobuf-encoded, which is why the protobuf layer is a first-class directory rather than an internal detail. The package exposes a gen:protobuf script that runs WAProto/GenerateStatics.sh, and WAProto/ is published, so the generated statics are part of the public surface. When the upstream protocol changes, that generation step is where the definitions are refreshed.

The build is a two-stage TypeScript compile: tsc -P tsconfig.build.json followed by tsc-esm-fix, which rewrites the emitted JavaScript for ESM. The package sets "type": "module" and points main at lib/index.js with types at lib/index.d.ts. In practice that means the library is ESM-first, and a CommonJS consumer has to deal with that boundary rather than assuming a require() will work unchanged.

One more structural detail matters for deployment: preinstall runs node ./engine-requirements.js. The engine check fires before the library is installed, not when it is first imported, so an unsupported runtime fails at install time.

Installing Baileys and running the bundled example

The package is published on npm under the name baileys. Install it with your package manager of choice:

npm install baileys

The repository is a Yarn project, with .yarnrc.yml and yarn.lock at the top level, so a contributor working from source would clone it and install with Yarn instead. For a consumer, the npm package is the normal path. If the engine check rejects your runtime, the error comes from engine-requirements.js during the preinstall step rather than from the library at runtime.

The repository ships a runnable example at Example/example.ts, and package.json wires it to a script:

npm run example

That script runs tsx ./Example/example.ts. Because it is defined in the project's own package.json, it is available when you work inside the repository, not when you install baileys as a dependency in your own project. Read Example/example.ts for the connection and event wiring before writing your own entry point; the README does not reproduce it inline.

For working from source, the standard build and test commands are:

npm run build
npm test

The build script compiles with tsconfig.build.json and then applies tsc-esm-fix. The test script runs Jest with the experimental VM modules flag and matches **/*.test.ts. There is a separate test:e2e script that sets NODE_TLS_REJECT_UNAUTHORIZED=0 and runs the *-test-e2e.ts files in band; that flag disables TLS certificate verification, so treat it as a repository test harness and not as a pattern for your own service.

The 7.0.0 migration is the real upgrade cost

The README opens with a caution banner: as of 7.0.0, multiple breaking changes were introduced, and it points to https://whiskey.so/migrate-latest. The current release line is v7.0.0-rc14, published on 2026-07-29, while v6.7.24 landed the same day. A release candidate carrying the major version number tells you the 7.x API is still settling, and the migration guide is the document that decides whether an upgrade is a small edit or a rewrite of your connection and auth handling.

The documentation situation compounds this. The README states plainly that the new guide at baileys.wiki is a work in progress with missing pages and content, and directs readers to the old guide in README.md on the master branch or the npm homepage. So there are two documentation surfaces, one explicitly incomplete, and the migration notes live on a third site. Before committing to 7.x, check that the pages covering your integration exist rather than assuming the wiki is complete.

The disclaimer is the other constraint worth reading closely. The project is not affiliated with, authorized by or endorsed by WhatsApp, and the maintainers state that they do not condone use in practices that violate WhatsApp's Terms of Service, discouraging stalkerware, bulk and automated messaging. That is a stated boundary, not a technical limitation, and it is the maintainers' own framing of who the library is for.

Where Baileys is the wrong tool

The clearest mismatch is messaging at volume. The README discourages bulk and automated messaging, so a growth or broadcast system built on Baileys is running against the maintainers' stated intent and against WhatsApp's Terms of Service. If your requirement is to send to a large list, this library is not the right layer, regardless of what it can technically do.

A second mismatch is anything that needs a supported contract. Baileys is a reverse-engineered client for an interface WhatsApp does not publish for third parties. There is no compatibility guarantee from the other side, and the protobuf generation step exists precisely because the wire format is not fixed by a public spec. If your product needs a vendor who will answer for protocol changes, an official business messaging API is the appropriate choice and Baileys is not.

A third case is operational simplicity. You take on session persistence, reconnection behaviour and the upgrade treadmill that the 7.0.0 banner describes. For a small internal notification, that cost may exceed the value. The library makes sense when a programmatic WhatsApp session is central to the service, not incidental to it.

Baileys against a browser automation client

The real alternative for most teams is a browser automation client such as Puppeteer or Playwright driving WhatsApp Web. The difference is where the protocol boundary sits. Browser automation keeps the official web client and controls it from outside: you get the client's own handling of the protocol, and you pay for it with a Chromium process, a page whose DOM you do not own, and selectors that break when the client is redeployed.

Baileys moves the boundary down. It implements the WebSocket protocol and the protobuf layer itself, which is why WAProto/ and proto-extract/ exist in the repository. You get a smaller runtime and direct access to protocol-level events, and you take responsibility for keeping up with a format that is not published for you. The trade is control against maintenance.

There is a third option worth naming: WhatsApp's own business messaging APIs. Those are supported interfaces with a vendor behind them, and they are the right answer when the requirement is compliance and stability rather than protocol access. Baileys occupies the space between: more direct than browser automation, less supported than an official API.

Maintenance, licence and what MIT does not cover

The repository is not archived, and the last push was on 2026-09-20. Releases are frequent: v7.0.0-rc14 and v6.7.24 both landed on 2026-07-29, with v7.0.0-rc13 before them on 2026-05-21. The maintenance picture is therefore active, but it is also split across two lines, a stable 6.x and a release-candidate 7.x, which means you should decide deliberately which one you track rather than floating on a range.

The licence is MIT, copyright Rajeh Taher/WhiskeySockets. MIT permits commercial use and modification with the copyright notice and permission notice retained, and it disclaims warranty. The README carries a second layer that the licence does not: the disclaimer separating the project from WhatsApp, and the statement against bulk and automated messaging. Those are not licence terms, but they are the maintainers' position, and anyone building a commercial product on Baileys should read them alongside the MIT text rather than treating the permissive licence as the whole story. This is a description of what the files say, not legal advice.

On upgrade cost, the concrete signal is the 7.0.0 breaking-change notice plus the migration page at https://whiskey.so/migrate-latest. The repository also keeps CHANGELOG.md and a changelog:update script built on conventional-changelog, so the release history is machine-generated from commits. Pin a version, read the changelog entries between your pin and the target, and use the migration page for the major jump.

Editorial conclusion

Adopt Baileys if you are building a Node, Bun or Deno service that needs a programmatic WhatsApp Web session and you can absorb the 7.0.0 breaking changes before upgrading. Do not adopt it for bulk or automated messaging; the maintainers state they discourage it, and the project is not affiliated with WhatsApp. Before writing code, read https://whiskey.so/migrate-latest against your current version, and check src/ and WAProto/ for the event and protobuf shapes your integration depends on.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. WhiskeySockets/Baileys on GitHub