Configuration Options
Relevant source files
The following files were used as context for generating this wiki page:
Configuration Options in the Baileys library define the operational behavior of the WhatsApp Web API bridge. These settings range from socket-level parameters (authentication, logging, and synchronization) to message-level attributes (media handling, styling, and interactive elements). Proper configuration ensures compatibility with different platforms and allows for advanced features like rich AI responses and complex UI components.
Sources: assets/examples/example.js:34-39, lib/Utils/messages.js:61-65
Socket Initialization Options
When creating a new connection via makeWASocket, several key parameters control how the library interacts with WhatsApp servers. These options are primarily used to manage state persistence, history synchronization, and debugging.
Primary Socket Parameters
The socket configuration object passed to makeWASocket determines the initial state of the connection.
| Option | Type | Description |
|---|---|---|
auth | AuthenticationState | Manages credentials, keys, and session data. |
syncFullHistory | boolean | Whether to synchronize the entire chat history upon connection. |
logger | Pino.Logger | An instance of a logger (e.g., Pino) for debugging. |
markOnlineOnConnect | boolean | Automatically sets the account status to online when connected. |
Sources: assets/examples/example.js:34-39
Connection Flow
The following diagram illustrates the socket initialization process using these configuration options:
The initialization flow ensures that authentication and logging are established before the synchronization strategy is executed. Sources: assets/examples/example.js:34-45
Browser and Platform Configuration
Baileys allows developers to spoof specific platforms and browsers to ensure compatibility or mimic specific device behaviors. This is configured using a "Browser Tuple" consisting of the operating system name, the browser name, and the browser version.
Platform Mapping
The library maps internal OS identifiers to user-friendly strings sent during the handshake.
| ID | Platform Name | Internal Version (Default) |
|---|---|---|
darwin | Mac OS | 18.5 |
win32 | Windows | 10.0.22631 |
android | Android | 14.0.0 |
linux | Linux | 6.5 |
ubuntu | Ubuntu | 22.04.4 |
baileys | Baileys | 6.5.0 |
Sources: lib/Utils/generics.js:42-86
Browser Tuple Generation
Developers can use the Browsers utility to generate valid configuration arrays:
Browsers.ubuntu('Chrome'):['Ubuntu', 'Chrome', '22.04.4']Browsers.macOS('Desktop'):['Mac OS', 'Desktop', '18.5']Browsers.appropriate('Chrome'): Automatically detects the host OS.Browsers.custom('MyOS', 'MyBrowser', '1.0'): Allows arbitrary values.
Sources: lib/Utils/generics.js:88-124
Message Handling and Media Options
Message configuration options control how content is processed before being sent to the WhatsApp servers. This includes media encryption, thumbnail generation, and text formatting.
Media Processing Options
When calling functions like prepareWAMessageMedia, several options dictate the handling of attachments:
| Option | Type | Description |
|---|---|---|
upload | Function | The function used to upload encrypted media to the WA server. |
mediaCache | Cache | An optional cache to store and reuse processed media metadata. |
mediaTypeOverride | string | Forces a specific media type (e.g., 'thumbnail-link'). |
mediaUploadTimeoutMs | number | Timeout for the media upload process. |
backgroundColor | string/number | Background ARGB for audio PTT messages or text status. |
Sources: lib/Utils/messages.js:61-125
Interactive and Rich Message Configuration
Baileys supports advanced message types that require specific metadata structures. The MessageBuilder class and message-composer utility use these options to build "Native Flow" and "Rich Response" payloads.
Interactive messages allow for button configurations such as cta_url, cta_call, and single_select via a buttonParamsJson payload. Sources: assets/buttonsbuilder/MessageBuilder.js:315-410, lib/Utils/message-composer.js:130-150
Protocol and Versioning
WhatsApp Web requires a specific version array for the handshake. This is maintained in a central configuration file.
Versioning Configuration
The version is represented as a three-part integer array: [Major, Minor, Patch].
- Current Default:
[2, 3000, 1015949539] - Utility:
fetchLatestWaWebVersioncan be used to dynamically retrieve the newest version from the WhatsApp Web service worker.
Sources: lib/Defaults/baileys-version.json:2, lib/Utils/generics.js:358-390
Conclusion
The configuration system in Baileys provides granular control over both the connection lifecycle and the specific presentation of message data. By leveraging the Browsers utility for platform spoofing and the various media processing options, developers can tailor the library to support diverse environments and complex interactive use cases. Proper alignment with the versioning found in baileys-version.json is critical for maintaining a stable connection to the WhatsApp infrastructure.
Sources: lib/Utils/generics.js:88-124, lib/Utils/messages.js:61-125