Skip to main content

LID Migration & Safety

WhatsApp has migrated account identifiers from JIDs (s.whatsapp.net phone numbers) to LIDs (lid WhatsApp internal IDs).

To ensure compatibility during this transition and avoid encryption/session loops, UDMODZ Edition implements a comprehensive LID safety mechanism.

Configuration Options​

These configurations are enabled by default in UDMODZ Edition:

const sock = makeWASocket({
  auth: state,
  // Automatically intercept ACKs with refresh_lid=true,
  // migrating underlying Signal sessions to the new identity
  enableLidMigrationSafety: true, 

  // Force-refresh phone number to LID mappings via USync 
  // when a migration notice is detected
  refreshMappingOnLidMigration: true 
})

How It Works​

  1. Safety Interception: When WhatsApp responds to a message ACK with refresh_lid="true", the library intercepts the attributes.
  2. Lookup & Cache Bypass: A forced USync lookup is scheduled, bypassing the normal LRU cache to verify the target JID's fresh LID.
  3. Session Migration: The library calls signalRepository.migrateSession(pn, newLid) to move stored pre-keys and cryptographic session states.
  4. Event Notification: The library triggers the 'lid-migration.update' event.

Listening to Migration Events​

You can listen to 'lid-migration.update' to update JID structures in your databases/filesystems:

sock.ev.on('lid-migration.update', (migration) => {
  console.log(`LID Migration detected for old JID: ${migration.oldLid}`)
  console.log(`New JID (LID): ${migration.newLid}`)
  console.log(`Associated Phone Number: ${migration.pn}`)
  console.log(`Triggered by message ID: ${migration.messageId}`)
  
  // Example: update contact references in your database
  if (migration.newLid) {
    updateContactLidInDatabase(migration.oldLid, migration.newLid)
  }
})

Event Payload Schema​

export type LIDMigrationUpdate = {
  oldLid: string        // Stale LID or PN JID
  newLid?: string       // Newly resolved LID JID
  pn?: string           // Phone number JID
  messageId?: string    // ID of the message that triggered the refresh
  reason: 'ack-refresh-lid'
}