TypeScript · ESM · MIT

The WhatsApp Web SDK with no browser

No Puppeteer, no headless Chromium. whatsweb speaks the native Multi-Device protocol directly over a WebSocket, wrapped in a fully-typed, bot-friendly API.

Read the docs $ npm install @whatsweb/core

Features

Batteries included

Everything you need to build WhatsApp bots and integrations.

No browser

A fraction of the RAM and startup time of Puppeteer-based clients.

Command router

command, hears, middleware and a rich Context.

Two styles

Event callbacks or a linear for await async iterator.

Media anywhere

Path, http(s)/S3 URL, Buffer or stream, with auto type detection.

Rich messages

Polls, mentions, stickers, contacts, edit / delete / forward.

Groups

Metadata, participants, invite links, create / join / leave.

Presence & profile

Presence, profile pictures, status and block list.

Multiple accounts

Run many numbers in one process, each with its own session.

Per-user conversations

State, history and ask, plus a neutral toMessages() to plug in your own LLM or agent.

Resilient

Auto-reconnect with backoff and optional send rate-limiting.

Install

Add it to your project

Works with npm, pnpm and Bun. Requires Node ≥ 20 (or Bun) and ESM.

$ npm install @whatsweb/core

Add "type": "module" to your package.json. Baileys 7 (and this SDK) are ESM-only. Bun can also run the TypeScript examples directly, no build step.

Examples

Real snippets

For the things you'll actually build. Hover a block to copy it.

Setup & sessions

Multiple accounts

Run several numbers in one process: one client per account, each with its own session folder.

Persistent sessions

Credentials live on disk, so you only scan once. Point them wherever you like.

Pairing by code (no QR)

Link an account with an 8-character code instead of scanning a QR.

Render the QR yourself

Turn off the terminal output and do what you want with the raw value: a PNG, a web page, a Slack message.

Reconnection & rate limiting

Stay online with backoff, and space out sends to reduce ban risk.

Logging & device name

Silent by default. Pass a pino-compatible logger when you need to see the wire.

Graceful shutdown

Close the socket without losing the session, or unlink the device for good.

Sending

Send media

Images, voice notes, documents and locations. Sources can be a path, URL or Buffer.

Send from a link (S3, CDNs)

Point at any URL and the media kind (image/video/audio/document) is detected for you.

Rich messages

Mentions, polls, stickers and contact cards.

Reply helpers

Every send has a reply counterpart on the context, already addressed to the sender.

Edit, delete, forward

Manage messages after sending them.

Download media

Save incoming attachments to disk.

Fluent chat handle

Set the recipient once and keep calling methods on it, no JIDs to repeat.

Routing & flow

Async / await style

Prefer a linear flow? Iterate incoming messages instead of registering callbacks.

Prefixes, aliases & captures

Choose your own command prefixes, give a handler several names, and read RegExp captures off the context.

Middleware & groups filter

Compose behavior; in groups, only react to commands.

Typing & read receipts

Mark as seen, hold the typing indicator while you work, or let the SDK time it.

Wait for the next reply

Pause a handler until the same person answers, or wait anywhere for a message that matches.

Events

Every event is strongly typed.

Conversations & state

Per-user state

Remember context per user, persisted through a pluggable store (in-memory by default, or Redis/DB).

Wizard (ask & save)

Prompt the user, await their replies, and store the answers: a full signup flow.

Confirm a value

Ask yes/no and get a boolean. Accepted answers are configurable (defaults cover en/es plus 👍/👎).

Conversation history

Recent messages are kept per chat, with a configurable window you can clear at any time.

Custom state store

Implement three methods to back conversation state with Redis, Postgres or anything else.

Bring your own agent (LLM)

whatsweb is unopinionated about LLMs. It hands you the transcript, you drive the model (here, the Vercel AI SDK).

Groups & contacts

Groups

A fluent handle for every group operation.

Presence & profile

Set your presence and profile, read other people's, manage the block list.

Check a number first

Find out whether a number is on WhatsApp before sending, and resolve its LID.

Run locally

Try the examples

Clone the repo and run any example with your package manager of choice.

$ npm install && npm run example:multi

Other examples: example:bot, example:async, example:pair, example:send. Bun runs the examples/*.ts files directly, no tsx needed.

Explore the full API

Every class, method, event and option, auto-generated from the source.

Open the documentation