User Status & Bot Profiles Sync

Relevant source files

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

• lib/WAUSync/Protocols/USyncBotProfileProtocol.js
• lib/Socket/chats.js
• lib/Socket/socket.js
• WAProto/BotMetadata/BotMetadata.proto
• lib/Utils/message-composer.js
• lib/Utils/messages.js

The User Status & Bot Profiles Sync system in Baileys is a specialized implementation of the WhatsApp Universal Sync (USync) protocol. Its primary purpose is to retrieve and synchronize real-time metadata for standard users and AI bot entities. This includes user text statuses, disappearing message settings, and complex bot profiles containing personas, commands, and prompts.

Within the library architecture, the sync process is orchestrated by the USyncQuery class, which aggregates multiple protocols into a single binary iq (information query) stanza. This allows the client to fetch disparate metadata—such as a user's current status and their bot-specific configuration—in a single network round-trip.

USync Query Architecture

The synchronization relies on a modular architecture where different types of metadata are requested via specialized "protocols." Each protocol defines how to build its portion of the XML query and how to parse the resulting binary nodes returned by the WhatsApp server.

Execution Flow

The core execution logic resides in socket.js, which handles the construction of the usync stanza and the synchronous wait for a server response.

The query process involves wrapping user JIDs and requested protocols into a list and query node structure respectively.
Sources: [lib/Socket/socket.js:84-123](https://github.com/innovatorssoft/Baileys/blob/000e5a14951e89b9ac56d4e08bef5524b8299f45/lib/Socket/socket.js#L84-L123)

Key System Components

Component	Responsibility
USyncQuery	Main container for users and protocols to be synced.
USyncUser	Represents a target entity (User JID, Phone, or Bot Persona).
executeUSyncQuery	Sends the binary iq and invokes protocol-specific parsers.
fetchStatus	High-level API to sync text statuses for multiple JIDs.
getBotListV2	Retrieves the list of available AI bots and their persona IDs.

Sources: [lib/Socket/chats.js:188-200](https://github.com/innovatorssoft/Baileys/blob/000e5a14951e89b9ac56d4e08bef5524b8299f45/lib/Socket/chats.js#L188-L200), [lib/Socket/socket.js:84-123](https://github.com/innovatorssoft/Baileys/blob/000e5a14951e89b9ac56d4e08bef5524b8299f45/lib/Socket/socket.js#L84-L123), [lib/Socket/chats.js:145-171](https://github.com/innovatorssoft/Baileys/blob/000e5a14951e89b9ac56d4e08bef5524b8299f45/lib/Socket/chats.js#L145-L171)

Bot Profiles Synchronization

Bot profiles are distinct from standard user profiles as they contain metadata required for AI interactions. The USyncBotProfileProtocol handles the retrieval of these extended attributes.

Bot Metadata Parsing

The protocol requests the bot tag with a nested profile element (version 1). When the server responds, the parser method extracts structured data:

1. Commands: Specific triggers available for the bot, including their names and descriptions.
2. Prompts: Suggested interaction starters, often including emojis.
3. Persona Info: The unique persona_id, category, and default status of the bot.

Bot Metadata Protobufs

On the protocol level, bots are represented by the BotMetadata message, which includes fields for personaId, pluginMetadata, and suggestedPromptMetadata. This structure supports advanced features like AIThreadInfo and BotProgressIndicatorMetadata.
Sources: [WAProto/BotMetadata/BotMetadata.proto:7-32](https://github.com/innovatorssoft/Baileys/blob/000e5a14951e89b9ac56d4e08bef5524b8299f45/WAProto/BotMetadata/BotMetadata.proto#L7-L32)

User Status Synchronization

User status synchronization is primarily handled through the fetchStatus method. This method uses the status protocol to retrieve the text-based "About" information of WhatsApp users.

High-Level API Logic

The makeChatsSocket function exposes several high-level methods for status and profile management:

• fetchStatus(...jids): Initiates a USync query specifically for the status protocol.
• updateProfileStatus(status): Sends an iq stanza to the status namespace to update the local user's own status text.
• fetchDisappearingDuration(...jids): Syncs the ephemeral message settings (disappearing mode) using USync.

Implementation Details

USync Bot Profile Data Model

The parsed bot profile object provides a comprehensive view of the bot's capabilities.

Field	Description	Source
name	The display name of the bot.	USyncBotProfileProtocol.js:52
description	A textual bio or description of the bot's purpose.	USyncBotProfileProtocol.js:54
personaId	The unique identifier for the AI persona.	USyncBotProfileProtocol.js:56
commands	An array of { name, description } for available bot functions.	USyncBotProfileProtocol.js:33-40
prompts	List of strings combining emojis and text for conversation starters.	USyncBotProfileProtocol.js:43-49

Interaction with Rich Messages

The sync system provides the metadata necessary to construct botForwardedMessage and richResponseMessage types. These messages often include forwardedAiBotMessageInfo which requires the botJid fetched during the sync process (defaulting to 867051314767696@bot for Meta AI).
Sources: [lib/Utils/message-composer.js:115-125](https://github.com/innovatorssoft/Baileys/blob/000e5a14951e89b9ac56d4e08bef5524b8299f45/lib/Utils/message-composer.js#L115-L125), [lib/Utils/messages.js:1125-1135](https://github.com/innovatorssoft/Baileys/blob/000e5a14951e89b9ac56d4e08bef5524b8299f45/lib/Utils/messages.js#L1125-L1135)

Summary

The User Status & Bot Profiles Sync module provides a robust interface for handling entity metadata. By utilizing the USync protocol, Baileys efficiently manages the retrieval of traditional user statuses alongside the increasingly complex metadata required for Meta AI and third-party bot integrations. This system ensures that the client has the necessary persona IDs, command lists, and status updates required for a modern messaging experience.