Venom (venom-bot) v6: a Puppeteer-based WhatsApp automation framework for Node.js

What venom-bot actually solves, and for whom

The problem venom-bot addresses is access. WhatsApp has no public, unauthenticated HTTP endpoint for sending a message to an arbitrary number from a script. The official route is the WhatsApp Business API, which is a commercial product with onboarding. Venom takes the other route: it automates WhatsApp Web, the browser client, and wraps the result in a Node.js API.

The README frames the target audience broadly, listing customer service, media sending and sentence recognition among the supported interactions. In practice the fit is narrower. This is a library for developers who already run Node.js services and want the WhatsApp client to be a dependency rather than a separate platform. If your team can write a TypeScript service but does not want to negotiate a Business API contract, venom-bot is the shape of tool you are looking for. If your requirement is a guaranteed delivery SLA with a vendor behind it, it is not.

The repository name in the facts is vynect/venom, while the package, homepage and README all point at orkestral/venom and the npm package venom-bot. Treat orkestral/venom and venom-bot as the canonical references when you go looking for issues or documentation.

How Venom drives WhatsApp Web: Puppeteer, CDP and a WebSocket model

The mechanism is browser automation. package.json lists puppeteer ^24.0.0, qrcode-terminal, ws, mime-types and pino as runtime dependencies. The README states that v6 is "Pure Puppeteer, no puppeteer-extra, no stealth plugins" and that it uses updated WhatsApp Web modules named WAWebSocketModel and WAWebConnModel. So the data flow is: Venom launches Chromium, loads WhatsApp Web, and talks to the page's internal modules rather than to a public API.

Authentication is a QR code rendered in your terminal by qrcode-terminal. Once you scan it, the session is persisted, and the README says sessions are saved automatically so you do not re-scan on every restart. That session directory is the single most operationally important artifact the library produces.

The v6 rewrite is the part worth understanding before you upgrade. The README claims the codebase went from 83+ source files to 6, that TypeScript 5.7+ with strict types is required, and that pino replaced whatever logging existed before. It also states Chromium is downloaded automatically on install through a postinstall script, scripts/download-chromium.js, which is visible in package.json. That postinstall step is where installs fail in restricted networks.

Installing venom-bot and sending your first message

The README requires Node.js 18+ and states Chromium is downloaded automatically during install. The engines field in package.json confirms node >=18.0.0. Install the published package:

npm install venom-bot

The install runs scripts/download-chromium.js as a postinstall hook, so expect a Chromium download on first install. If your environment blocks outbound downloads, that hook is the thing to work around. The README also documents two alternatives: a nightly tarball and installing straight from GitHub.

npm install https://github.com/orkestral/venom/releases/download/nightly/venom-bot-nightly.tgz

npm install github:orkestral/venom

The quick start in the README is a single create call plus an onMessage handler. The session option names the folder where the login state is kept.

import { create } from 'venom-bot';

create({ session: 'venom-bot' }).then((client) => {
  client.onMessage(async (message) => {
    if (message.body === 'hello') {
      await client.sendText(message.from, 'Hey there! I am running on Venom.');
    }
  });
});

Run that file with Node, and the README says a QR code appears in your terminal. Scan it with the phone that owns the WhatsApp account. After that, sending the word hello to the connected account from another phone should produce a reply. The README notes the session is saved, so a restart should not require a new scan.

The API surface: media, polls, groups and profile calls

The breadth of the client object is the strongest argument for Venom over hand-rolling Puppeteer scripts. The README documents sendText, sendImage, sendImageFromBase64, sendFile, sendFileFromBase64, sendVoice, sendImageAsSticker, sendImageAsStickerGif, sendLocation, sendLinkPreview, sendContactVcard, sendContactVcardList, sendPollCreation and sendListMenu. Each is a one-line call, which means the protocol details stay inside the library.

There is a second tier aimed at making the bot look human. sendTextViaTyping and sendPhotoVideoViaTyping send a typing indicator before the payload. reply takes an original message id, forwardMessages takes an array of ids, and sendMentioned takes a list of numbers to tag. These exist because WhatsApp Web reacts differently to a message that arrives with no preceding presence signal, and the library exposes the presence controls rather than hiding them.

Read-side calls are grouped as data retrieval: getAllChats, getAllContacts, getUnreadMessages, getAllMessagesInChat, getProfilePicFromServer, checkNumberStatus and getBlockList. Group management covers createGroup, addParticipant, removeParticipant, promoteParticipant, demoteParticipant, getGroupMembers, getGroupAdmins, getGroupInviteLink, setGroupDescription, joinGroup and leaveGroup. Profile and device calls include setProfileStatus, setProfileName, setProfilePic, getHostDevice, getConnectionState, getBatteryLevel, isConnected and getWAVersion.

Two of those deserve attention. getWAVersion tells you which WhatsApp Web build you are driving, which is the first thing to check when a call starts failing after a client update. getBatteryLevel and getHostDevice expose the linked device state, useful for detecting a session that has been unlinked from the phone.

Where venom-bot breaks, and who should not use it

The central limitation is structural, not a bug. Venom automates a browser client that WhatsApp controls and updates on its own schedule. The README names the internal modules it depends on, WAWebSocketModel and WAWebConnModel, and any rename or refactor on WhatsApp's side can break those calls. There is no compatibility guarantee in the README, and the release history shows the cost: v5.1.0 in April 2024, v5.2.0 in September 2024, v5.3.0 in November 2024, with package.json now at 6.0.0. The last push to the repository was on 2026-09-09, so the project is being worked on, but the published release tags lag well behind that.

A second limitation is the install itself. Chromium is fetched by a postinstall script. In a container with no egress, or in a CI runner with a small disk, that step fails or bloats the image. You will need to pre-provision a browser and skip the download.

A third is session handling. The README says sessions are saved automatically, but it does not document rollback, session migration between v5 and v6, or what happens to an existing session folder after the rewrite. If you are upgrading from v5, that is unverified ground.

Finally, consider the use case. If you need a bot that responds to a handful of commands inside a group you control, this is a reasonable tool. If you are building a notification channel for customers who did not opt in, you are using a browser automation library to route around a product decision, and the account risk sits with you, not with the library.

Alternatives: the official Business API and raw Puppeteer

The obvious alternative is the official WhatsApp Business API. The difference is not speed or features, it is the contract. The Business API is a supported product with message templates, delivery status webhooks and a vendor you can escalate to. Venom has none of that: it drives WhatsApp Web, and the README documents no delivery receipts, no template approval flow and no rate-limit contract. If your requirement is transactional messaging at volume with an audit trail, the Business API is the correct choice and Venom is the wrong one.

The other alternative is writing the Puppeteer automation yourself. That is essentially what v6 is, minus the API layer. The README's own framing supports this: it advertises "Pure Puppeteer, no puppeteer-extra, no stealth plugins" and a small file count. If you only need sendText and onMessage, a few hundred lines of your own Puppeteer code gives you the same result with no dependency to track. What you would lose is the media, poll, sticker, group and profile calls, which are tedious to reimplement and are the real reason to take the dependency.

Licence, maintenance and the cost of upgrading

There is a discrepancy you should resolve before shipping. The README displays an Apache-2.0 licence badge and the repository facts list Apache-2.0, but package.json contains "license": "MIT". Both are permissive, and both allow commercial use, but they differ on patent grant language and on attribution requirements. Check the LICENSE file in the tarball you actually install. This is a factual inconsistency in the project, not a legal opinion.

The upgrade cost is the other thing to budget. The README describes v6 as rewritten from scratch with a different dependency set, a different logger and a different internal module layer. The release notes list v5.3.0 as the last 5.x tag, from November 2024, while package.json already reads 6.0.0. That gap means anyone on v5 is moving across a rewrite rather than a patch. The README does not document a migration path, a compatibility shim, or what happens to a v5 session directory under v6. Plan for a re-scan at minimum, and test your group and media calls specifically, because those touch the WhatsApp Web modules that changed.

Editorial conclusion

Adopt venom-bot if you are comfortable with a Puppeteer-driven WhatsApp Web session and want one API for text, media, polls and group administration. Do not adopt it if you need an official, contract-backed WhatsApp Business API, or if you cannot run a headless Chromium next to your service. Before committing, verify three things: that the session folder survives your deployment model, that the WhatsApp Web module names referenced in the README still match the version you get from npm, and which licence the published tarball actually carries, because the README badge says Apache-2.0 while package.json says MIT.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. vynect/venom on GitHub