TheDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/wppconnect-team/wa-js/llms.txt
Use this file to discover all available pages before exploring further.
WPP.conn module is the entry point for everything related to the lifecycle of the WhatsApp Web session. It lets you inspect authentication and connection state, read your own user identity, configure client-side settings such as themes and auto-download behaviour, generate QR codes or phone-number linking codes for login, and query platform and build information. All of its functions are available on the WPP.conn namespace immediately after the loader reaches its ready state.
Authentication
isAuthenticated()
Returns true when the current session is fully authenticated with WhatsApp’s servers.
true if the session is authenticated, false otherwise.isRegistered()
Checks whether the current browser is registered with WhatsApp before the main interface has loaded. Useful for early-stage checks before WPP.loader.isReady.
true if the browser is already linked to a WhatsApp account.getStreamData()
Returns a snapshot of the current stream mode and stream info. Both values update in real time as the connection state changes.
getMyUserId()
Returns the Wid object for the currently logged-in user, excluding the device suffix. Returns undefined when not authenticated.
WhatsApp identifier object for the current user, or
undefined if not authenticated.getMyUserLid()
Returns the LID (Locally Identified) Wid for the current user. LIDs are used in multi-device sessions.
LID-scoped identity of the current user.
getMyUserWid()
Returns the full Wid of the currently logged-in user. Internally this calls either getMaybeMeUser() or getMaybeMePnUser() depending on which is available.
Full WhatsApp identifier for the current user.
logout()
Logs out the current session, waits for WhatsApp to confirm the logout event, then resolves.
Resolves to
true once the logout is confirmed.Connection settings
isOnline()
Returns true when the network is connected.
Current network online status from
NetworkStatus.online.isIdle()
Returns true when the socket is in the UNPAIRED_IDLE state — that is, not paired and not actively connecting.
true when Socket.state === SOCKET_STATE.UNPAIRED_IDLE.isMultiDevice()
Indicates whether multi-device mode is active. Always returns true for WhatsApp Web >= 2.2241.6.
Always
true on supported versions.getTheme() / setTheme(theme)
Read or change the WhatsApp Web colour theme. Changing the theme triggers a page reload after 500 ms to apply the new value.
Theme to apply. Accepted values:
'light', 'dark', or 'system'.Resolves once the preference is saved. The page reloads automatically.
Current theme preference:
'light', 'dark', or 'system'.getAutoDownloadSettings() / setAutoDownloadSettings(settings)
Read or update the auto-download preferences for each media type. Calling setAutoDownloadSettings() saves the preferences and reloads the page to apply them.
setKeepAlive(enable?)
Forces the document to appear focused and dispatches a synthetic scroll event every 15 seconds to prevent WhatsApp Web from marking the session as idle. Pass false to restore the original behaviour.
true to enable keep-alive, false to disable it.true if keep-alive is now active, false if it was disabled.setLimit(key, value)
Override built-in WhatsApp Web limits such as file size caps and the number of pinned chats.
maxMediaSize and statusVideoMaxDuration are deprecated and no longer have effect in recent WhatsApp Web versions.The limit to override. Accepted values:
| Key | Type | Description |
|---|---|---|
'maxFileSize' | number | Maximum upload size in bytes (max 1 GB). |
'maxMediaSize' | number | Maximum media upload size in bytes (max 70 MB). Deprecated. |
'maxShare' | number | Maximum number of contacts when forwarding or sharing. |
'statusVideoMaxDuration' | number | Maximum status video length in seconds. Deprecated. |
'unlimitedPin' | boolean | Remove the three-chat pinned-chat limit. |
The new value for the specified limit key.
markAvailable(available?) / markUnavailable()
Set your presence to available (online) or unavailable (offline). When set, the value is locked so WhatsApp cannot override it.
true to appear online, false to appear offline.Resolves to
true once the presence is updated.QR and phone-number linking
refreshQR()
Forces a new QR code to be generated when the session is waiting for a scan. On multi-device sessions this calls Cmd.refreshQR(); on legacy sessions it sends a socket poke and waits for the next code.
Returns null if the session is already authenticated.
Resolves with an
AuthCode object, or null when already authenticated.genLinkDeviceCodeForPhoneNumber(phone, sendPushNotification?)
Alternative authentication method. Generates a short numeric code that the user enters on their phone to link the device, instead of scanning a QR code.
Phone number in international format, digits only (e.g.
'5511999999999').Whether to send a push notification to the phone. Set to
false for silent generation.Resolves with the numeric linking code string (e.g.
'123-456').getAuthCode()
Returns the current authentication code data for the active QR state. Returns null when already authenticated, already registered, or when no QR reference is available.
Resolves with an
AuthCode object for multi-device sessions, or null when no code is available.Build and platform info
getBuildConstants()
Returns the WAWebBuildConstants module from WhatsApp’s internal bundle, providing version strings and related constants.
getPlatform()
Returns the platform identifier of the connected phone, as reported by WhatsApp’s Conn model.
Platform string from
Conn.platform. Typical values are 'android', 'iphone', or 'wp'.needsUpdate()
Returns true when WhatsApp Web is signalling that an update is required before the session can continue.
true when Stream.needsUpdate is set by the server.getABProps()
Returns all A/B test property configurations for the current session. These are experimental flags that WhatsApp uses for gradual feature roll-out.
Array of A/B property configurations. Each entry includes a
name (human-readable, may be null) and a configCode.Interface state checks
These three synchronous helpers reflect the progressive stages of the WhatsApp Web main interface boot sequence. They are useful for early-startup checks before subscribing to events.isMainInit()
Returns true once the WhatsApp Web main interface has begun initialising (detected via window.Debug.VERSION).
true when window.Debug.VERSION is set, indicating the interface has started.isMainLoaded()
Returns true once the main interface is authenticated and loaded but not necessarily fully synced with message history.
true when Cmd.isMainLoaded is set.isMainReady()
Returns true once the main interface is authenticated, loaded, and synced — the conn.main_ready event has fired. This is the ideal moment to start sending messages.
true after the conn.main_ready event has fired.History sync and migration
getHistorySyncProgress()
Returns the current progress of the history sync operation that downloads old messages after a new device link.
getMigrationState()
Returns the LID (Linked Identity) migration state for the current account. Useful for debugging multi-device identity issues.
Device management
getMyDeviceId()
Returns the current logged-in user’s full Wid including the device ID suffix (e.g. 123:4@c.us). Differs from getMyUserId() which strips the device suffix.
Full device-scoped Wid, or
undefined when not authenticated.setMultiDevice(md?)
Switch WhatsApp Web between multi-device (MD) and legacy single-device mode. On modern WhatsApp Web versions, multi-device is the default.
true to switch to multi-device (calls Cmd.upgradeToMDProd()), false to downgrade to legacy (calls Cmd.downgradeWebclient()).Always returns
true after the switch command is issued.joinWebBeta(value)
Opt in or out of the WhatsApp Web external beta program. The new value is persisted to IndexedDB.
true to join the beta, false to leave. Throws a WPPError with code value_not_a_boolean if the value is not a boolean.Resolves with the new beta opt-in state as confirmed by IndexedDB.
changeEnviromentDevice()
Toggles the environment device between Web and Windows by flipping Enviroment.isWeb and Enviroment.isWindows. This affects how WhatsApp Web identifies itself to the server.
The function name preserves the original spelling from the source (
Enviroment, not Environment).Events
WPP.conn emits events through the global WPP.on() / WPP.off() event bus. Subscribe to them from anywhere in your code.
conn.stream_mode_changed
Fired immediately when the loader captures the current mode, and again each time the stream mode changes. Use this to react to authentication and disconnection transitions.
The new stream mode. Possible values:
| Value | Meaning |
|---|---|
'QR' | Waiting for QR code scan. |
'MAIN' | Authenticated and running normally. |
'SYNCING' | Authenticated but still syncing message history. |
'OFFLINE' | No network connection. |
'CONFLICT' | Session conflict — another device opened the same account. |
'PROXYBLOCK' | Connection blocked, typically by a proxy or firewall. |
'TOS_BLOCK' | Account suspended due to Terms of Service violation. |
'SMB_TOS_BLOCK' | Business account suspended due to Terms of Service violation. |
'DEPRECATED_VERSION' | WhatsApp Web version is too old and must be updated. |
conn.stream_info_changed
Fired when the internal WebSocket connection state changes. This is a lower-level signal than stream_mode_changed and reflects the socket handshake progress.
The new connection state. Possible values:
| Value | Meaning |
|---|---|
'OFFLINE' | Not connected. |
'OPENING' | WebSocket is opening. |
'PAIRING' | Pairing with the phone. |
'SYNCING' | Syncing message history after pairing. |
'RESUMING' | Resuming an existing session. |
'CONNECTING' | Establishing the WebSocket connection. |
'NORMAL' | Fully connected and operational. |
Additional events
conn.authenticated
conn.authenticated
Fired once after a successful QR code scan.
conn.logout
conn.logout
Fired when the session is logged out.
conn.online
conn.online
Fired when the network online status changes.Payload is a
boolean: true for online, false for offline.conn.main_init / conn.main_loaded / conn.main_ready
conn.main_init / conn.main_loaded / conn.main_ready
Lifecycle events for the WhatsApp Web main interface.
conn.main_init— interface has started bootingconn.main_loaded— interface is loaded but may still be syncingconn.main_ready— interface is loaded, authenticated, and ready to send messages
conn.auth_code_change
conn.auth_code_change
Fired when a new QR code or auth code becomes available.Payload is
AuthCode | null.conn.needs_update
conn.needs_update
Fired when WhatsApp Web signals that an update is required.
conn.qrcode_idle
conn.qrcode_idle
Fired when the QR code has been shown for too long without a scan and has become idle.
conn.backend_event
conn.backend_event
Passes through every event emitted by WhatsApp Web’s internal
BackendEventBus. The first argument is the event name; additional arguments vary per event.