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

> Migrate your WhatsApp bot with Baileys 7 breaking changes. Learn about package renaming, new auth state handling, read receipts, and event system updates. Get your code updated easily.

- Repository: [WhiskeySockets/Baileys](https://github.com/WhiskeySockets/Baileys)
- Tags: migration-guide
- Published: 2026-08-01

---

**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`](https://github.com/WhiskeySockets/Baileys/blob/main/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:

```bash
yarn add @whiskeysockets/baileys

```

Then replace all import statements throughout your codebase:

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

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

```

According to the [`README.md`](https://github.com/WhiskeySockets/Baileys/blob/main/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

```typescript
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`](https://github.com/WhiskeySockets/Baileys/blob/main/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.

```typescript
import { WAMessageKey } from '@whiskeysockets/baileys'

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

```

The [`src/Utils/messages.ts`](https://github.com/WhiskeySockets/Baileys/blob/main/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`.

```typescript
// 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`](https://github.com/WhiskeySockets/Baileys/blob/main/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.

```typescript
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:

```bash
yarn add link-preview-js

```

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

```typescript
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`.

```typescript
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`](https://github.com/WhiskeySockets/Baileys/blob/main/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.

```typescript
// 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.

```typescript
// 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:

```typescript
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`](https://github.com/WhiskeySockets/Baileys/blob/main/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`](https://github.com/WhiskeySockets/Baileys/blob/main/src/index.ts) | Public API exports including `makeWASocket`, `useMultiFileAuthState` |
| [`src/Utils/auth-utils.ts`](https://github.com/WhiskeySockets/Baileys/blob/main/src/Utils/auth-utils.ts) | New authentication state workflow implementation |
| [`src/Utils/messages.ts`](https://github.com/WhiskeySockets/Baileys/blob/main/src/Utils/messages.ts) | `readMessages` and message handling helpers |
| [`src/Utils/event-buffer.ts`](https://github.com/WhiskeySockets/Baileys/blob/main/src/Utils/event-buffer.ts) | `BaileysEventMap` type definitions |
| [`README.md`](https://github.com/WhiskeySockets/Baileys/blob/main/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.