WhatsApp Baileys

WhatsApp Baileys is a highly modular, open-source Node.js library for building automation, bots, and integrations with WhatsApp using direct WebSocket connections, bypassing the need for a browser. It enables developers to manage messaging, groups, media, and advanced interactive features while maintaining robust stability and security.

The library emphasizes:
- Reliable pairing & authentication
- Automatic session management
- Interactive messaging & dynamic menus
- Full support for WhatsApp multi-device architecture

---

Table of Contents

1. Architecture Overview
2. Installation
3. Authentication & Pairing
4. Session Management
5. Message Handling
6. Interactive Messages
7. Media Handling
8. Group Management
9. Event System
10. Advanced Features
11. Best Practices
12. Troubleshooting
13. Resources

---

Architecture Overview

Baileys is built with a WebSocket-based event-driven architecture, separating:

1. Connection Layer – Handles WebSocket communication with WhatsApp servers
2. Authentication Layer – Manages session credentials, pairing codes, and QR code login
3. Message Layer – Parses incoming messages, reactions, and status updates
4. Interactive Layer – Supports buttons, lists, and other rich message types
5. Persistence Layer – Stores session state and media metadata for reliable reconnections

The modular design allows developers to extend functionality, integrate with databases, or build custom automation pipelines.

---

Usage / Detailed Examples

WhatsApp Baileys allows developers to quickly setup, authenticate, send messages, manage groups, and handle interactive content in a stable and modular environment. The following example demonstrates a full workflow, including custom pairing code usage.

``javascript
const { default: makeWASocket, useSingleFileAuthState, makeInMemoryStore } = require("qudbail");
const { Boom } = require("@hapi/boom");

// Authentication state
const { state, saveState } = useSingleFileAuthState("./auth_info.json");

// Initialize WhatsApp connection
const sock = makeWASocket({
auth: state,
printQRInTerminal: true, // shows QR code in terminal if no valid session
connectTimeoutMs: 30_000,
});

// Monitor connection updates
sock.ev.on('connection.update', (update) => {
console.log('Connection update:', update);

if (update.connection === 'close') {
const shouldReconnect = (update.lastDisconnect?.error instanceof Boom) &&
update.lastDisconnect.error.output.statusCode !== 401;
if (shouldReconnect) {
console.log('Reconnecting...');
} else {
console.log('Authentication failed, please re-scan QR code or use custom pairing code.');
}
}

if (update.connection === 'open') {
console.log('Connected successfully!');
}
});

// Save auth state on exit
process.on('exit', () => saveState());

// ---------------------------
// Custom Pairing / Authentication
// ---------------------------

// If you want a custom pairing code instead of default QR
sock.ev.on('creds.update', saveState);

// Example: listen for QR code updates (ASCII string)
sock.ev.on('connection.update', ({ qr }) => {
if (qr) {
console.log('Scan this QR with WhatsApp:', qr);
}
});

// ---------------------------
// Message Handling
// ---------------------------

// Listen for all incoming messages
sock.ev.on('messages.upsert', async (m) => {
const msg = m.messages[0];
console.log('Received message:', msg.message);
});

// Sending text message
await sock.sendMessage('123456789@s.whatsapp.net', { text: 'Hello! This is a test message.' });

// Sending media
await sock.sendMessage('123456789@s.whatsapp.net', { image: { url: './image.png' }, caption: 'Sample Image' });
await sock.sendMessage('123456789@s.whatsapp.net', { video: { url: './video.mp4' }, caption: 'Sample Video' });
await sock.sendMessage('123456789@s.whatsapp.net', { audio: { url: './audio.mp3' }, mimetype: 'audio/mp3' });
await sock.sendMessage('123456789@s.whatsapp.net', { document: { url: './document.pdf' }, mimetype: 'application/pdf', fileName: 'example.pdf' });
await sock.sendMessage('123456789@s.whatsapp.net', { sticker: { url: './sticker.webp' } });

// ---------------------------
// Interactive Messages
// ---------------------------

// Buttons
await sock.sendMessage('123456789@s.whatsapp.net', {
text: "Choose an option",
buttons: [
{ buttonId: 'opt1', buttonText: { displayText: 'Option 1' }, type: 1 },
{ buttonId: 'opt2', buttonText: { displayText: 'Option 2' }, type: 1 }
],
headerType: 1
});

// List message
await sock.sendMessage('123456789@s.whatsapp.net', {
text: 'Select from the list below',
footer: 'Footer text',
sections: [
{
title: 'Menu Section',
rows: [
{ title: 'Item 1', rowId: 'item1' },
{ title: 'Item 2', rowId: 'item2' }
]
}
],
buttonText: 'Open List'
});

// ---------------------------
// Group Management
// ---------------------------

await sock.groupParticipantsUpdate('group-id@g.us', ['user@s.whatsapp.net'], 'promote');
await sock.groupParticipantsUpdate('group-id@g.us', ['user@s.whatsapp.net'], 'demote');
await sock.groupParticipantsUpdate('group-id@g.us', ['user@s.whatsapp.net'], 'remove');
await sock.groupUpdateSubject('group-id@g.us', 'New Group Name');
await sock.groupUpdateDescription('group-id@g.us', 'Updated group description');

// ---------------------------
// Advanced Automation
// ---------------------------

// Relay incoming messages to another chat
sock.ev.on('messages.upsert', async (m) => {
const msg = m.messages[0];
if (!msg.key.fromMe) {
await sock.sendMessage('target-chat@s.whatsapp.net', { text: msg.message.conversation });
}
});

// Auto-reply system
sock.ev.on('messages.upsert', async (m) => {
const msg = m.messages[0];
if (msg.message && !msg.key.fromMe) {
await sock.sendMessage(msg.key.remoteJid, { text: 'Thanks for your message!' });
}
});

// ---------------------------
// Connection Handling
// ---------------------------

sock.ev.on('connection.update', (update) => {
if(update.connection === 'close') {
const shouldReconnect = (update.lastDisconnect?.error)?.output?.statusCode !== 401;
if(shouldReconnect) {
console.log('Reconnecting...');
// implement reconnection logic
} else {
console.log('Authentication failed, please re-scan QR code or provide a new pairing code.');
}
}
});
`End Usage

---

Installation

``bash
npm install qudbail

or

yarn add qudbail