Contact & Device Synchronization

Relevant source files

The following files were used as context for generating this wiki page:

• lib/WAUSync/Protocols/USyncContactProtocol.js
• lib/Socket/socket.js
• lib/Socket/chats.js
• lib/Socket/usync.js
• lib/Socket/messages-send.d.ts
• lib/WABinary/generic-utils.js

Contact & Device Synchronization in the Baileys project is managed through the USync (Universal Sync) protocol framework. This system allows the client to query WhatsApp servers for information regarding user existence, contact status, device lists, and identity mappings (such as LID to PN mappings). It serves as a foundational layer for privacy settings, presence updates, and multi-device session management.

The system utilizes specialized protocol handlers to construct XML-like binary nodes for queries and to parse the resulting server stanzas. By aggregating these protocols, the executeUSyncQuery function facilitates batch requests for multiple users and different data types (e.g., status, contact, lid) in a single round-trip to the server.

Architecture and Query Flow

The USync architecture is designed around the USyncQuery class and specific protocol implementations. Queries are wrapped in an iq (Info/Query) stanza with the usync XML namespace.

USync Query Execution

The core logic for executing these queries resides in the socket implementation. It involves mapping valid users to user nodes and appending protocol-specific XML elements.

Key Components

Component	Description
USyncQuery	Builder class to define users and protocols for a synchronization request.
USyncContactProtocol	Handles queries related to contact existence and mapping (Phone/Username).
executeUSyncQuery	The primary function that assembles and sends the USync iq stanza.
onWhatsApp	A high-level utility to check if specific JIDs exist on WhatsApp.

Protocols and Node Construction

Each synchronization type has a dedicated protocol handler that defines how to request data and how to interpret the server's response.

USyncContactProtocol

This protocol manages requests for contact information. It can identify users via phone numbers or usernames. When querying via username, it supports optional parameters like pin and lid.

getUserElement(user) {
    if (user.phone) {
        return { tag: 'contact', attrs: {}, content: user.phone }
    }
    if (user.username) {
        return {
            tag: 'contact',
            attrs: {
                username: user.username,
                ...(user.usernameKey ? { pin: user.usernameKey } : {}),
                ...(user.lid ? { lid: user.lid } : {})
            }
        }
    }
    // ...
}

Sources: lib/WAUSync/Protocols/USyncContactProtocol.js:15-39

LID and PN Mapping

A critical part of device synchronization involves mapping LID (Linked Identity) to PN (Phone Number). When a USync query returns LID information, the client stores these mappings in a signal repository.

Data Structures and XML Mapping

USync queries are structured as a list of users and a query node containing requested protocols.

User Node Attributes

When constructing the XML content for a synchronization request, users are identified by JID or phone number.

Tag	Attribute	Description
user	jid	The user's JID (used if phone is not provided).
usync	context	The synchronization context (e.g., 'interactive').
usync	mode	Query mode (e.g., 'query' or 'full').
usync	sid	Unique session ID for the message tag.

Sources: lib/Socket/socket.js:93-125, lib/Socket/usync.js:19-54

Identity Verification (LID)

The system distinguishes between standard user JIDs and LID users. For LID users, a specific lid protocol is used within the USync query to fetch identity details.

const lidQuery = new WAUSync_1.USyncQuery().withLIDProtocol()
if (WABinary_1.isLidUser(jid)) {
    lidQuery.withUser(new WAUSync_1.USyncUser().withLid(jid))
}

Sources: lib/Socket/socket.js:145-148, lib/Socket/chats.js:192-212

Error Handling and Validation

USync queries enforce strict validation before transmission. A query must contain at least one protocol handler, and results are checked for error nodes using assertNodeErrorFree.

• Protocol Requirement: executeUSyncQuery throws an error if usyncQuery.protocols.length === 0.
• Node Integrity: The assertNodeErrorFree utility checks the binary response for an error tag and throws a Boom error with the corresponding text and status code if found.

Sources: lib/Socket/socket.js:85-87, lib/WABinary/generic-utils.js:52-57

Summary

Contact and Device Synchronization in Baileys utilizes the USync framework to manage identity discovery and metadata updates. Through a modular protocol system, it efficiently handles phone number checks, LID-PN mappings, and username-based discovery, ensuring that the client maintains an accurate state of available contacts and their associated devices.