toxic-baileys™ ⭐

A professionally enhanced, feature-rich fork of the Baileys WhatsApp Web API. Built for developers who need robust, stable WhatsApp automation with LID identity mapping, AI group support, interoperability, extended message types, and improved connection handling.

Maintainer: 𝐱𝐡_𝐜𝐥𝐢𝐧𝐭𝐨𝐧 ✓

Important

🆔 LID Mapping — Critical Feature in This Fork

WhatsApp has rolled out Linked Identity (LID) JIDs as part of its cross-platform interoperability initiative. Group messages and status updates now arrive with @lid domain JIDs instead of standard @s.whatsapp.net phone-number JIDs. Without LID resolution, you cannot identify who sent a message in many groups.

This fork ships a complete LIDMappingStore (bidirectional LRU cache + persistent key store) and UsyncLIDProtocol so your bot always knows the real phone number behind every @lid JID. See the 🆔 LID Mapping System section for full integration details.

📋 Table of Contents

🆕 What's New
✨ Features
📦 Installation
🚀 Quick Start
🔌 Connection & Configuration
💾 Authentication State Management
🆔 LID Mapping System
🤖 AI Groups
🔗 Interoperability API
🔄 USync Protocol
📤 Sending Messages
- Basic Messages
- Media Messages
- Interactive Messages
- Album Messages
- Event Messages
- Poll & Poll Result Messages
- Group Status Messages
- Payment Request Messages
- Product Messages
- Button & Template Messages
📁 Chat & Message Management
👥 Group Management
👤 User & Profile Management
📡 Newsletter / Channel Management
🔒 Privacy & Block Management
🗄️ Data Store Implementation
🛠️ Utility Functions
💡 Best Practices & Tips
⚠️ Important Legal Notice
🆘 Getting Help
📄 License

🆕 What's New

Compared to upstream Baileys, this fork adds:

Feature	Description
🆔 LID Mapping System	Full `LIDMappingStore` with LRU cache, persistent key store, bidirectional lookups, and `UsyncLIDProtocol`
🤖 AI Groups	`makeAIGroupsSocket` — create, manage, and receive events for WhatsApp AI-powered groups
🔗 Interoperability API	`makeInteropSocket` — fetch third-party integrators, accept Interop TOS, opt in/out
📡 USync Protocol Layer	Full `WAUSync` module: LID, Contact, Device, Disappearing Mode, Status, Username, Bot Profile protocols
🔎 MEX / GraphQL Queries	`executeWMexQuery` for structured WhatsApp server queries via the `w:mex` IQ namespace
🗝️ `me.lid` Credential	Bot's own LID identity stored in credentials on pairing via `configureSuccessfulPairing`
📌 `lidDbMigrated` Login Flag	Signals to WhatsApp to push down LID mappings on connect
📺 Group Status V2	`ToxicHandler` exposed on socket for rich group story/status management
🔧 `SignalRepositoryWithLIDStore`	Extended signal repository type that exposes `lidMapping` directly on the socket
📣 `newsletterId()` Helper	Utility to extract a clean newsletter/channel ID from any JID format

✨ Features

🚀 Modern & Fast — Latest WA version [2,3000,1035194821], optimised pre-key upload (812 keys)
🆔 Full LID Identity Resolution — Bidirectional LID↔PN mapping with LRU cache, USync lookup, and persistent storage
🤖 AI Groups Support — Create and manage WhatsApp's AI-powered group type
🔗 Cross-Platform Interop — Third-party integrator management (BirdyChat, Haiket, and more)
🔧 Enhanced Stability — Improved connection handling, rate-limit backoff, 5 s keepAlive grace
📱 Multi-Device Support — Full WhatsApp multi-device protocol with improved historySyncConfig
🔐 End-to-End Encryption — Signal Protocol, inlineInitialPayloadInE2EeMsg: true
📨 Extended Message Types — Interactive, album, event, poll result, group status, payment, product
👥 Advanced Group Management — Group controls, group status V2, communities support
💾 Flexible Auth — Multi-file auth state with makeCacheableSignalKeyStore
📡 Full Newsletter/Channel API — Follow, create, metadata, newsletterId() helper
🛠️ Developer Friendly — toxicHandler and ToxicHandler exposed on socket, clean API
🌐 WebSocket Improvements — perMessageDeflate: false, 100 MB max payload

📦 Installation

Via npm

npm install toxic-baileys

Via Yarn

yarn add toxic-baileys

From GitHub (edge)

npm install github:xhclintohn/Baileys

Drop-in replacement for `@whiskeysockets/baileys`

{
  "dependencies": {
    "@whiskeysockets/baileys": "npm:toxic-baileys@latest"
  }
}

🚀 Quick Start

Basic Connection (QR Code)

import makeWASocket, { useMultiFileAuthState, DisconnectReason } from 'toxic-baileys';
import { Boom } from '@hapi/boom';

async function connectToWhatsApp() {
    const { state, saveCreds } = await useMultiFileAuthState('auth_info_baileys');
    const sock = makeWASocket({ auth: state, printQRInTerminal: true });

    sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
        if (connection === 'close') {
            const shouldReconnect = lastDisconnect?.error?.output?.statusCode !== DisconnectReason.loggedOut;
            if (shouldReconnect) connectToWhatsApp();
        } else if (connection === 'open') {
            console.log('Connected! Bot LID:', sock.user?.lid);
        }
    });

    sock.ev.on('messages.upsert', async ({ messages }) => {
        for (const m of messages) {
            if (!m.message) continue;
            console.log('Message:', JSON.stringify(m, undefined, 2));
        }
    });

    sock.ev.on('creds.update', saveCreds);
}

connectToWhatsApp().catch(console.error);

Pairing Code (no QR)

import makeWASocket, { useMultiFileAuthState } from 'toxic-baileys';

async function connectWithPairing() {
    const { state, saveCreds } = await useMultiFileAuthState('auth_info_baileys');
    const sock = makeWASocket({ auth: state, printQRInTerminal: false });
    sock.ev.on('creds.update', saveCreds);

    if (!sock.authState.creds.registered) {
        const phoneNumber = '254712345678'; // no + or spaces
        const code = await sock.requestPairingCode(phoneNumber);
        console.log('Pairing Code:', code);
    }
}

connectWithPairing().catch(console.error);

🔌 Connection & Configuration

Full Socket Configuration

import makeWASocket, { Browsers, makeCacheableSignalKeyStore } from 'toxic-baileys';
import NodeCache from '@cacheable/node-cache';

const groupCache = new NodeCache({ stdTTL: 300, useClones: false });

const sock = makeWASocket({
    browser: Browsers.macOS('Chrome'),
    syncFullHistory: true,
    markOnlineOnConnect: false,
    connectTimeoutMs: 60_000,
    defaultQueryTimeoutMs: 60_000,
    keepAliveIntervalMs: 30_000,
    generateHighQualityLinkPreview: true,
    cachedGroupMetadata: async (jid) => groupCache.get(jid),
    getMessage: async (key) => await yourStore.getMessage(key),
});

sock.ev.on('groups.update', async ([event]) => {
    const metadata = await sock.groupMetadata(event.id);
    groupCache.set(event.id, metadata);
});

💾 Authentication State Management

Multi-File Auth (Development)

import makeWASocket, { useMultiFileAuthState } from 'toxic-baileys';

const { state, saveCreds } = await useMultiFileAuthState('./auth_info');
const sock = makeWASocket({ auth: state });
sock.ev.on('creds.update', saveCreds);

Custom Database Auth (Production)

import makeWASocket, { makeCacheableSignalKeyStore } from 'toxic-baileys';

const myAuthState = {
    creds: await db.getAuthCreds(),
    keys: makeCacheableSignalKeyStore(await db.getSignalKeys(), console)
};
const sock = makeWASocket({ auth: myAuthState });
sock.ev.on('creds.update', async (creds) => await db.saveAuthCreds(creds));

🆔 LID Mapping System

Important

This is one of the most critical new features in this fork. WhatsApp is migrating groups to use Linked Identity (LID) JIDs — identifiers in the @lid domain that replace @s.whatsapp.net phone-number JIDs for privacy and cross-platform reasons. If you receive a message from 1234567890:0@lid and don't have a mapping, you cannot identify the sender.

What is a LID?

A Linked Identity (LID) is an opaque numeric identifier assigned to each WhatsApp account in the @lid domain. WhatsApp uses LIDs in groups to decouple a person's phone number from their group identity. The LID is stable across phone number changes and is used for the Signal encryption protocol in newer group types.

Standard JID:  254712345678@s.whatsapp.net  ← phone number visible
LID JID:       9876543210:0@lid             ← opaque — phone number hidden

How the Mapping Store Works

This fork implements LIDMappingStore in src/Signal/lid-mapping.ts:

┌─────────────────────────────────────────────────────┐
│                  LIDMappingStore                     │
│                                                     │
│  LRU Cache (3-day TTL, auto-purge)                  │
│    pn:{pnUser}  →  lidUser                          │
│    lid:{lidUser} →  pnUser                          │
│         ↕                                           │
│  SignalKeyStoreWithTransaction                      │
│    lid-mapping/{pnUser}          → lidUser          │
│    lid-mapping/{lidUser}_reverse → pnUser           │
│         ↕                                           │
│  USync Lookup (UsyncLIDProtocol)                    │
│    Query WhatsApp servers via w:sync IQ             │
└─────────────────────────────────────────────────────┘

Persistent file naming (with useMultiFileAuthState):

Session/
  lid-mapping-{pnUser}.json           ← pnUser → lidUser
  lid-mapping-{lidUser}_reverse.json  ← lidUser → pnUser  (reverse lookup)

`me.lid` — Your Bot's Own LID

When your bot pairs with WhatsApp, its own LID is stored in the session credentials:

// Stored automatically by configureSuccessfulPairing()
// Access it any time after connecting:
const myLid = sock.user?.lid;
console.log('My LID:', myLid); // e.g. "9876543210@lid"

`lidDbMigrated` Login Flag

The login payload includes lidDbMigrated: false. This signals to WhatsApp that the client has not yet migrated its local LID database, which causes WhatsApp to push down a full set of LID↔PN mappings on the initial connection — seeding your local store automatically.

API Reference

// On the socket (via SignalRepositoryWithLIDStore):
sock.signalRepository.lidMapping.getPNForLID(lidJid)         // string | null
sock.signalRepository.lidMapping.getLIDForPN(pnJid)          // string | null
sock.signalRepository.lidMapping.getPNsForLIDs(lidJids[])    // LIDMapping[] | null
sock.signalRepository.lidMapping.getLIDsForPNs(pnJids[])     // LIDMapping[] | null
sock.signalRepository.lidMapping.storeLIDPNMappings(pairs[]) // void

// Type:
type LIDMapping = { lid: string; pn: string }

Live Integration Example

import makeWASocket, { useMultiFileAuthState, makeCacheableSignalKeyStore } from 'toxic-baileys';

const { state, saveCreds } = await useMultiFileAuthState('./Session');
const lidPhoneCache = new Map();

const sock = makeWASocket({
    auth: {
        creds: state.creds,
        keys: makeCacheableSignalKeyStore(state.keys, console)
    }
});

sock.ev.on('creds.update', saveCreds);

// Wire up LID globals for use throughout your bot
globalThis.resolvePhoneFromLid = (lidJid) => {
    // synchronous — only works if the mapping is already cached
    return null;
};

globalThis.resolvePhoneFromLidAsync = async (lidJid) => {
    return await sock.signalRepository.lidMapping.getPNForLID(lidJid);
};

// Keep the in-memory cache warm from live LID mapping events
sock.ev.on('lid-mapping.update', (map) => {
    for (const [lid, pn] of Object.entries(map)) {
        const lidNum = lid.split('@')[0].split(':')[0];
        const phone = String(pn).split('@')[0].split(':')[0].replace(/\D/g, '');
        if (lidNum && phone) lidPhoneCache.set(lidNum, phone);
    }
});

// Resolving a sender from a group message
sock.ev.on('messages.upsert', async ({ messages }) => {
    for (const m of messages) {
        const sender = m.key.participant || m.key.remoteJid || '';
        if (sender.endsWith('@lid')) {
            const resolved = await sock.signalRepository.lidMapping.getPNForLID(sender);
            console.log(`LID ${sender} → ${resolved ?? 'unknown'}`);
        }
    }
});

Multi-Layer Resolution (Recommended Pattern)

For maximum reliability, resolve LIDs in this priority order:

async function resolveLid(lidJid, sock, lidPhoneCache) {
    const lidNum = lidJid.split('@')[0].split(':')[0].replace(/\D/g, '');
    if (!lidNum) return null;

    // 1. In-memory LRU cache (fastest)
    const cached = lidPhoneCache?.get(lidNum);
    if (cached) return String(cached).replace(/\D/g, '') + '@s.whatsapp.net';

    // 2. Baileys LIDMappingStore (LRU + persistent key store)
    const fromStore = await sock.signalRepository?.lidMapping?.getPNForLID(lidJid);
    if (fromStore) {
        const num = fromStore.split('@')[0].replace(/\D/g, '');
        if (num) { lidPhoneCache?.set(lidNum, num); return num + '@s.whatsapp.net'; }
    }

    // 3. Session file (lid-mapping-{lidNum}_reverse.json)
    try {
        const revFile = `./Session/lid-mapping-${lidNum}_reverse.json`;
        if (fs.existsSync(revFile)) {
            const jid = JSON.parse(fs.readFileSync(revFile, 'utf-8'));
            const num = String(jid).split('@')[0].replace(/\D/g, '');
            if (num && num !== lidNum) {
                lidPhoneCache?.set(lidNum, num);
                return num + '@s.whatsapp.net';
            }
        }
    } catch {}

    // 4. Group metadata participant scan (network call — use sparingly)
    try {
        const meta = await sock.groupMetadata(chatJid);
        for (const p of meta.participants || []) {
            const pLid = (p.lid || p.id || '').split('@')[0].split(':')[0].replace(/\D/g, '');
            if (pLid !== lidNum) continue;
            const pBase = p.id || p.jid || '';
            if (pBase && !pBase.endsWith('@lid')) {
                const num = pBase.split('@')[0].replace(/\D/g, '');
                if (num) { lidPhoneCache?.set(lidNum, num); return num + '@s.whatsapp.net'; }
            }
        }
    } catch {}

    return null; // unresolvable — pass lidJid through and let WhatsApp handle it
}

Note

Session file cleanup warning: If your bot cleans up session files periodically, make sure lid-mapping-* files are preserved in your keep-list, or your mapping cache will be lost on restart and need to be re-fetched from WhatsApp's servers.

🤖 AI Groups

WhatsApp introduced AI-powered groups — special group types that include an AI bot participant. This fork exposes full management of these groups via makeAIGroupsSocket (which is included in the socket chain automatically).

Socket Chain

makeWASocket
  └─ makeInteropSocket
       └─ makeAIGroupsSocket
            └─ makeCommunitiesSocket
                 └─ makeGroupsSocket
                      └─ ...

AI Group Events

// Automatically fires when an AI group is created
sock.ev.on('groups.upsert', ([groupMeta]) => {
    console.log('New group:', groupMeta.id, groupMeta.subject);
});

// Fires on participant changes (add/remove/promote/demote) in AI groups
sock.ev.on('group-participants.update', ({ id, participants, action }) => {
    console.log(`${action} in ${id}:`, participants);
});

AI Group Metadata

// Fetch full metadata for an AI group (uses interactive query)
const meta = await sock.aiGroupMetadata('1234567890@g.us');
console.log('AI group subject:', meta.subject);
console.log('Participants:', meta.participants);

Add Bot to AI Group

// Add an AI bot participant to an AI group
await sock.aiGroupAddBot('1234567890@g.us');

🔗 Interoperability API

WhatsApp's interoperability (interop) system allows messages to be exchanged with third-party messaging platforms. This fork exposes the full interop socket layer via makeInteropSocket.

Supported Integrators

ID	Name	Notes
`12`	BirdyChat	Cross-platform messaging bridge
`13`	Haiket	Cross-platform messaging bridge

Fetch Available Integrators

const integrators = await sock.fetchIntegrators();
/*
[
  {
    id: 12,
    name: 'BirdyChat',
    status: 'active',         // 'active' | 'onboarding' | 'removed'
    identifierType: 'pn',     // 'email' | 'pn' | 'username'
    optedIn: false,
    features: { groupMessaging: true }
  },
  ...
]
*/

Accept Interop Terms of Service

// Must be called before opting in to any integrator
await sock.acceptInteropTOS();

Opt In to Integrators

// Opt in to all default integrators (BirdyChat + Haiket)
await sock.optInIntegrators();

// Opt in to specific integrators by ID
await sock.optInIntegrators([12]);

🔄 USync Protocol

WAUSync is WhatsApp's batch user-info query system. This fork exports the full USync module so you can run structured queries against WhatsApp's w:sync:user IQ namespace.

Available Protocols

Protocol Class	Purpose
`USyncContactProtocol`	Resolve contact info
`USyncDeviceProtocol`	Fetch registered devices
`USyncDisappearingModeProtocol`	Get disappearing message settings
`USyncStatusProtocol`	Fetch user status
`USyncUsernameProtocol`	Resolve usernames
`UsyncBotProfileProtocol`	Fetch AI bot profile data
`UsyncLIDProtocol`	Resolve LID ↔ phone-number pairs

Running a USync Query

import { USyncQuery, USyncUser, UsyncLIDProtocol, USyncDeviceProtocol } from 'toxic-baileys';

const query = new USyncQuery();
query.withContext('interactive');
query.withProtocol(new UsyncLIDProtocol());
query.withProtocol(new USyncDeviceProtocol());

const user = new USyncUser();
user.withPhone('254712345678@s.whatsapp.net');
query.withUser(user);

const result = await sock.executeUSyncRequest(query);
console.log(result);

MEX / GraphQL Queries

For structured server queries, this fork exposes executeWMexQuery — a GraphQL-style query executor over WhatsApp's w:mex IQ namespace:

import { executeWMexQuery } from 'toxic-baileys';

const result = await executeWMexQuery(
    { userId: '254712345678' },   // variables
    'xwa2_user_profile',          // queryId (WhatsApp's internal query name)
    'xwa2_user_profile',          // dataPath (key in the response data object)
    sock.query.bind(sock),        // query function
    sock.generateMessageTag.bind(sock)
);
console.log('MEX result:', result);

📤 Sending Messages

Basic Messages

Text, Reply, Mention, Forward, Edit, Delete, React

await sock.sendMessage(jid, { text: 'Hello World!' });
await sock.sendMessage(jid, { text: 'Reply!' }, { quoted: m });
await sock.sendMessage(jid, { text: 'Hi @user!', mentions: ['254712345678@s.whatsapp.net'] });
await sock.sendMessage(jid, { forward: m });

const sent = await sock.sendMessage(jid, { text: 'Original' });
await sock.sendMessage(jid, { text: 'Edited!', edit: sent.key });
await sock.sendMessage(jid, { delete: sent.key });

await sock.sendMessage(jid, { react: { text: '🔥', key: m.key } });
await sock.sendMessage(jid, { react: { text: '', key: m.key } }); // remove reaction

Media Messages

Image, Video, Audio, Document, Sticker, View Once

await sock.sendMessage(jid, { image: { url: './image.jpg' }, caption: 'Caption' });
await sock.sendMessage(jid, { image: fs.readFileSync('./img.jpg') });
await sock.sendMessage(jid, { video: { url: './video.mp4' }, caption: 'Video' });
await sock.sendMessage(jid, { video: { url: './animation.mp4' }, gifPlayback: true });
await sock.sendMessage(jid, { audio: { url: './voice.ogg' }, mimetype: 'audio/ogg; codecs=opus', ptt: true });
await sock.sendMessage(jid, { audio: { url: './song.mp3' }, mimetype: 'audio/mp4' });
await sock.sendMessage(jid, { document: { url: './file.pdf' }, fileName: 'MyDoc.pdf', mimetype: 'application/pdf' });
await sock.sendMessage(jid, { sticker: { url: './sticker.webp' } });
await sock.sendMessage(jid, { image: fs.readFileSync('./img.jpg'), viewOnce: true });

Interactive Messages

Interactive Message with Native Flow Buttons

// Copy button
await sock.sendMessage(jid, {
    interactiveMessage: {
        header: 'toxic-baileys™',
        title: 'Hello World',
        footer: 'By 𝐱𝐡_𝐜𝐥𝐢𝐧𝐭𝐨𝐧 ✓',
        buttons: [
            {
                name: 'cta_copy',
                buttonParamsJson: JSON.stringify({ display_text: 'Copy Code', id: '1', copy_code: 'TOXIC123' })
            }
        ]
    }
}, { quoted: m });

// URL button
await sock.sendMessage(jid, {
    interactiveMessage: {
        header: 'Visit Us',
        title: 'toxic-baileys',
        footer: 'GitHub',
        buttons: [
            {
                name: 'cta_url',
                buttonParamsJson: JSON.stringify({ display_text: 'Open GitHub', url: 'https://github.com/xhclintohn/Baileys' })
            }
        ]
    }
}, { quoted: m });

// With image thumbnail
await sock.sendMessage(jid, {
    interactiveMessage: {
        header: 'With Image',
        title: 'toxic-baileys™',
        footer: 'Best Baileys Fork',
        image: { url: 'https://example.com/image.jpg' },
        buttons: [
            { name: 'cta_copy', buttonParamsJson: JSON.stringify({ display_text: 'Copy', id: '1', copy_code: 'HELLO' }) }
        ]
    }
}, { quoted: m });

// Single select list
await sock.sendMessage(jid, {
    interactiveMessage: {
        header: 'Choose',
        title: 'Menu',
        footer: 'Select below',
        nativeFlowMessage: {
            buttons: [
                {
                    name: 'single_select',
                    buttonParamsJson: JSON.stringify({
                        title: 'Options',
                        sections: [
                            {
                                title: 'Commands',
                                rows: [
                                    { title: 'Option 1', description: 'First', id: 'opt_1' },
                                    { title: 'Option 2', description: 'Second', id: 'opt_2' }
                                ]
                            }
                        ]
                    })
                }
            ]
        }
    }
}, { quoted: m });

// With externalAdReply
await sock.sendMessage(jid, {
    interactiveMessage: {
        header: 'Premium',
        title: 'toxic-baileys™',
        footer: 'By 𝐱𝐡_𝐜𝐥𝐢𝐧𝐭𝐨𝐧',
        externalAdReply: {
            title: 'toxic-baileys',
            body: 'Best WhatsApp Library',
            mediaType: 1,
            thumbnailUrl: 'https://example.com/thumb.jpg',
            sourceUrl: 'https://github.com/xhclintohn/Baileys',
            showAdAttribution: true,
            renderLargerThumbnail: true
        },
        buttons: [
            { name: 'cta_url', buttonParamsJson: JSON.stringify({ display_text: 'Visit', url: 'https://github.com/xhclintohn/Baileys' }) }
        ]
    }
}, { quoted: m });

Album Messages

Send multiple images/videos in a single album

await sock.sendMessage(jid, {
    albumMessage: [
        { image: fs.readFileSync('./photo1.jpg'), caption: 'First photo' },
        { image: { url: 'https://example.com/photo2.jpg' }, caption: 'Second photo' },
        { video: fs.readFileSync('./clip.mp4'), caption: 'A video clip' }
    ]
}, { quoted: m });

Event Messages

Send WhatsApp event invitations

await sock.sendMessage(jid, {
    eventMessage: {
        isCanceled: false,
        name: 'toxic-baileys Launch',
        description: 'Join us for the launch!',
        location: { degreesLatitude: -1.2921, degreesLongitude: 36.8219, name: 'Nairobi, Kenya' },
        joinLink: 'https://call.whatsapp.com/video/your-link',
        startTime: String(Math.floor(Date.now() / 1000) + 3600),
        endTime: String(Math.floor(Date.now() / 1000) + 7200),
        extraGuestsAllowed: true
    }
}, { quoted: m });

Poll & Poll Result Messages

Polls and displaying poll results

// Create poll
await sock.sendMessage(jid, {
    poll: {
        name: 'Best WhatsApp library?',
        values: ['toxic-baileys', 'Baileys', 'Other'],
        selectableCount: 1
    }
});

// Display poll results
await sock.sendMessage(jid, {
    pollResultMessage: {
        name: 'Best Library Results',
        pollVotes: [
            { optionName: 'toxic-baileys', optionVoteCount: '42' },
            { optionName: 'Baileys', optionVoteCount: '10' },
            { optionName: 'Other', optionVoteCount: '2' }
        ]
    }
}, { quoted: m });

Group Status Messages

Post status/story to a group (Group Status V2)

await sock.sendMessage(groupJid, { groupStatusMessage: { text: 'Hello group! 👋' } });
await sock.sendMessage(groupJid, { groupStatusMessage: { image: fs.readFileSync('./banner.jpg'), caption: 'Update!' } });
await sock.sendMessage(groupJid, { groupStatusMessage: { video: fs.readFileSync('./promo.mp4'), caption: 'Promo' } });
await sock.sendMessage(groupJid, { groupStatusMessage: { audio: fs.readFileSync('./audio.mp4'), mimetype: 'audio/mp4' } });

// Using ToxicHandler directly (exposed on socket)
const storyResult = await sock.toxicHandler.handleGroupStory(content, groupJid, quotedMsg);

Payment Request Messages

Send payment requests

await sock.sendMessage(jid, {
    requestPaymentMessage: {
        currency: 'KES',
        amount: 500000,
        from: m.sender,
        background: { id: 'DEFAULT', placeholderArgb: 0xFFF0F0F0 }
    }
}, { quoted: m });

Product Messages

Send product catalog messages

await sock.sendMessage(jid, {
    productMessage: {
        title: 'Premium Script',
        description: 'Best bot script available',
        thumbnail: { url: 'https://example.com/product.jpg' },
        productId: 'PROD001',
        retailerId: 'xhclinton',
        url: 'https://github.com/xhclintohn/Baileys',
        body: 'Full featured automation',
        footer: 'Special price',
        priceAmount1000: 10000,
        currencyCode: 'USD',
        buttons: [{ name: 'cta_url', buttonParamsJson: JSON.stringify({ display_text: 'Buy Now', url: 'https://github.com/xhclintohn/Baileys' }) }]
    }
}, { quoted: m });

Button & Template Messages

Classic buttons, list messages, template buttons

// Classic buttons
await sock.sendMessage(jid, {
    text: 'Choose:',
    footer: 'toxic-baileys™',
    buttons: [
        { buttonId: 'btn_1', buttonText: { displayText: 'Option 1' }, type: 1 },
        { buttonId: 'btn_2', buttonText: { displayText: 'Option 2' }, type: 1 }
    ],
    headerType: 1
});

// List message
await sock.sendMessage(jid, {
    text: 'Pick one:',
    footer: 'toxic-baileys™',
    title: 'Menu',
    buttonText: 'Open List',
    sections: [
        {
            title: 'Section 1',
            rows: [
                { title: 'Item 1', rowId: 'row_1', description: 'Description 1' },
                { title: 'Item 2', rowId: 'row_2', description: 'Description 2' }
            ]
        }
    ]
});

📁 Chat & Message Management

Read receipts, archive, pin, delete, star

await sock.readMessages([m.key]);
await sock.sendReadReceipt(jid, participant, [m.key.id]);
await sock.chatModify({ archive: true, lastMessages: [{ key: m.key, messageTimestamp: m.messageTimestamp }] }, jid);
await sock.chatModify({ pin: true }, jid);
await sock.chatModify({ delete: true, lastMessages: [{ key: m.key, messageTimestamp: m.messageTimestamp }] }, jid);
await sock.chatModify({ star: { messages: [{ id: m.key.id, fromMe: m.key.fromMe }], star: true } }, jid);
await sock.sendMessage(jid, { delete: m.key });

👥 Group Management

Create, modify, manage participants

const group = await sock.groupCreate('Group Name', ['254712345678@s.whatsapp.net']);
await sock.groupParticipantsUpdate(jid, ['254712345678@s.whatsapp.net'], 'add');
await sock.groupParticipantsUpdate(jid, ['254712345678@s.whatsapp.net'], 'remove');
await sock.groupParticipantsUpdate(jid, ['254712345678@s.whatsapp.net'], 'promote');
await sock.groupParticipantsUpdate(jid, ['254712345678@s.whatsapp.net'], 'demote');
await sock.groupUpdateSubject(jid, 'New Name');
await sock.groupUpdateDescription(jid, 'New description');
await sock.groupSettingUpdate(jid, 'announcement');
await sock.groupSettingUpdate(jid, 'not_announcement');
await sock.groupSettingUpdate(jid, 'locked');
await sock.groupSettingUpdate(jid, 'unlocked');
await sock.groupLeave(jid);
const inviteCode = await sock.groupInviteCode(jid);
const meta = await sock.groupMetadata(jid);
const all = await sock.groupFetchAllParticipating();

👤 User & Profile Management

Profile photo, status, presence

await sock.updateProfilePicture(jid, { url: './avatar.jpg' });
await sock.removeProfilePicture(jid);
const pp = await sock.profilePictureUrl(jid, 'image');
await sock.updateProfileStatus('Hey there! I am using toxic-baileys™');
await sock.updateProfileName('My Bot Name');
await sock.fetchStatus(jid);
const exists = await sock.onWhatsApp('254712345678@s.whatsapp.net');
await sock.sendPresenceUpdate('available', jid);
await sock.sendPresenceUpdate('composing', jid);
await sock.sendPresenceUpdate('recording', jid);
await sock.sendPresenceUpdate('paused', jid);

📡 Newsletter / Channel Management

Create, follow, manage newsletters and channels

import { newsletterId } from 'toxic-baileys';

// Follow a channel
await sock.newsletterFollow('1234567890@newsletter');

// Unfollow
await sock.newsletterUnfollow('1234567890@newsletter');

// Fetch channel metadata
const meta = await sock.newsletterMetadata('invite', 'your-invite-link');
console.log(meta.id, meta.name, meta.subscribers);

// Create a channel
const channel = await sock.newsletterCreate('Channel Name', { description: 'My channel' });

// Send a message to your channel
await sock.sendMessage('1234567890@newsletter', { text: 'Channel update!' });

// newsletterId() helper — extract clean ID from any format
const cleanId = newsletterId('1234567890@newsletter');
const cleanIdFromLink = newsletterId('https://whatsapp.com/channel/yourlink');
console.log('Clean ID:', cleanId);

// Mute/unmute
await sock.newsletterMute('1234567890@newsletter');
await sock.newsletterUnmute('1234567890@newsletter');

🔒 Privacy & Block Management

Privacy settings and block list

await sock.updateProfilePicturePrivacy('contacts');   // 'all' | 'contacts' | 'contact_blacklist' | 'none'
await sock.updateStatusPrivacy('contacts');
await sock.updateReadReceiptsPrivacy('all');           // 'all' | 'none'
await sock.updateGroupsAddPrivacy('contacts');
await sock.updateLastSeenPrivacy('contacts');
await sock.updateOnlinePrivacy('all');

const privacy = await sock.fetchPrivacySettings(true);

await sock.updateBlockStatus(jid, 'block');
await sock.updateBlockStatus(jid, 'unblock');
const blocked = await sock.fetchBlocklist();

🗄️ Data Store Implementation

In-Memory Store (Development)

import makeWASocket, { makeInMemoryStore } from 'toxic-baileys';

const store = makeInMemoryStore({ logger: console });
store.readFromFile('./baileys_store.json');
setInterval(() => store.writeToFile('./baileys_store.json'), 10_000);

const sock = makeWASocket({});
store.bind(sock.ev);

Using ToxicHandler Directly

// ToxicHandler and toxicHandler are both exposed on the socket
const { toxicHandler } = sock;

const paymentContent  = await toxicHandler.handlePayment(content, quoted);
const interactive     = await toxicHandler.handleInteractive(content, jid, quoted);
const album           = await toxicHandler.handleAlbum(content, jid, quoted);
const event           = await toxicHandler.handleEvent(content, jid, quoted);
const pollResult      = await toxicHandler.handlePollResult(content, jid, quoted);
const groupStory      = await toxicHandler.handleGroupStory(content, jid, quoted);

🛠️ Utility Functions

Core Utilities

import {
    getContentType, areJidsSameUser, isJidGroup, isJidBroadcast,
    isJidStatusBroadcast, isJidNewsLetter, jidNormalizedUser,
    isLidUser, isPnUser, isHostedPnUser,
    generateMessageID, generateMessageIDV2, generateWAMessage,
    generateWAMessageContent, generateWAMessageFromContent,
    downloadContentFromMessage, getAggregateVotesInPollMessage,
    extractMessageContent, normalizeMessageContent, newsletterId,
    proto
} from 'toxic-baileys';

const type = getContentType(m.message);
console.log(isJidGroup('123@g.us'));           // true
console.log(isJidNewsLetter('123@newsletter')); // true
console.log(isLidUser('12345@lid'));            // true

// Extract clean newsletter ID
const id = newsletterId('https://whatsapp.com/channel/mylink');

// Download media
const stream = await downloadContentFromMessage(m.message.imageMessage, 'image');
const chunks = [];
for await (const chunk of stream) chunks.push(chunk);
const buffer = Buffer.concat(chunks);

// Aggregate poll votes
const votes = getAggregateVotesInPollMessage(
    { message: pollMsg.message, pollUpdates },
    sock.user.id
);

💡 Best Practices & Tips

Connection Stability

Always implement reconnect logic on connection === 'close'
Cache group metadata using cachedGroupMetadata
Use markOnlineOnConnect: false to still receive phone notifications
Set syncFullHistory: true for complete history

LID Mapping

Always preserve lid-mapping-* files in session cleanup routines
Listen to the lid-mapping.update event to keep your in-memory cache warm
Fall back to group metadata scan only when all cache/store lookups fail
Use sock.user?.lid to access your own bot's LID identity

Performance

Use @cacheable/node-cache for group metadata caching
Implement a message queue with rate limiting for bulk sends
Use databases instead of in-memory store for production

Auto-reconnect pattern

async function connectWithRetry(maxRetries = 10) {
    let attempt = 0;
    const connect = async () => {
        attempt++;
        try {
            const { state, saveCreds } = await useMultiFileAuthState('./auth');
            const sock = makeWASocket({ auth: state });
            sock.ev.on('creds.update', saveCreds);
            sock.ev.on('connection.update', async ({ connection, lastDisconnect }) => {
                if (connection === 'close') {
                    const code = lastDisconnect?.error?.output?.statusCode;
                    if (code === DisconnectReason.loggedOut) return;
                    const delay = Math.min(5000 * attempt, 60000);
                    if (attempt < maxRetries) setTimeout(connect, delay);
                } else if (connection === 'open') {
                    attempt = 0;
                }
            });
        } catch (err) {
            if (attempt < maxRetries) setTimeout(connect, 5000 * attempt);
        }
    };
    await connect();
}

Message queue with rate limiting

class MessageQueue {
    constructor(sock, delayMs = 1000) {
        this.sock = sock;
        this.queue = [];
        this.processing = false;
        this.delayMs = delayMs;
    }
    async add(jid, content, options = {}) {
        this.queue.push({ jid, content, options });
        if (!this.processing) this._process();
    }
    async _process() {
        this.processing = true;
        while (this.queue.length > 0) {
            const { jid, content, options } = this.queue.shift();
            try {
                await this.sock.sendMessage(jid, content, options);
                await new Promise(r => setTimeout(r, this.delayMs));
            } catch (err) {
                console.error('Send failed:', err.message);
            }
        }
        this.processing = false;
    }
}

const queue = new MessageQueue(sock, 1500);
await queue.add(jid, { text: 'Message 1' });
await queue.add(jid, { text: 'Message 2' });

⚠️ Important Legal Notice

This project is NOT affiliated with, authorized, maintained, sponsored, or endorsed by WhatsApp LLC or any of its affiliates.

Only message users who have explicitly consented
Do NOT use for spamming, bulk unsolicited messaging, or harassment
Respect WhatsApp's Terms of Service and rate limits
The maintainer assumes NO liability for misuse or damages

🆘 Getting Help

GitHub Issues — github.com/xhclintohn/Baileys/issues
Response Time — Typically within 24–48 hours

📄 License

MIT License. See LICENSE for details.

Credits: Original Baileys by WhiskeySockets · toxic-baileys enhancements by 𝐱𝐡_𝐜𝐥𝐢𝐧𝐭𝐨𝐧 ✓

🌟 toxic-baileys™ — Crafted with ❤️ by 𝐱𝐡_𝐜𝐥𝐢𝐧𝐭𝐨𝐧 ✓

The most powerful WhatsApp automation toolkit

⭐ Star the repository if this helped you!

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
Example		Example
Media		Media
WAProto		WAProto
lib		lib
proto-extract		proto-extract
scripts		scripts
src		src
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
engine-requirements.js		engine-requirements.js
eslint.config.mts		eslint.config.mts
jest.config.ts		jest.config.ts
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
typedoc.json		typedoc.json
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

toxic-baileys™ ⭐

🆔 LID Mapping — Critical Feature in This Fork

📋 Table of Contents

🆕 What's New

✨ Features

📦 Installation

Via npm

Via Yarn

From GitHub (edge)

Drop-in replacement for @whiskeysockets/baileys

🚀 Quick Start

🔌 Connection & Configuration

💾 Authentication State Management

🆔 LID Mapping System

What is a LID?

How the Mapping Store Works

me.lid — Your Bot's Own LID

lidDbMigrated Login Flag

API Reference

Live Integration Example

Multi-Layer Resolution (Recommended Pattern)

🤖 AI Groups

Socket Chain

AI Group Events

AI Group Metadata

Add Bot to AI Group

🔗 Interoperability API

Supported Integrators

Fetch Available Integrators

Accept Interop Terms of Service

Opt In to Integrators

🔄 USync Protocol

Available Protocols

Running a USync Query

MEX / GraphQL Queries

📤 Sending Messages

Basic Messages

Media Messages

Interactive Messages

Album Messages

Event Messages

Poll & Poll Result Messages

Group Status Messages

Payment Request Messages

Product Messages

Button & Template Messages

📁 Chat & Message Management

👥 Group Management

👤 User & Profile Management

📡 Newsletter / Channel Management

🔒 Privacy & Block Management

🗄️ Data Store Implementation

🛠️ Utility Functions

💡 Best Practices & Tips

Connection Stability

LID Mapping

Performance

⚠️ Important Legal Notice

🆘 Getting Help

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Drop-in replacement for `@whiskeysockets/baileys`

`me.lid` — Your Bot's Own LID

`lidDbMigrated` Login Flag

Packages