whatsapp-web-js

name	whatsapp-web-js
description	Expert guidance for whatsapp-web.js, a Puppeteer-based library providing high-level API to interact with WhatsApp Web. Use when building WhatsApp bots, automating WhatsApp messaging, integrating WhatsApp into applications, or working with WhatsApp Web automation, message handling, media sending, group management, or channel operations.

WhatsApp Web.js

Provides expert guidance for whatsapp-web.js, a library that automates WhatsApp Web by controlling a Chromium browser instance via Puppeteer.

Quick Start

Initialize client with authentication strategy and listen for events:

const { Client, LocalAuth } = require('whatsapp-web.js');

const client = new Client({
    authStrategy: new LocalAuth(),
    puppeteer: { headless: true }
});

client.on('qr', (qr) => console.log('Scan QR:', qr));
client.on('ready', () => console.log('Client ready'));
client.on('message', async (msg) => {
    if (msg.body === 'ping') await msg.reply('pong');
});

client.initialize();  // Non-blocking - listen for 'ready' event

Requirements: Node.js >= 18.0.0, puppeteer (required), ffmpeg (optional for stickers).

ID Format Conventions

Always use correct ID format for chat operations:

• Private chats: <country_code><phone>@c.us (e.g., [e-mail])
• Groups: <id>@g.us (e.g., [e-mail])
• Channels: <id>@newsletter
• Status broadcasts: status@broadcast

Phone numbers exclude + and leading zeros. Example: US [phone] becomes [e-mail].

Authentication Strategies

Choose based on deployment model:

// No persistence - QR scan every restart
new NoAuth()

// Local filesystem - recommended for single-instance bots
new LocalAuth({ clientId: 'bot1' })

// Remote store - for cloud/multi-instance deployments
new RemoteAuth({ store: myStore, clientId: 'bot1', backupSyncIntervalMs: 60000 })

Pairing Code Authentication

Skip QR scanning by using phone number pairing:

const client = new Client({
    authStrategy: new LocalAuth(),
    pairWithPhoneNumber: {
        phoneNumber: '5511999999999',  // country code + number, no symbols
        showNotification: true,
        intervalMs: 180000
    }
});
client.on('code', (code) => console.log('Pairing code:', code));

Essential Patterns

Sending Messages

// Text message
await client.sendMessage('[e-mail]', 'Hello!');

// Reply to received message
await msg.reply('Got it!');

// With mentions
await client.sendMessage(chatId, 'Hi @5511999999999', {
    mentions: ['[e-mail]']
});

// Quote specific message
await client.sendMessage(chatId, 'Replying to this', {
    quotedMessageId: msg.id._serialized
});

Media Handling

const { MessageMedia } = require('whatsapp-web.js');

// From file
const media = MessageMedia.fromFilePath('/path/to/image.png');
await client.sendMessage(chatId, media, { caption: 'Check this out' });

// From URL
const media = await MessageMedia.fromUrl('https://example.com/image.png');
await client.sendMessage(chatId, media);

// Download received media
if (msg.hasMedia) {
    const media = await msg.downloadMedia();
    // Access: media.mimetype, media.data (base64), media.filename
}

Media Send Variants

Control how media is sent with specific options:

// As sticker (requires ffmpeg)
await client.sendMessage(chatId, media, { sendMediaAsSticker: true });

// As voice note
await client.sendMessage(chatId, audio, { sendAudioAsVoice: true });

// As HD quality
await client.sendMessage(chatId, media, { sendMediaAsHd: true });

// As view-once
await client.sendMessage(chatId, media, { isViewOnce: true });

// As document
await client.sendMessage(chatId, media, { sendMediaAsDocument: true });

Polls, Reactions, Location

const { Poll, Location } = require('whatsapp-web.js');

// Poll (single choice)
await client.sendMessage(chatId, new Poll('Question?', ['A', 'B']));

// Poll (multiple choice)
await client.sendMessage(chatId, new Poll('Pick', ['A', 'B', 'C'], 
    { allowMultipleAnswers: true }));

// React to message
await msg.react('👍');   // add reaction
await msg.react('');      // remove reaction

// Send location
await client.sendMessage(chatId, 
    new Location(37.422, -122.084, { name: 'Googleplex' }));

Message Operations

// Edit sent message
const sent = await client.sendMessage(chatId, 'Original');
await sent.edit('Edited text');

// Delete message
await sent.delete(true);  // true = delete for everyone

// Pin message
await msg.pin(86400);     // Pin for 24h (86400|604800|2592000 seconds)
await msg.unpin();

Critical Gotchas

• client.initialize() is non-blocking — Always listen for ready event before using client
• message event fires only for incoming — Use message_create to capture outgoing messages too
• Message IDs require ._serialized — Use msg.id._serialized for string representation
• Group admin operations — Bot must be admin to setSubject, removeParticipants, etc.
• Rate limiting — Add delays between bulk sends to avoid temporary blocks
• fetchMessages() loads from cache — Call chat.syncHistory() for full history sync
• Sticker conversion requires ffmpeg — Install on system PATH for sticker support
• Memory considerations — Runs real Chromium instance; plan for multi-client setups
• Status messages — Send to status@broadcast as chatId

Key Events

Essential events for bot logic:

Event	Use Case
ready	Client ready to use
message	Incoming message only
message_create	All messages (including own)
message_ack	Track delivery status (0=pending, 1=server, 2=device, 3=read, 4=played)
qr	QR code for authentication
authenticated	Auth successful
disconnected	Handle reconnection logic

References

Consult these detailed references when implementing specific features:

• detailed-guide.md — Read when implementing any WhatsApp Web.js feature. Contains comprehensive API reference organized by category: messaging, media, chats, groups, channels, contacts, events. Includes all method signatures, options, return types, and code examples. Start here for unfamiliar operations or when debugging unexpected behavior.