Skip to main content

Documentation Index

Fetch the complete documentation index at: https://whiskeysockets-docs-jids-socket-config-ptbr.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Baileys 7.x introduces several breaking changes you must address when upgrading from 6.x. This guide walks through each one in the order most projects encounter them.

​
LIDs (Linked Identity JIDs)

WhatsApp finalized its LID rollout in 2024. A LIDJID (Linked Identity Jabber Identifier) is a per-user identifier on the @lid server that anonymizes phone numbers in large groups, in contrast to the legacy PNJID (Phone Number Jabber Identifier) on @s.whatsapp.net. By default, all new Signal sessions in Baileys 7.x are created in the LID format, and existing sessions are migrated automatically. See WhatsApp JIDs explained for the full PN/LID model.
The LID system requires your auth state to support the lid-mapping, device-list, and tctoken keys. Check your SignalDataTypeMap and update your custom auth implementation before upgrading.
Key things to know:
  • A LID is a JID. It is unique per user, not per group. You can message anyone using either their LID or their PN (phone number JID, user@s.whatsapp.net).
  • You can resolve PN → LID, but not the reverse, using onWhatsApp() or the USyncProtocol. Internally, Baileys exposes a mapping store on sock.signalRepository.lidMapping with storeLIDPNMapping, storeLIDPNMappings, getLIDForPN, getLIDsForPNs, and getPNForLID.
  • onWhatsApp no longer returns LIDs. Use getLIDForPN / getLIDsForPNs instead.
  • isJidUser was removed in favor of isPnUser. Both PNs and LIDs are JIDs, so the old name was misleading.

​
MessageKey changes

6.8.0 added two fields to MessageKey:
  • remoteJidAlt — the alternate JID for direct messages
  • participantAlt — the alternate JID for groups, broadcasts, and channels
If participant is a LID, participantAlt is the matching PN, and vice versa.

​
GroupMetadata changes

In GroupMetadata, every ID-bearing field now has a paired PN field:
  • owner is a LID; ownerPn holds the matching phone-number JID.
  • descOwner / descOwnerPn, and so on.

​
Contact changes

The Contact type no longer has separate jid and lid fields. Instead:
  • id is the preferred identifier (whichever WhatsApp returns).
  • phoneNumber is populated when id is a LID.
  • lid is populated when id is a PN.
These changes also affect participants on GroupMetadata.

​
Phone number sharing

Businesses have used LIDs since 2023 (#408). To exchange phone numbers when needed:
  • Businesses can request a number with { requestPhoneNumber: true } on a sent message.
  • Users can share their number with { sharePhoneNumber: true }.

​
New event

A new lid-mapping.update event fires when a fresh PN ↔ LID mapping is discovered. Note: this is not always emitted yet.

​
New enum

WAMessageAddressingMode represents the preferred ID type for a chat or group.
Don’t try to “restore” PN JIDs. Migrate your application logic to LIDs — PNs are less reliable going forward.

​
ACKs no longer sent

Baileys 7.x stops sending acknowledgments on successful message delivery. WhatsApp has been banning accounts that send these — leaving them off is now the safe default.

​
Meta Coexistence

Meta added Coexistence support, which lets users keep WhatsApp Business plus its linked devices while connected to the Meta API. Baileys 7.x can send, receive, and pair with accounts that have Coexistence enabled. This support is somewhat experimental — please report issues on GitHub.

​
ESM only

Baileys 7.x is ESM-only. Multiple upstream packages have moved to ESM, and supporting CommonJS required workarounds (like makeWASocket.default) and held back our linting toolchain. You have two options for upgrading: Set "type": "module" in your package.json and replace require() with import. If you must keep some CommonJS files, use createRequire() inside ESM.

​
Option 2 — Dynamically import Baileys from CommonJS

If you can’t migrate yet, load Baileys with await import(): 
// cjs_module.js
const fs = require('fs')

async function loadESMModule() {
  try {
    const { default: makeWASocket } = await import('@whiskeysockets/baileys')
    const socket = makeWASocket({ /* ... */ })
  } catch (error) {
    console.error('Error loading ESM module:', error)
  }
}

loadESMModule()
The project has also moved from Yarn Classic to Yarn v4. Baileys now requires corepack for development.

​
Slimmer protobufs

To reduce bundle size, Baileys 7.x removed most proto helpers. The only ones that remain are:
  • .create() — use this in place of .fromObject().
  • .encode() and .decode().
When (de)serializing protos, use the BufferJSON utilities — JSON.stringify / JSON.parse alone will corrupt buffer fields. A new decodeAndHydrate() method handles a long-standing pbjs decoding quirk; prefer it over plain decode().

​
Reference

For the complete changelog, see the GitHub releases page. The canonical short link for this guide is whiskey.so/migrate-latest.