USync (User Sync) Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The USync (User Sync) architecture is a centralized mechanism within Baileys designed to synchronize user-related metadata and capabilities from WhatsApp servers. It utilizes a modular "protocol" system to query diverse information types, including contact availability, device lists, bot profiles, status updates, and disappearing message settings.
The system operates by constructing a unified iq (Information Query) stanza containing a list of target users and the specific protocols required for the query. This architecture ensures efficient data retrieval by batching multiple metadata requests into a single network round-trip.
Sources: lib/Socket/socket.js:101-155, lib/WAUSync/USyncQuery.js:7-66
Core Components
USyncQuery Class
The USyncQuery class serves as the builder for constructing synchronization requests. It manages a collection of protocols and a list of target users, and provides methods to configure the query context and mode.
- Protocols: A list of
USyncQueryProtocolimplementations (e.g., Contact, Device, Status). - Users: A list of
USyncUserobjects containing identifiers like JIDs or phone numbers. - Context: Typically set to 'interactive'.
- Mode: Typically set to 'query'.
Sources: lib/WAUSync/USyncQuery.js:7-17, lib/Types/USync.d.ts:7-24
USync Protocols
Protocols define how specific metadata is requested and parsed. Each protocol must implement the USyncQueryProtocol interface, providing logic for generating XML elements for the query and for individual users, as well as a parser for the server's response.
| Protocol Name | Purpose | Data Parsed |
|---|---|---|
devices | Syncs companion device lists and key indices. | Device IDs, hosted status, key-index timestamps. |
status | Syncs user status text and timestamps. | Status string, set-at date. |
bot | Syncs AI bot profiles and capabilities. | Name, description, commands, prompts. |
username | Syncs WhatsApp usernames. | Utf-8 username string. |
contact | Checks if a user exists on WhatsApp. | Existence flag, JID mapping. |
disappearing_mode | Syncs disappearing message durations. | Duration value. |
Sources: lib/WAUSync/Protocols/USyncDeviceProtocol.js:7-50, lib/WAUSync/Protocols/USyncStatusProtocol.js:7-41, lib/WAUSync/Protocols/USyncBotProfileProtocol.js:7-63, lib/WAUSync/USyncQuery.js:67-97
Data Flow and Query Execution
The execution of a USync query involves transforming a USyncQuery object into a WABinary node structure and processing the resulting server response.
Query Construction Flow
- User Nodes: Each user in the query is mapped to a
<user>tag, populated with protocol-specific elements viagetUserElement(). - List Node: A
<list>tag wraps all user nodes. - Query Node: A
<query>tag contains global protocol requirements viagetQueryElement(). - IQ Stanza: An
<iq>node withxmlns="usync"wraps the<usync>node, which contains the list and query structures.
A visual representation of the USync request lifecycle from object construction to result parsing.
Sources: lib/Socket/socket.js:101-155, lib/WAUSync/USyncQuery.js:25-66
Server Communication Sequence
The executeUSyncQuery function handles the transmission and response handling.
The interaction between the socket handler, query builder, and remote server.
Sources: lib/Socket/socket.js:101-155, lib/Socket/usync.js:10-72
Protocol Implementation Details
Device Synchronization
The USyncDeviceProtocol retrieves device lists for Multi-Device support. It handles versioned queries (version 2) and parses both the device list and the key-index-list used for encryption synchronization.
- Device Attributes:
id,key-index, andis_hosted. - Key Index Attributes:
ts(timestamp),expected_ts, and the raw content (signed key index).
Sources: lib/WAUSync/Protocols/USyncDeviceProtocol.js:12-50
Bot Profile Synchronization
The USyncBotProfileProtocol handles metadata for AI entities. It parses complex structures including command lists and prompt suggestions.
- Commands: Extracted from the
<commands>node, includingnameanddescription. - Prompts: Extracted from
<prompts>as combined emoji and text strings. - Profile Metadata: Includes
persona_id,category, andattributes.
Sources: lib/WAUSync/Protocols/USyncBotProfileProtocol.js:24-63
Summary
The USync architecture provides a scalable and type-safe method for Baileys to interact with user metadata on WhatsApp. By decoupling the XML generation and parsing logic into discrete protocols, the system allows for easy extension as new WhatsApp features (like AI Bots or Usernames) are introduced, while maintaining a consistent batching mechanism for performance.
Sources: lib/WAUSync/USyncQuery.js:7-66, lib/Socket/usync.js:10-76