whatsapp-web.js: a Node.js client that drives WhatsApp Web through Puppeteer

The gap whatsapp-web.js fills between the Business API and a browser tab

WhatsApp's official routes are the Business API and the consumer app. whatsapp-web.js takes a third path: it automates the WhatsApp Web client itself. The README describes it as a Node.js library that "lets you interact with WhatsApp Web, making it easy to build a dynamic WhatsApp API with nearly all features of the web client." The audience is developers building bots, notification senders, group administration tools, or internal dashboards on top of a personal or business WhatsApp account, in Node.js, without applying for Business API access.

The feature table in the README is the honest scope statement. Multi Device, sending and receiving messages, sending images, audio, documents and video, stickers, contact cards, location, replies, polls, channels, reactions, muting, blocking, profile pictures and group administration are all listed as supported. Sending buttons and sending lists are marked deprecated. Communities is marked as planned. If your product depends on interactive button messages, this library is the wrong tool, and the README says so in the same table it uses to advertise everything else.

Puppeteer, a managed browser, and why the session lives on disk

The mechanism is not a reimplementation of the WhatsApp protocol. The README states the library "uses Puppeteer to access WhatsApp Web's internal functions and runs them in a managed browser instance to reduce the risk of being blocked." So the data flow is: your Node process starts a Client, the Client launches Chromium through Puppeteer, loads web.whatsapp.com, and injects code that calls the page's own internal modules. Events such as qr, ready and message are surfaced back to your process. Every message you send is a browser action, not an HTTP call to an API.

That design explains the dependency list. puppeteer is a runtime dependency, not a dev one, pinned at 24.38.0 in package.json. fluent-ffmpeg, node-webpmux and mime are there for media handling and sticker packing. The practical consequence is that your deployment target must be able to run a headless Chrome. A small serverless function with a read-only filesystem will not work. The session, once authenticated, is stored locally and restored on later runs; the README points to the Authentication Strategies page for saving and restoring sessions, and does not describe rollback or session invalidation there.

The README's disclaimer is unusually direct for a project of this kind: it is not affiliated with WhatsApp, and "it is not guaranteed you will not be blocked by using this method." Treat that as a design constraint, not boilerplate.

Installing whatsapp-web.js and answering a message

The README requires Node.js v18.0.0 or higher. Install with your package manager of choice; the README lists npm, yarn and pnpm forms.

npm install whatsapp-web.js

The README's own example pairs the client with qrcode-terminal so the login QR code is printed to the console. That package is not a dependency of whatsapp-web.js, so install it separately if you follow the example.

npm install qrcode-terminal

The minimal client below is the README example: it creates a Client, renders the QR event, logs readiness, and replies pong when a message body equals !ping. After client.initialize(), the terminal should print a QR code you scan from the phone's Linked Devices screen. Once pairing completes, the ready handler runs and the process stays alive listening for messages.

const { Client } = require('whatsapp-web.js');
const qrcode = require('qrcode-terminal');

const client = new Client();

client.on('qr', (qr) => {
    qrcode.generate(qr, { small: true });
});

client.on('ready', () => {
    console.log('Client is ready!');
});

client.on('message', (msg) => {
    if (msg.body == '!ping') {
        msg.reply('pong');
    }
});

client.initialize();

The repository also ships example.js for more use cases and a shell script entry, npm run shell, which runs node with --experimental-repl-await against shell.js. That REPL is the fastest way to inspect the object model before committing to an application structure. The .env.example file shows the two variables the test suite expects, WWEBJS_TEST_REMOTE_ID and WWEBJS_TEST_CLIENT_ID, which is a hint that the tests need a live authenticated session rather than a mock.

The ban risk, the headless Chrome requirement, and the messages you cannot send

Three limitations matter more than any feature comparison.

First, account risk. The README's disclaimer states plainly that being blocked is not ruled out. Automating a consumer messaging account is outside the terms the official clients assume, and the library's own documentation does not offer a mitigation beyond running inside a managed browser instance. If a banned number would break your business, this is the wrong foundation.

Second, infrastructure. Puppeteer is a direct dependency at version 24.38.0, which means a Chromium download and a process that can fork a browser. Containers need the right shared libraries and enough memory; managed runtimes that forbid child processes cannot host it. Video sending is listed as requiring Google Chrome specifically, which is a narrower requirement than the default bundled browser.

Third, feature drift. Buttons and lists are marked deprecated in the README's table, and Communities is marked as planned rather than supported. Anyone building an interactive menu flow on this library is building on a feature the maintainers have already flagged as going away. The library tracks WhatsApp Web's internals, so when the web client changes, the library has to follow.

whatsapp-web.js vs Baileys and wppconnect: browser automation against a protocol implementation

The recurring comparison in search traffic is whatsapp-web.js against Baileys, and the difference is architectural rather than cosmetic. whatsapp-web.js drives a real browser session through Puppeteer. Baileys implements the WhatsApp Web protocol directly over a socket, without a browser. The practical split follows from that: the browser approach inherits the web client's behaviour and its media pipeline, and pays for it with a Chrome process, more memory, and a heavier container. A socket implementation skips the browser entirely, which is lighter to deploy but is a different codebase with a different maintenance surface and its own compatibility problems when the protocol moves.

wppconnect is the other name that comes up. It is also browser automation, so the trade-off against whatsapp-web.js is closer: both depend on a headless browser and both inherit the same class of account risk. Choosing between them comes down to API shape and how quickly each tracks WhatsApp Web changes, not to a difference in kind.

The honest framing: if you want the smallest possible runtime, a protocol implementation wins. If you want the web client's feature set with the least reimplementation, whatsapp-web.js is the direct route, and the README's feature table is the checklist to compare against.

Maintenance, licensing, and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-09-20. The most recent release listed is v1.34.7 from 2026-04-24, preceded by v1.34.6 in January 2026 and an alpha, v1.34.5-alpha.3, earlier that month. So releases are infrequent relative to commits, which is worth knowing before you pin a version: the code on main can be ahead of the published package.

The upgrade cost is dominated by the Puppeteer pin. package.json fixes puppeteer at 24.38.0 rather than a caret range, so bumping it is a deliberate change, and a Chrome version that breaks WhatsApp Web's internal selectors will surface as a runtime failure, not a compile error. There is no documented rollback procedure for a session that stops authenticating; the README points to the Authentication Strategies page for saving and restoring sessions and stops there.

The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. The README's disclaimer also notes that WhatsApp and related marks are trademarks of their owners, and that the project is not affiliated with or endorsed by WhatsApp. That is a naming and branding constraint to keep in mind if you ship a product that mentions WhatsApp in its own marketing; it is not legal advice, and the disclaimer text is the source to read.

Editorial conclusion

Adopt whatsapp-web.js when you need the web client's surface (groups, media, polls, channels) from Node.js and you accept the ban risk the README states plainly. Do not adopt it when you need guaranteed delivery, official support, or button and list messages, which the feature table marks deprecated. Before writing production code, verify the Node.js version against the package.json engines field, confirm the Puppeteer version resolves in your lockfile, and check whether your deployment host can run a headless Chrome at all.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. wwebjs/whatsapp-web.js on GitHub