@codexverified/baileys

A readable, carefully maintained Baileys distribution for building reliable WhatsApp integrations with codexverified/baileys.

@codexverified/baileys is a Node.js and TypeScript library for creating WhatsApp automations over the Baileys protocol. It provides a socket-oriented API for authentication, messaging, media, interactive content, rich responses, newsletters, groups, communities, business features, account utilities, and carefully documented extensions.

The package is maintained by Codex under the CodexVerified organization. It is intended for developers who want a practical Baileys foundation with familiar interfaces, public TypeScript declarations, readable source code, explicit behavior, and room for carefully tested improvements.

At a glance

This release is version 2.10.12. It uses ECMAScript modules, supports CommonJS usage where the installed Node.js version permits it, ships public TypeScript declarations, and targets Node.js 20 or newer.

| Property | Value | | --- | --- | | Package | @codexverified/baileys | | Version | 2.10.12 | | Runtime | Node.js 20 or newer | | Module format | ESM, with CommonJS compatibility where supported | | Type declarations | Included at lib/index.d.ts | | License | MIT, as declared by the package metadata | | Maintainer | Codex | | Entry point | lib/index.js | | Repository | https://github.com/codexverified/baileys |

Installation

Install the package from npm when it is published under your organization:

npm install @codexverified/baileys

To install a local package archive, place the .tgz file beside your application and run:

npm install ./codex-baileys-2.10.12.tgz

Both installation methods use the same import name:

import { makeWASocket } from '@codexverified/baileys'

For local source auditing, install dependencies without executing package installation hooks:

npm install --ignore-scripts

Quick start

The following example creates a socket, stores multi-file authentication credentials, reconnects after an unexpected disconnect, and replies to incoming messages. Keep the session directory private and never commit it to a public repository.

import {
  DisconnectReason,
  makeWASocket,
  useMultiFileAuthState
} from '@codexverified/baileys'
import P from 'pino'

async function start() {
  const { state, saveCreds } = await useMultiFileAuthState('./session')

  const sock = makeWASocket({
    auth: state,
    logger: P({ level: 'silent' })
  })

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

  sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
    if (connection === 'open') {
      console.log('Connected with @codexverified/baileys')
    }

    if (connection === 'close') {
      const statusCode = lastDisconnect?.error?.output?.statusCode
      if (statusCode !== DisconnectReason.loggedOut) {
        start().catch(console.error)
      }
    }
  })

  sock.ev.on('messages.upsert', async ({ messages }) => {
    for (const message of messages) {
      if (!message.message || message.key.fromMe) continue

      await sock.sendMessage(message.key.remoteJid, {
        text: 'Hello from @codexverified/baileys'
      })
    }
  })
}

start().catch(console.error)

CommonJS usage

For supported Node.js versions, the package can also be loaded through CommonJS:

const {
  makeWASocket,
  useMultiFileAuthState
} = require('@codexverified/baileys')

If your runtime or bundler does not support this interop path, use the ESM import form instead.

Core capabilities

Connections and authentication

The socket layer manages WebSocket connection events, reconnect handling, browser identity configuration, pairing-code flows, and connection state transitions. Authentication helpers include multi-file credentials for standard deployments, single-file state for compact setups, SQLite-backed persistence when the optional driver is installed, and cache-manager integrations for applications that need custom persistence.

Messages and conversations

The message API supports text, mentions, replies, reactions, edits, deletions, forwards, polls, contacts, locations, events, group invitations, quoted messages, disappearing messages, view-once envelopes, and other protocol message types. Message composition is centralized so applications can use the ordinary sendMessage flow while opting into advanced structures when required.

Media and albums

Images, video, audio, documents, stickers, thumbnails, and albums are supported. Media can be prepared from URLs, local files, or buffers according to the upload configuration. Video messages can opt into GIF playback, and the image-processing layer can use an available sharp, @napi-rs/image, or jimp implementation. Album child-message association uses the WhatsApp-compatible wire value.

Interactive content

The package includes interactive buttons, lists, native flows, hydrated templates, carousel layouts, button grids, and other structured message formats. Interactive identifiers should be stable and unique within the application. Receiving code should handle the possibility that different WhatsApp clients deliver a selected value through different response envelopes.

Rich content and previews

Rich-response utilities cover code blocks, tables, inline entities, LaTeX-oriented content, link previews, and structured response arrays. Rich previews can fetch a title, description, and image for a URL when the optional dependency and network access are available. Applications should retain a plain-text fallback for clients that do not render rich content.

Rich menus

The experimental richMenu helper builds a structured rich-response envelope with an optional header image, row or carousel cards, stable button identifiers, toast metadata, disclaimers, and a footer action. The package also exposes lower-level preparation utilities for applications that need more control. Rich menus are client-dependent and should be tested against the WhatsApp versions used by the application.

Groups and communities

Group operations include group creation, participant management, settings, metadata, invites, labels, and community relationships. Community helpers support linked groups and subgroup operations where the connected account and current protocol permit them.

Newsletters and channel operations

Newsletter utilities cover channel metadata, following and unfollowing, posts, reactions, media, and polls. Following is consumer-controlled: the library does not silently follow a trusted channel, inject a fallback channel identifier, or add an automatic channel pill to generated media. Applications should request newsletter actions explicitly and validate identifiers before sending requests.

Account, business, and privacy tools

The package includes profile and business helpers, product and catalog operations, privacy controls, username utilities, account-layer and interoperation helpers, status publishing, favorites management, and selected account-management operations. Availability depends on the connected account, WhatsApp rollout, and the permissions associated with that account.

Storage and protocol utilities

The distribution includes in-memory and ordered-dictionary stores, cache-manager support, authentication persistence, LID and phone-number resolution, event utilities, message normalization, media retry handling, protocol helpers, and TypeScript declarations in lib/index.d.ts.

Everyday message usage

Send a text message with the standard socket method:

await sock.sendMessage(jid, {
  text: 'A message from Codex'
})

Send media with a caption:

await sock.sendMessage(jid, {
  image: { url: './media/photo.jpg' },
  caption: 'A photo message'
})

Send a video with GIF-style playback enabled:

await sock.sendMessage(jid, {
  video: { url: './media/animation.mp4' },
  gifPlayback: true,
  caption: 'Animated media'
})

Use the existing explicit view-once options when you want the media to use a view-once envelope:

await sock.sendMessage(jid, {
  image: { url: './media/private-image.jpg' },
  caption: 'Open once',
  viewOnce: true
})

The compatible mediaSpoilerMode option provides an additional explicit path. Set it to viewOnce for supported image, video, document, or sticker media, or set it to native to apply the native spoiler context flag. The option is intentionally opt-in and does not change the default behavior of existing applications.

await sock.sendMessage(jid, {
  video: { url: './media/clip.mp4' },
  caption: 'View-once video',
  mediaSpoilerMode: 'viewOnce'
})

await sock.sendMessage(jid, {
  image: { url: './media/hidden-preview.jpg' },
  mediaSpoilerMode: 'native'
})

The existing viewOnce, viewOnceV2, viewOnceV2Extension, and spoiler options remain supported. When an explicit view-once option is enabled, it takes precedence over mediaSpoilerMode.

Rich menu example

The experimental rich-menu helper accepts a header, card rows or a carousel, stable button IDs, and a footer action:

await sock.richMenu(jid, {
  header: {
    title: 'Codex Menu',
    image: {
      url: 'https://example.com/menu.jpg',
      mime_type: 'image/jpeg'
    }
  },
  body: {
    row: true,
    carousel: false,
    cards: [
      {
        title: 'Account',
        buttons: [
          { id: 'profile', text: 'Profile' },
          { id: 'settings', text: 'Settings' }
        ]
      },
      {
        title: 'Support',
        buttons: ['help', 'contact']
      }
    ]
  },
  footer: {
    text: 'Codex Technology',
    url: 'https://example.com'
  }
})

Status, grids, tables, and flows

The socket also provides helpers for status posts, status mentions, button grids, interactive tables, and WhatsApp flows:

await sock.sendStatus({ text: 'New Codex status' }, {
  statusJidList: ['[email protected]']
})

await sock.sendRichButtonGrid(jid, {
  text: 'Choose an option',
  cards: [{
    title: 'Actions',
    buttons: [
      { id: 'first_action', text: 'First action' },
      { id: 'second_action', text: 'Second action' }
    ]
  }]
})

await sock.sendInteractiveTable(jid, {
  title: 'Plans',
  headers: ['Name', 'Price'],
  rows: [['Basic', '$5'], ['Pro', '$10']],
  buttons: [{ id: 'choose_pro', text: 'Choose Pro' }],
  footer: 'Select a plan'
})

await sock.sendWhatsAppFlow(jid, {
  text: 'Open the form',
  flowId: 'your-flow-id',
  flowToken: 'your-flow-token',
  flowName: 'your-flow-name',
  flowAction: 'navigate',
  flowActionPayload: { screen: 'WELCOME' }
})

These helpers are protocol- and client-dependent. Use graceful fallbacks when an application serves a wide range of WhatsApp client versions.

Authentication and deployment guidance

Authentication data contains sensitive account credentials. Keep the session directory private, exclude it from version control, and use a dedicated service account or restricted filesystem permissions where possible. Do not place access tokens, private keys, phone numbers, or personal account data in the README, package archive, or a public repository.

For production deployments, pin dependencies with a lockfile, use a supported Node.js runtime, monitor connection events, handle logout separately from recoverable disconnects, and keep reconnect logic from creating uncontrolled parallel sockets.

Development workflow

Run the package tests with:

npm test

Before submitting changes, validate ESM syntax, CommonJS compatibility where applicable, generated protocol files, and the declarations in lib/index.d.ts. Keep package metadata, exports, runtime requirements, and documentation synchronized. When a protocol behavior is experimental, document the fallback behavior and the client versions used during testing.

Recent compatibility updates

The current source includes the verified album compatibility correction: album child messages use association type 1, the compatible child-association wire value, rather than treating the MEDIA_ALBUM message category as the association value.

The source also preserves the package’s explicit view-once implementations and exposes the opt-in mediaSpoilerMode path for applications that want either a view-once envelope or a native spoiler context flag without changing existing defaults.

About Codex

This package is built and maintained by Codex, also known as Dev Codex. Codex is a developer from Nigeria who focuses on practical, accessible, and reliable software projects across the JavaScript and TypeScript ecosystem.

Codex works with JavaScript, HTML, TypeScript, Node.js, GitHub, Baileys, APIs, key-value stores, and related developer tools. Projects include application development, websites, WhatsApp bots, Telegram bots, API endpoints, and games.

The developer’s work is driven by a commitment to learning, experimentation, clear documentation, and useful software that developers can understand and extend. This package reflects that commitment through its readable source, public declarations, practical examples, and emphasis on responsible automation.

For updates and direct contact, connect with Codex on Telegram at @codexverified. Email: [email protected]

Package layout

The lib/ directory contains the JavaScript implementation, supporting utilities, and public TypeScript declarations. WAProto/ contains generated WhatsApp protocol definitions. engine-requirements.js performs installation-time runtime checks. package.json contains package metadata, scripts, dependencies, and exports. This README.md is the user-facing installation and usage guide.

Security and responsible use

This library interacts with WhatsApp accounts and user communications. Use it only with accounts and data you are authorized to control. Respect WhatsApp’s terms, applicable law, and the privacy expectations of message participants. Avoid unsolicited messaging, protect authentication state, limit access to stored media, and provide clear notice when an application performs automated actions.

Never commit session files, access tokens, private keys, phone numbers, or other personal information to a public repository. Review installation scripts and optional dependencies before deploying to production, and use pinned dependency versions for repeatable builds.

License and maintenance

This distribution is provided under the license declared in package.json and the accompanying license file. Review those terms before redistributing or combining this package with third-party code.

@codexverified/baileys is built and maintained by Codex under the CodexVerified organization. Contributions, bug reports, and carefully documented improvements are welcome through the project repository.