The next generation of WhatsApp automation. Completely rebuilt.
Venom is not just another library. It's a complete automation platform designed from the ground up for performance, reliability, and developer experience.
Built on top of proven technologies, Venom gives you full control over WhatsApp Web through a clean, intuitive API β whether you're building a simple chatbot or a large-scale enterprise solution.
Blazing fast message processing
Session persistence out of the box
Modular architecture β extend with ease
Multi-session support for scaling
Battle-tested in production by thousands of developers
Rewritten from scratch β cleaner, simpler codebase
Pure Puppeteer β no puppeteer-extra, no stealth plugins
Updated WhatsApp Web modules (WAWebSocketModel, WAWebConnModel, etc.)
Chromium auto-download on npm install
Node.js 18+ required
TypeScript 5.7+ with strict types
Pino logger β fast, structured logging
Only 6 source files β down from 83+
Requires Node.js 18+. Chromium is downloaded automatically on install.
npm install venom-botπ§ͺ Nightly builds
npm install https://github.com/orkestral/venom/releases/download/nightly/venom-bot-nightly.tgzπ¦ Install from source
npm install github:orkestral/venomGet a fully functional bot running in under 30 seconds.
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\'m running on Venom.');
}
});
});Scan the QR code that appears in your terminal. Done β you're live.
Tip
Sessions are saved automatically. No need to re-scan on every restart.
Send anything. Text, images, videos, documents, audio, stickers, locations, polls β you name it.
// Text
await client.sendText(chatId, 'Hello from Venom π·οΈ');
// Image with caption
await client.sendImage(chatId, './photo.jpg', 'photo', 'Check this out!');
// Image from base64
await client.sendImageFromBase64(chatId, base64Image, 'image');
// Document
await client.sendFile(chatId, './report.pdf', 'report.pdf', 'Monthly report');
// Document from base64
await client.sendFileFromBase64(chatId, base64File, 'file.pdf', 'Description');
// Audio
await client.sendVoice(chatId, './message.mp3');
// Sticker
await client.sendImageAsSticker(chatId, './sticker.png');
// Animated sticker
await client.sendImageAsStickerGif(chatId, './animation.gif');
// Location
await client.sendLocation(chatId, '-23.5505', '-46.6333', 'SΓ£o Paulo, Brazil');
// Link with auto-preview
await client.sendLinkPreview(chatId, 'https://github.com/orkestral/venom', 'Venom Bot');
// Contact card
await client.sendContactVcard(chatId, 'contact@c.us', 'John Doe');
// Multiple contact cards
await client.sendContactVcardList(chatId, ['user1@c.us', 'user2@c.us']);
// Poll
await client.sendPollCreation(chatId, {
name: 'Best framework?',
options: [{ name: 'Venom' }, { name: 'Others' }],
selectableOptionsCount: 1
});
// List menu
await client.sendListMenu(chatId, 'Menu', 'Subtitle', 'Choose an option', 'Select', [
{
title: 'Category A',
rows: [{ title: 'Option 1', description: 'First option' }]
}
]);// Send with typing indicator
await client.sendTextViaTyping(chatId, 'This feels more natural...');
// Send photo/video with typing simulation
await client.sendPhotoVideoViaTyping(chatId, './sunset.jpg', 'Beautiful sunset');
// Reply to a message
await client.reply(chatId, 'Got it!', originalMessageId);
// Forward messages
await client.forwardMessages(chatId, [messageId1, messageId2]);
// Mention users
await client.sendMentioned(chatId, 'Hey @5511999999999!', ['5511999999999']);const chats = await client.getAllChats();
const contacts = await client.getAllContacts();
const unread = await client.getUnreadMessages();
const messages = await client.getAllMessagesInChat(chatId);
const profile = await client.getProfilePicFromServer(chatId);
const status = await client.checkNumberStatus(chatId);
const blocked = await client.getBlockList();// Create a group
await client.createGroup('Team Chat', ['user1@c.us', 'user2@c.us']);
// Manage participants
await client.addParticipant(groupId, 'user@c.us');
await client.removeParticipant(groupId, 'user@c.us');
// Admin controls
await client.promoteParticipant(groupId, 'user@c.us');
await client.demoteParticipant(groupId, 'user@c.us');
// Group info
await client.getGroupMembers(groupId);
await client.getGroupAdmins(groupId);
await client.getGroupInviteLink(groupId);
await client.setGroupDescription(groupId, 'Our awesome group');
// Join via invite
await client.joinGroup(inviteCode);
// Leave
await client.leaveGroup(groupId);await client.setProfileStatus('Building something amazing π');
await client.setProfileName('Venom Bot');
await client.setProfilePic('./avatar.jpg');
await client.getHostDevice();
await client.getConnectionState();
await client.getBatteryLevel();
await client.isConnected();
await client.getWAVersion();await client.sendSeen(chatId);
await client.startTyping(chatId);
await client.deleteChat(chatId);
await client.clearChatMessages(chatId);
await client.archiveChat(chatId, true);
await client.pinChat(chatId, true);
await client.blockContact(chatId);
await client.unblockContact(chatId);
await client.sendMute(chatId, 30, 'minutes');Build reactive bots with powerful event listeners.
// Incoming messages
client.onMessage((msg) => { /* handle message */ });
client.onAnyMessage((msg) => { /* all messages including groups */ });
// Message status tracking
client.onAck((ack) => {
// -7 MD_DOWNGRADE | -6 INACTIVE | -5 CONTENT_UNUPLOADABLE
// -4 CONTENT_TOO_BIG | -3 CONTENT_GONE | -2 EXPIRED | -1 FAILED
// 0 CLOCK | 1 SENT | 2 RECEIVED | 3 READ | 4 PLAYED
});
// Connection state
client.onStateChange((state) => {
// CONFLICT | CONNECTED | DEPRECATED_VERSION | OPENING | PAIRING
// PROXYBLOCK | TIMEOUT | TOS_BLOCK | UNLAUNCHED | UNPAIRED
});
// Live location
client.onLiveLocation(chatId, (location) => { /* track location */ });
// Group participants
client.onParticipantsChanged(groupId, (event) => { /* member joined/left */ });
// Added to group
client.onAddedToGroup((chat) => { /* handle new group */ });
// Incoming calls
client.onIncomingCall(async (call) => {
await client.sendText(call.peerJid, "I'm a bot, can't take calls π");
});Download any media received β images, videos, audio, documents. Fast.
import * as fs from 'fs';
import * as mime from 'mime-types';
client.onMessage(async (message) => {
if (message.isMedia || message.isMMS) {
const buffer = await client.decryptFile(message);
const fileName = `file.${mime.extension(message.mimetype)}`;
fs.writeFileSync(fileName, buffer);
}
});Full control over every aspect of the browser and session.
create({
session: 'production',
catchQR: (base64Qr, asciiQR, attempts, urlCode) => {
console.log(`Scan attempt ${attempts}`);
},
statusFind: (status, session) => {
console.log(`[${session}] Status: ${status}`);
},
options: {
// Browser
headless: 'new',
devtools: false,
browserWS: '',
browserPathExecutable: '',
puppeteerOptions: {},
browserArgs: [''],
addBrowserArgs: [''],
// Session
folderNameToken: 'tokens',
mkdirFolderToken: '',
createPathFileToken: false,
// Logging
debug: false,
logQR: true,
updatesLog: true,
disableSpins: false,
disableWelcome: false,
// Connection
autoClose: 60000,
addProxy: [''],
userProxy: '',
userPass: ''
},
browserInstance: (browser, waPage) => {
console.log('Browser PID:', browser.process().pid);
}
});π Session Status Reference
| Status | Description |
|---|---|
isLogged |
Already authenticated |
notLogged |
Awaiting QR scan |
browserClose |
Browser closed |
qrReadSuccess |
QR scanned successfully |
qrReadFail |
QR scan failed |
autocloseCalled |
Auto-close triggered |
desconnectedMobile |
Phone disconnected |
serverClose |
WebSocket closed |
chatsAvailable |
Chat list loaded |
deviceNotConnected |
Phone not connected |
successChat |
Chat ready |
waitForLogin |
Waiting for login |
waitChat |
Loading chats |
Keep your bot running and handle disconnections gracefully.
client.onStateChange((state) => {
if (state === 'CONFLICT') client.useHere(); // reclaim session
if (state === 'UNPAIRED') console.log('Session expired');
});
// Graceful shutdown
process.on('SIGINT', () => client.close());Note
Always call client.close() instead of killing the process β this ensures the session is saved properly.
create({
session: 'custom-version',
webVersion: '2.2402.5' // pinned version
});Available versions: wppconnect-team/wa-version
# Clone
git clone https://github.com/orkestral/venom.git && cd venom
# Install dependencies
npm install
# Build individual modules
npm run build:wapi
npm run build:middleware
npm run build:jsQR
npm run build:venom
# Or build everything at once
npm run buildThe complete documentation is available at orkestral.github.io/venom.
Every method, every parameter, every edge case β fully documented.
We love contributions. Open an issue, submit a PR, or help improve the docs.
For major changes, please open an issue first to discuss the approach.
Orkestral β by vynect
Silicon Valley, California