Skip to content

vynect/venom

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

2,306 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Venom

Venom v6

The next generation of WhatsApp automation. Completely rebuilt.

npm node downloads build license


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
πŸ§ͺ Nightly builds
npm install https://github.com/orkestral/venom/releases/download/nightly/venom-bot-nightly.tgz
πŸ“¦ Install from source
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 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

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

About

Venom is a high-performance system developed with JavaScript to create a bot for WhatsApp, support for creating any interaction, such as customer service, media sending, sentence recognition based on artificial intelligence and all types of design architecture for WhatsApp.

Topics

Resources

License

Contributing

Security policy

Stars

Watchers

Forks

Packages

 
 
 

Contributors