Baileys Redis Authentication State Handler

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax with `baileys-redis-auth` which is an ESM-only package since v2.0.0.
  fix Change your import statements to ES module syntax (e.g., `import { useRedisAuthStateWithHSet } from 'baileys-redis-auth'`) and ensure your `package.json` contains `"type": "module"`.

• Error: Cannot find package 'baileys' or its corresponding type declarations.

  cause The `baileys` package is a peer dependency but has not been installed in your project.
  fix Install Baileys using your package manager: `npm install baileys` or `yarn add baileys`.

• Error: connect ECONNREFUSED <ip_address>:<port>

  cause The application failed to connect to the Redis server, likely because the server is not running, is inaccessible, or the connection details are incorrect.
  fix Verify that your Redis server is active and reachable. Check the `host`, `port`, and `password` provided in your `redisOptions` object.

• TypeError: (0 , baileys_redis_auth__WEBPACK_IMPORTED_MODULE_0__.useRedisAuthStateWithHSet) is not a function

  cause This often occurs in bundler environments (like Webpack or Vite) when mixing CommonJS and ESM or due to incorrect build configurations for ESM modules.
  fix Ensure your bundler is correctly configured to handle ES Modules. Verify `"type": "module"` in `package.json` and check your bundler's resolution/transpilation settings for `node_modules`.

Warnings

• breaking Version 2.0.0 and above are ESM-only modules. CommonJS (require()) syntax is no longer supported and will lead to runtime errors.
  Fix: Ensure your project is configured for ES modules (e.g., add `"type": "module"` to your `package.json`) and use `import` statements for all package imports.
• breaking Baileys is now a peer dependency. It must be explicitly installed in your project alongside `baileys-redis-auth`.
  Fix: Run `npm install baileys-redis-auth baileys` or `yarn add baileys-redis-auth baileys` to ensure both packages are installed.
• breaking The official Baileys package name changed from `@whiskeysockets/baileys` to `baileys` with its v7 release. This library aligns with the new package name.
  Fix: Update all your Baileys import statements from `import { ... } from '@whiskeysockets/baileys'` to `import { ... } from 'baileys'`.
• gotcha A running Redis server instance is a prerequisite. The library will fail to connect if Redis is not available or if connection details are incorrect.
  Fix: Ensure your Redis server is running and accessible from your application's environment. Verify `host`, `port`, and `password` in your `redisOptions`.

Install

• npm install baileys-redis-auth npm
• yarn add baileys-redis-auth yarn
• pnpm add baileys-redis-auth pnpm

Imports

• useRedisAuthStateWithHSet
  wrong:

  const { useRedisAuthStateWithHSet } = require('baileys-redis-auth')

  correct:

  import { useRedisAuthStateWithHSet } from 'baileys-redis-auth'

  The library is ESM-only since v2.0.0; CommonJS require() is not supported.
• deleteHSetKeys
  wrong:

  const { deleteHSetKeys } = require('baileys-redis-auth')

  correct:

  import { deleteHSetKeys } from 'baileys-redis-auth'

  Used for programmatic deletion of specific session data from Redis. Requires ESM import.

Quickstart

This quickstart demonstrates how to initialize Baileys with Redis authentication state using `useRedisAuthStateWithHSet`, set up basic connection event handling, and persist credentials.

import { useRedisAuthStateWithHSet } from 'baileys-redis-auth'
import { RedisOptions } from 'ioredis'
import makeWASocket, { DisconnectReason } from 'baileys'
import { Boom } from '@hapi/boom'

// Define your Redis connection options
const redisOptions: RedisOptions = {
  host: 'localhost',
  port: 6379
  // password: process.env.REDIS_PASSWORD ?? '', // Uncomment if your Redis has a password
}

// Define a unique session identifier for this Baileys session
const sessionId = 'my_baileys_session_example'

async function initializeBaileysWithHSet() {
  const { state, saveCreds, redis: authRedisInstance } = await useRedisAuthStateWithHSet(
    redisOptions,
    sessionId,
    console.log // Optional: pass logger for Redis connection events
  )

  authRedisInstance.on('connect', () =>
    console.log(`Redis (from hook) connected for session: ${sessionId}`)
  )
  authRedisInstance.on('error', (err) =>
    console.error(`Redis (from hook) error for session ${sessionId}:`, err)
  )

  const sock = makeWASocket({
    auth: state,
    printQRInTerminal: true
  })

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

  sock.ev.on('connection.update', (update) => {
    const { connection, lastDisconnect } = update
    if (connection === 'close') {
      const shouldReconnect = (lastDisconnect?.error as Boom)?.output?.statusCode !== DisconnectReason.loggedOut
      console.log('connection closed due to ', lastDisconnect?.error, ', reconnecting ', shouldReconnect)
      // reconnect if not logged out
      if (shouldReconnect) {
        initializeBaileysWithHSet()
      }
    } else if (connection === 'open') {
      console.log('opened connection')
    }
  })

  // You can now use 'sock' for Baileys operations
  console.log('Baileys initialized with Redis HSet state for session:', sessionId)
}

initializeBaileysWithHSet().catch(err => console.error('Failed to initialize Baileys:', err))