[BUG] 'lid-mapping.update' event never fires

[royalh23]

Describe the bug
I'm trying to respond to specific people (an array called TARGET_PEOPLE) in a group with my bot. Basically, I have their PNs in 123456...@s.whatsapp.net format, but since WhatsApp only returns each user's LID, I need to get each user's PN using their LID so that I can compare each PN to my array. In order not to always depend on the 'lid-mapping.update' event, I created a lidMapper method for my database, which basically:

1. Gets a user's PN using their LID after a messages.upsert event, so that my bot doesn't query the WhatsApp servers;
2. In case the database is empty, after the lid-mapping.update event fires, it saves the user's LID and PN in the database for future queries.

The problem is, lid-mapping.update never fires and I can't figure out how I can manually force the WP servers to fire this event either. I tried asking the Discord bot (since the docs aren't even complete/barely understandable), and it suggested using the onWhatsApp method, but it never returns the LID of a user, so I don't know what to do.

To Reproduce
Steps to reproduce the behavior:

1. Create a new connection
2. Listen for the lid-mapping.update event
3. Inside the callback of this function, iterate through update.mapping and save each LID with the PN

Expected behavior
I am expecting this event to fire and thus save all LID -> PN mappings to my database, but it never happens.

Environment (please complete the following information):

• Is this on a server?
• No, I am running the code locally
• What do your connectOptions look like?
• N/A
• Do you have multiple clients on the same IP?
• N/A
• Are you using a proxy?
• No

Additional context
Baileys version: "@whiskeysockets/baileys": "^7.0.0-rc.9"

[jlucaso1]

I think will be fixed by: #2266

[Jeferson-Ramos-Einov]

@jlucaso1 This resolves cases where the chat receives the remoteJid as "@lid" within the event: messages-history.set?

[Jeferson-Ramos-Einov]

@jlucaso1 Example of what I receive: { "participant": [], "id": "152230971891797@lid", "unreadCount": 0, "readOnly": false, "ephemeralExpiration": 0, "ephemeralSettingTimestamp": { "low": 0, "high": 0, "unsigned": false }, "conversationTimestamp": { "low": 1768823999, "high": 0, "unsigned": true }, "notSpam": true, "archived": false, "disappearingMode": { "initiator": "CHANGED_IN_CHAT" }, "unreadMentionCount": 0, "markedAsUnread": false, "tcToken": { "type": "Buffer", "data": [ 4, 1, 31, 32, 174, 66, 199, 159, 52, 207, 46 ] }, "tcTokenTimestamp": { "low": 1768823559, "high": 0, "unsigned": true }, "contactPrimaryIdentityKey": { "type": "Buffer", "data": [ 26, 160, 122, 24, 183, 60, 194, 26, 241, 239, 54, 79, 173, 56, 143, 100, 49, 192, 36, 110, 218, 191, 33, 7, 31, 192, 19, 3, 237, 140, 185, 25 ] }, "tcTokenSenderTimestamp": { "low": 1768822350, "high": 0, "unsigned": true }, "pnJid": "554199088675@s.whatsapp.net", "shareOwnPn": true, "lidOriginType": "general", "commentsCount": 1000000, "locked": false, "accountLid": "152230971891797@lid", "messages": [ { "message": { "key": { "remoteJid": "152230971891797@lid", "fromMe": true, "id": "A505FDBD904CBA1E0AA75BA1C48DAD3D" }, "message": { "conversation": "Bora malhar?", "messageContextInfo": { "messageSecret": "5gtmCZDnCvZtfqJaMLQ3U8iHCJ0rXIpVpI+/qmNlQQc=" } }, "messageTimestamp": "1768823999", "status": "READ", "messageC2STimestamp": "1768824000", "userReceipt": [ { "userJid": "152230971891797@lid", "receiptTimestamp": "1768824001", "readTimestamp": "1768824057", "playedTimestamp": "0" } ], "messageSecret": "5gtmCZDnCvZtfqJaMLQ3U8iHCJ0rXIpVpI+/qmNlQQc=", "originalSelfAuthorUserJidString": "554892185611@s.whatsapp.net", "isMentionedInStatus": false } } ] }

[jlucaso1]

@Jeferson-Ramos-Einov this is another bug, check #2282

[alessandropcostabr]

We hit the same problem in production and solved it by not relying on lid-mapping.update at all. There are three alternative sources for LID-to-phone mappings that are already available in the Baileys message flow:

1. key.senderPn on incoming messages

Recent Baileys versions include senderPn (phone number as @s.whatsapp.net) on incoming message keys. This is the most reliable source:

// On every incoming message:
if (msg.key.senderPn) {
  const lid = msg.key.participant || msg.key.remoteJid;
  if (lid?.endsWith('@lid')) {
    lidMap.set(lid, msg.key.senderPn);
  }
}

2. Send response key.remoteJid

After calling sendMessage(), the returned key always contains the phone-based JID, so you can map any LID you had stored for that contact.

3. sock.signalRepository.lidMapping

Available as a runtime fallback for contacts encountered during the current session.

We maintain a local Map<lid, phone> populated from all three sources. It fills up naturally from normal message flow — within hours of operation, virtually all active contacts are mapped. We persist this map to the database so it survives restarts.

This approach is more robust than waiting for an event that may never fire depending on the WhatsApp account state or Baileys version. Tested and confirmed working in production.

[alessandropcostabr]

✅ CONFIRMED — This is a Ghost Event

We investigated this and confirmed that lid-mapping.update is declared in BaileysEventMap but NEVER emitted by the library.

Root Cause

The event is processed internally in process-message.js:

signalRepository.lidMapping.storeLIDPNMappings() → no event emitted

LID mapping is now handled entirely by Baileys internally (Signal/lid-mapping.js), not exposed as an event.

What You Should Do Instead

Monitor these instead:

1. store.contacts — populated by contacts.upsert + contacts.update
2. lid-mapping-*.json files in the auth directory — persistent mapping storage
3. Manually warm up LID map on connection from auth files (see [DISCUSSION] LID Mapping Best Practices & Debugging Guide for Production #2414)

Proposed Fix

Mark this event as @deprecated in Events.d.ts so developers stop wasting time:

See our issue #2416 for full proposal.

Related

• [DISCUSSION] LID Mapping Best Practices & Debugging Guide for Production #2414 — LID Mapping Best Practices (what to do instead)
• [BUG/ENHANCEMENT] Mark deprecated/ghost events in BaileysEventMap #2416 — Proposal to mark deprecated events
• [RESOURCE] Production Debugging Guide: Discovering & Monitoring Baileys Events #2417 — Full production debugging guide

We've implemented a workaround that works 100% in production with 6 accounts.