Baileys 7 Breaking Changes: A Complete Migration Guide for WhatsApp Bot Developers

Baileys 7 introduced package renaming, new auth state handling with useMultiFileAuthState, explicit message key-based read receipts, and event system restructuring that requires code changes to migrate from earlier versions.

Baileys—the popular open-source WhatsApp Web API library maintained by WhiskeySockets—released version 7 as a major breaking update. The project's README.md explicitly warns developers about these changes and provides migration guidance for projects built on pre-7 versions. This guide distills every critical API change with actionable migration code.

Package Name Migration: From baileys to @whiskeysockets/baileys

The most immediate breaking change is the scoped package name. The old baileys package on npm has been deprecated in favor of @whiskeysockets/baileys.

Update your dependency installation:

yarn add @whiskeysockets/baileys

Then replace all import statements throughout your codebase:

// Old (deprecated)
import makeWASocket from 'baileys'

// New (Baileys 7)
import makeWASocket from '@whiskeysockets/baileys'

According to the README.md, the new import structure is demonstrated in the "Getting Started" section where all examples now use the scoped package name.

Auth State Handling: useMultiFileAuthState Returns { state, saveCreds }

The authentication system was completely restructured. The authInfo object is no longer accepted by makeWASocket. Instead, Baileys 7 requires you to use the useMultiFileAuthState helper, which returns a state object and a save handler separately.

Migration Pattern

import { useMultiFileAuthState } from '@whiskeysockets/baileys'

// Extract state and save handler
const { state, saveCreds } = await useMultiFileAuthState('auth_info')

// Pass only state to makeWASocket
const sock = makeWASocket({ auth: state })

// Persist credential updates
sock.ev.on('creds.update', saveCreds)

The src/Utils/auth-utils.ts file contains the implementation details for this new workflow. The critical distinction: makeWASocket receives auth: state, not the full auth response.

Message Read Receipts: Explicit Keys Required

Generic "mark all as read" functionality was removed. You must now call readMessages with explicit message key arrays.

import { WAMessageKey } from '@whiskeysockets/baileys'

const key: WAMessageKey = /* extract from WAMessage */
await sock.readMessages([key])

The src/Utils/messages.ts file defines this readMessages helper. Any code that previously relied on automatic read marking must be refactored to track and pass specific message keys.

Event System: messages.upsert Replaces messages.update for New Messages

The messages.update event now delivers only delta updates—such as poll votes or status changes. To receive full new incoming messages, migrate your listeners to messages.upsert.

// Old pattern (no longer receives new messages)
sock.ev.on('messages.update', ({ messages }) => {
  // Only handles updates, not new messages
})

// New pattern (Baileys 7)
sock.ev.on('messages.upsert', ({ messages }) => {
  // Handle all new incoming messages here
})

This change affects src/Utils/event-buffer.ts where the BaileysEventMap type definitions reflect the new event structure.

Ephemeral Messages: New Helper Constants

The ephemeralExpiration option remains functional but now works with explicit helper constants for clarity.

import { WA_DEFAULT_EPHEMERAL } from '@whiskeysockets/baileys'

await sock.sendMessage(jid, { text: 'hello' }, { 
  ephemeralExpiration: WA_DEFAULT_EPHEMERAL 
})

The disappearingMessagesInChat method provides additional control for managing ephemeral settings at the chat level.

Link Preview Generation: Optional link-preview-js Package

Link previews are no longer built-in. Media-preview generation now lives in the optional link-preview-js package.

After installing the peer dependency:

yarn add link-preview-js

Send link previews as regular text messages—the library handles preview generation automatically:

await sock.sendMessage(jid, { text: 'Check https://github.com/WhiskeySockets/Baileys' })

The README's "Sending Messages with Link Previews" section documents this shift to optional dependencies.

Group Metadata Caching: Required cachedGroupMetadata Option

Performance-minded group handling now requires an explicit cache implementation. The cachedGroupMetadata option must be provided to makeWASocket.

import NodeCache from 'node-cache'

const groupCache = new NodeCache({ stdTTL: 5 * 60 }) // 5 minute TTL

const sock = makeWASocket({ 
  cachedGroupMetadata: async jid => groupCache.get(jid)
})

Without this cache, group operations may trigger excessive network requests. The src/index.ts exports show this as a configurable socket option.

Media Handling: Prefer Streaming Over Buffers

Baileys 7 optimizes memory usage by preferring streaming media uploads. Where you previously loaded entire buffers, migrate to URL or stream-based approaches.

// Preferred: Direct file path (streaming)
await sock.sendMessage(jid, { 
  image: { url: './Media/example.png' },
  caption: 'via streaming'
})

// Alternative: URL-based (no local download)
await sock.sendMessage(jid, { 
  video: { url: 'https://example.com/video.mp4' }
})

The "Media Messages" section in the README demonstrates these patterns with { url: '...' } syntax rather than buffer loading.

Presence Updates: WAPresence String Literals

Presence must now use explicit string values from the WAPresence type.

// Valid presence values: 'available', 'unavailable', 'composing', 'recording', 'paused'
await sock.sendPresenceUpdate('available', jid)
await sock.sendPresenceUpdate('composing', jid) // "typing..."

Hard-coded presence strings should be cross-referenced against the WAPresence type definition to ensure compatibility.

TypeScript Event Typing: BaileysEventMap

All events are now consolidated under BaileysEventMap for type safety. Custom event listeners should reference this type:

import { BaileysEventMap } from '@whiskeysockets/baileys'

// Type-safe event handler
sock.ev.on('messages.upsert', (data: BaileysEventMap['messages.upsert']) => {
  // Full IntelliSense support
})

The event-map alias link in src/Utils/event-buffer.ts provides the authoritative type definitions.

Complete Migration Checklist

Follow this sequence for a successful Baileys 7 upgrade:

1. Update dependency — yarn add @whiskeysockets/baileys
2. Replace all imports — change require('baileys') to @whiskeysockets/baileys
3. Migrate auth handling — switch to useMultiFileAuthState with { state, saveCreds } pattern
4. Refactor read receipts — replace generic "mark all as read" with explicit readMessages([key])
5. Update message listeners — move from messages.update to messages.upsert for new messages
6. Add link-preview-js — install if your project uses URL previews
7. Implement group cache — add cachedGroupMetadata with node-cache or equivalent
8. Review media sends — convert buffer-based uploads to streaming { url: ... } or { stream: ... }
9. Fix presence calls — use WAPresence string literals
10. Type-check with compiler — run yarn tsc or yarn lint to catch remaining API mismatches

Key Source Files for Reference

File	Purpose
src/index.ts	Public API exports including makeWASocket, useMultiFileAuthState
src/Utils/auth-utils.ts	New authentication state workflow implementation
src/Utils/messages.ts	readMessages and message handling helpers
src/Utils/event-buffer.ts	BaileysEventMap type definitions
README.md	Central documentation with breaking change notices

Summary

• Package renamed to @whiskeysockets/baileys — update all imports
• Auth state handling requires destructured { state, saveCreds } from useMultiFileAuthState
• Message read receipts need explicit WAMessageKey arrays via readMessages
• Event system splits functionality: messages.upsert for new messages, messages.update for deltas only
• Group operations require cachedGroupMetadata implementation for performance
• Media uploads prefer streaming via { url: ... } over buffer loading
• Optional dependencies like link-preview-js now handle extended features

Frequently Asked Questions

What happens if I don't migrate to the new auth state pattern?

Your application will fail at runtime. makeWASocket in Baileys 7 strictly validates the auth option and rejects the old authInfo object structure. The TypeScript compiler will also flag type errors if you attempt to pass the deprecated format.

Can I still use buffer-based media uploads in Baileys 7?

Yes, but it's discouraged. The streaming approach via { url: ... } or { stream: ... } is optimized for memory efficiency and is the documented pattern in the README's "Media Messages" section. Buffer uploads remain functional for backward compatibility but may be deprecated in future versions.

How do I handle "mark all as read" functionality now that it's removed?

You must track incoming message keys and call readMessages explicitly. A common pattern: store WAMessageKey objects from messages.upsert events in a queue, then batch-process them through readMessages([key1, key2, ...]) when your read logic triggers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}