Relevant source files

The following files were used as context for generating this wiki page: - [lib/Socket/usync.js](https://github.com/innovatorssoft/Baileys/blob/main/lib/Socket/usync.js) - [lib/WAUSync/USyncQuery.js](https://github.com/innovatorssoft/Baileys/blob/main/lib/WAUSync/USyncQuery.js) - [lib/Socket/socket.js](https://github.com/innovatorssoft/Baileys/blob/main/lib/Socket/socket.js) - [lib/WAUSync/Protocols/USyncContactProtocol.js](https://github.com/innovatorssoft/Baileys/blob/main/lib/WAUSync/Protocols/USyncContactProtocol.js) - [lib/WAUSync/Protocols/USyncDeviceProtocol.js](https://github.com/innovatorssoft/Baileys/blob/main/lib/WAUSync/Protocols/USyncDeviceProtocol.js) - [lib/WAUSync/Protocols/USyncStatusProtocol.js](https://github.com/innovatorssoft/Baileys/blob/main/lib/WAUSync/Protocols/USyncStatusProtocol.js) - [lib/WAUSync/Protocols/USyncBotProfileProtocol.js](https://github.com/innovatorssoft/Baileys/blob/main/lib/WAUSync/Protocols/USyncBotProfileProtocol.js) - [lib/Types/USync.d.ts](https://github.com/innovatorssoft/Baileys/blob/main/lib/Types/USync.d.ts)

# User Sync (USync) Protocol The User Sync (USync) Protocol is a specialized synchronization mechanism used within the Baileys library to fetch and update metadata related to WhatsApp users. It operates by sending structured Information Query (IQ) stanzas to the WhatsApp server, allowing the client to retrieve specific attributes such as contact status, device lists, profile information, and bot metadata. The protocol is designed to be extensible, utilizing a "protocol-based" architecture where different types of user data are handled by dedicated protocol classes. This allows for concurrent querying of multiple data types (e.g., fetching both device lists and statuses in a single request) while maintaining a clean separation of parsing logic for each data category. Sources: [lib/Socket/usync.js:10-15](), [lib/WAUSync/USyncQuery.js:8-12]() ## Architecture and Core Components The USync system is built around three primary components: the `USyncQuery` builder, various `Protocol` implementations, and the `executeUSyncQuery` execution logic. ### USyncQuery Class The `USyncQuery` class serves as a builder to construct the parameters of a synchronization request. It manages the list of users to be queried, the synchronization mode, and the specific protocols to be utilized. | Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | `protocols` | Array | `[]` | List of protocol handlers to include in the query. | | `users` | Array | `[]` | List of users (JIDs or phone numbers) to sync. | | `context` | String | `'interactive'` | The execution context (e.g., interactive). | | `mode` | String | `'query'` | The sync mode (e.g., query). | Sources: [lib/WAUSync/USyncQuery.js:8-13](), [lib/Types/USync.d.ts:7-27]() ### Protocol Handlers Each protocol handler implements the `USyncQueryProtocol` interface, defining how to generate query elements and how to parse the resulting server data. * **USyncContactProtocol**: Synchronizes contact information and verifies if a user is "in" the contact list. * **USyncDeviceProtocol**: Retrieves the list of devices associated with a user, including their hardware IDs and key indices. * **USyncStatusProtocol**: Fetches the text status and the timestamp of when it was set. * **USyncBotProfileProtocol**: Retrieves metadata for AI bots, including names, descriptions, commands, and prompts. Sources: [lib/WAUSync/Protocols/USyncContactProtocol.js:7-10](), [lib/WAUSync/Protocols/USyncDeviceProtocol.js:7-10](), [lib/WAUSync/Protocols/USyncStatusProtocol.js:7-10](), [lib/WAUSync/Protocols/USyncBotProfileProtocol.js:7-10]() ## Data Flow and Execution The execution of a USync query involves transforming the `USyncQuery` object into a `WABinary` node, sending it via the socket, and then distributing the response parts back to the respective protocols for parsing. ### Query Construction Flow The diagram below illustrates how the system aggregates multiple protocols into a single binary request. ```mermaid graph TD A[USyncQuery Builder] --> B{Add Protocols} B --> C[Device Protocol] B --> D[Status Protocol] B --> E[Contact Protocol] A --> F[Add Users] C & D & E & F --> G[executeUSyncQuery] G --> H[Generate IQ Stanza] H --> I[Send via WebSocket] ``` The `executeUSyncQuery` function iterates through all added protocols to generate the `` section and iterates through users to generate the `` section of the USync node. Sources: [lib/Socket/usync.js:15-60](), [lib/Socket/socket.js:115-140]() ### Response Processing When the server returns an IQ result, the protocol uses a mapping strategy to decode the data: 1. The result node is verified to ensure it is of type `result`. 2. The `` and `` child nodes are extracted. 3. Each `` node in the list is processed. 4. For every protocol tag found inside a user node, the corresponding protocol's `parser` function is invoked. Sources: [lib/WAUSync/USyncQuery.js:24-55](), [lib/Socket/usync.js:62-65]() ## Implementation Details ### IQ Stanza Structure The USync protocol uses a specific XML-like structure for its binary nodes. A typical query is wrapped in an `iq` stanza with the `usync` namespace. ```javascript const iq = { tag: 'iq', attrs: { to: S_WHATSAPP_NET, type: 'get', xmlns: 'usync', }, content: [ { tag: 'usync', attrs: { context: usyncQuery.context, mode: usyncQuery.mode, sid: generateMessageTag(), last: 'true', index: '0', }, content: [queryNode, listNode] } ], } ``` Sources: [lib/Socket/usync.js:37-60](), [lib/Socket/socket.js:142-168]() ### Bot Profile Metadata The `USyncBotProfileProtocol` handles complex metadata structures for WhatsApp bots, extracting specific interactive elements. | Field | Source Attribute/Node | Description | | :--- | :--- | :--- | | `personaId` | `persona_id` attribute | Unique identifier for the bot's persona. | | `commands` | `command` nodes | List of available bot commands with names and descriptions. | | `prompts` | `prompt` nodes | Suggested interaction prompts (emoji + text). | | `isDefault` | `default` node | Boolean indicating if this is the default bot profile. | Sources: [lib/WAUSync/Protocols/USyncBotProfileProtocol.js:23-55]() ## Sequence Diagram: USync Interaction This diagram shows the end-to-end communication between the Baileys client and the WhatsApp server during a USync operation. ```mermaid sequenceDiagram participant App as "Application Logic" participant Socket as "USync Socket" participant Proto as "Protocol Handler" participant Server as "WhatsApp Server" App->>Socket: executeUSyncQuery(usyncQuery) activate Socket Socket->>Proto: getQueryElement() Proto-->>Socket: BinaryNode () Socket->>Server: Send IQ (xmlns='usync') Server-->>Socket: Return IQ Result Socket->>Proto: parser(node) Proto-->>Socket: Parsed Data (status: "Busy") Socket-->>App: USyncQueryResult deactivate Socket ``` Sources: [lib/Socket/usync.js:15-68](), [lib/WAUSync/USyncQuery.js:24-50]() ## Summary The User Sync (USync) Protocol is the backbone for user-centric data retrieval in Baileys. By abstracting different data categories (status, devices, contacts, bots) into modular protocols, it provides a unified and efficient interface for maintaining up-to-date user metadata across the library.