Venom v6

The next generation of WhatsApp automation. Completely rebuilt.

Why Venom?

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

What's new in v6

  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+

Install

Requires Node.js 18+. Chromium is downloaded automatically on install.

npm install venom-bot

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

npm install github:orkestral/venom

Quick Start

Get 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.

Capabilities

Messaging

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' }]
  }
]);

Smart Sending

// 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']);

Data Retrieval

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();

Group Management

// 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);

Profile & Device

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();

Chat Operations

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');

Events

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 📞");
});

File Downloads

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);
  }
});

Advanced Configuration

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 Resilience

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.

Custom WhatsApp Web Version

create({
  session: 'custom-version',
  webVersion: '2.2402.5'  // pinned version
});

Available versions: wppconnect-team/wa-version

Building from Source

# 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 build

Documentation

The complete documentation is available at orkestral.github.io/venom.

Every method, every parameter, every edge case — fully documented.

Contributing

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}