whatsapp-web.js

whatsapp-web.js supports a wide range of features including:

• Messaging: Send/receive text, media (images, audio, documents), stickers, contact cards, and locations. Note that sending video requires Google Chrome.
• Group Management: Join by invite, get invite links, modify group info/settings, add/kick/promote/demote participants, and mention users/groups.
• Interactions: Message replies, reacting to messages, creating and voting in polls, and setting user status.
• Contacts: Get contact info and profile pictures, block/unblock contacts, and mute/unmute chats.
• New Features: Support for Channels and Communities (Communities is currently in development).

Note: Sending buttons and lists are currently marked as DEPRECATED.

To get started, import the Client class from whatsapp-web.js. You will typically use a library like qrcode-terminal to display the QR code in your terminal for authentication. The lifecycle involves listening for the qr event to authenticate, the ready event to confirm connection, and the message event to handle incoming communications. Finally, call client.initialize() to start the process.

const { Client } = require('whatsapp-web.js');
const qrcode = require('qrcode-terminal');

const client = new Client();

client.on('qr', (qr) => {
    qrcode.generate(qr, { small: true });
});

client.on('ready', () => {
    console.log('Client is ready!');
});

client.on('message', (msg) => {
    if (msg.body == '!ping') {
        msg.reply('pong');
    }
});

client.initialize();

Install the library using your preferred package manager. Note that Node.js v18.0.0 or higher is required.

npm install whatsapp-web.js
yarn add whatsapp-web.js
pnpm add whatsapp-web.js

The Client class extends EventEmitter and emits several events during its lifecycle. Common events include:

• ready: Emitted when the client has initialized and is ready to receive messages.
• qr: Emitted when a QR code is received.
• authenticated: Emitted when authentication is successful.
• auth_failure: Emitted when there is an error restoring a session.
• message: Emitted when a new message is received.
• message_create: Emitted when a new message is created (including sent messages).
• message_ack: Emitted when a message acknowledgment occurs.
• disconnected: Emitted when the client is disconnected (reason can be a state or 'LOGOUT').
• group_join: Emitted when a user joins a group.
• group_leave: Emitted when a user leaves or is removed from a group.
• contact_changed: Emitted when a contact changes their phone number.

The Channel class represents a WhatsApp Channel. It provides methods to manage channel metadata (name, description, profile picture), handle administrative tasks (inviting admins, transferring ownership, demoting admins), and interact with content (sending messages, fetching message history, and managing reactions).

// Example of interacting with a Channel instance
const channel = await client.getChannel(channelId);

// Update channel info
await channel.setSubject('New Channel Name');
await channel.setDescription('New description here');

// Send a message
await channel.sendMessage('Hello Channel!');

// Fetch message history
const messages = await channel.fetchMessages({ limit: 50, fromMe: true });

Use sendReaction(messageId, reaction) to add an emoji reaction to a specific message. To remove a reaction, pass an empty string as the reaction argument.

await client.sendReaction('MESSAGE_ID', '❤️');
// To remove
await client.sendReaction('MESSAGE_ID', '');

Control your account's profile picture:

• setProfilePicture(media): Sets your profile picture using a MessageMedia object. Returns true if successful.
• deleteProfilePicture(): Deletes your current profile picture. Returns true if successful.

// Set profile picture
const media = new MessageMedia('image/jpeg', 'base64_string...', 'filename.jpg');
await client.setProfilePicture(media);

// Delete profile picture
await client.deleteProfilePicture();

For WhatsApp Business accounts, you can manage unstructured notes for customers:

• addOrEditCustomerNote(userId, note): Adds or updates a note for a specific user.
• getCustomerNote(userId): Retrieves the note for a user. Returns an object containing chatId, content, createdAt, id, modifiedAt, and type.

// Add a note
await client.addOrEditCustomerNote('USER_ID', 'This is a customer note');

// Get a note
const note = await client.getCustomerNote('USER_ID');
console.log(note.content);

You can manage labels (primarily for WhatsApp Business) using the following methods:

• getLabels(): Retrieves all current labels as an array of Label instances.
• getLabelById(labelId): Retrieves a specific Label instance by its ID.
• getChatLabels(chatId): Retrieves all labels assigned to a specific chat.
• getChatsByLabelId(labelId): Retrieves all Chat instances associated with a specific label.
• addOrRemoveLabels(labelIds, chatIds): Adds or removes specified labels from a list of chats. Note: This method only works on WhatsApp Business platforms (smba or smbi).

// Get all labels
const labels = await client.getLabels();

// Get chats for a specific label
const chats = await client.getChatsByLabelId('LABEL_ID');

// Add/Remove labels for specific chats (Business only)
await client.addOrRemoveLabels(['label_id_1'], ['chat_id_1', 'chat_id_2']);