Skip to main content

Documentation 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.

The 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.
const authenticated = WPP.conn.isAuthenticated();
console.log('Authenticated:', authenticated);
return
boolean
required
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.
const registered = WPP.conn.isRegistered();
console.log('Registered:', registered);
return
boolean
required
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.
const stream = WPP.conn.getStreamData();
console.log('Mode:', stream.mode);  // e.g. 'MAIN', 'QR', 'SYNCING'
console.log('Info:', stream.info);  // e.g. 'NORMAL', 'OPENING'
return
object
required

getMyUserId()

Returns the Wid object for the currently logged-in user, excluding the device suffix. Returns undefined when not authenticated.
const wid = WPP.conn.getMyUserId();
if (wid) {
  console.log(wid.toString()); // e.g. '5511999999999@c.us'
}
return
Wid | undefined
required
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.
const lid = WPP.conn.getMyUserLid();
console.log(lid.toString()); // e.g. '123456789@lid'
return
Wid
required
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.
const wid = WPP.conn.getMyUserWid();
console.log(wid.toString()); // e.g. '5511999999999@c.us'
return
Wid
required
Full WhatsApp identifier for the current user.

logout()

Logs out the current session, waits for WhatsApp to confirm the logout event, then resolves.
Calling logout() terminates the active session immediately. The user will need to scan a new QR code or use phone-number linking to reconnect.
await WPP.conn.logout();
console.log('Logged out successfully');
return
Promise<boolean>
required
Resolves to true once the logout is confirmed.

Connection settings

isOnline()

Returns true when the network is connected.
if (WPP.conn.isOnline()) {
  console.log('Network is online');
}
return
boolean
required
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.
if (WPP.conn.isIdle()) {
  console.log('Socket is idle and unpaired');
}
return
boolean
required
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.
console.log(WPP.conn.isMultiDevice()); // true
return
boolean
required
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.
Use the string literal values 'light', 'dark', or 'system' directly, or import the Theme enum from @wppconnect/wa-js.
// Read current theme
const theme = WPP.conn.getTheme();
console.log(theme); // 'light', 'dark', or 'system'

// Set to dark mode (triggers page reload)
await WPP.conn.setTheme('dark');

// Or use the enum
import { Theme } from '@wppconnect/wa-js';
await WPP.conn.setTheme(Theme.LIGHT);
body.theme
string
required
Theme to apply. Accepted values: 'light', 'dark', or 'system'.
setTheme return
Promise<void>
Resolves once the preference is saved. The page reloads automatically.
getTheme return
string
required
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.
// Read current settings
const settings = WPP.conn.getAutoDownloadSettings();
console.log(settings);
// { photos: true, audio: true, videos: false, documents: false }

// Disable video and document auto-download
await WPP.conn.setAutoDownloadSettings({
  videos: false,
  documents: false,
});
body.settings
object
required
getAutoDownloadSettings return
object
required

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.
// Enable keep-alive (default)
WPP.conn.setKeepAlive();

// Disable keep-alive
WPP.conn.setKeepAlive(false);
body.enable
boolean
default:"true"
true to enable keep-alive, false to disable it.
return
boolean
required
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.
// Raise the maximum upload file size to 100 MB
WPP.conn.setLimit('maxFileSize', 104857600);

// Allow sharing to up to 50 contacts at once
WPP.conn.setLimit('maxShare', 50);

// Remove the three-chat pin limit
WPP.conn.setLimit('unlimitedPin', true);
body.key
string
required
The limit to override. Accepted values:
KeyTypeDescription
'maxFileSize'numberMaximum upload size in bytes (max 1 GB).
'maxMediaSize'numberMaximum media upload size in bytes (max 70 MB). Deprecated.
'maxShare'numberMaximum number of contacts when forwarding or sharing.
'statusVideoMaxDuration'numberMaximum status video length in seconds. Deprecated.
'unlimitedPin'booleanRemove the three-chat pinned-chat limit.
body.value
number | boolean
required
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.
// Mark as online
await WPP.conn.markAvailable();

// Mark as offline
await WPP.conn.markAvailable(false);
// or equivalently:
await WPP.conn.markUnavailable();
body.available
boolean
default:"true"
true to appear online, false to appear offline.
return
Promise<boolean>
required
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.
const authCode = await WPP.conn.refreshQR();
if (authCode) {
  console.log('QR data:', authCode.fullCode);
}
return
Promise<AuthCode | null>
required
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.
Throws if the session is already authenticated or if no phone number is provided.
// Request a linking code sent to the phone via push notification
const code = await WPP.conn.genLinkDeviceCodeForPhoneNumber('5511999999999');
console.log('Link code:', code); // e.g. '123-456'

// Request silently without push notification
const code = await WPP.conn.genLinkDeviceCodeForPhoneNumber('5511999999999', false);
body.phone
string
required
Phone number in international format, digits only (e.g. '5511999999999').
body.sendPushNotification
boolean
default:"true"
Whether to send a push notification to the phone. Set to false for silent generation.
return
Promise<string>
required
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.
const authCode = await WPP.conn.getAuthCode();
if (authCode) {
  console.log('Full QR code data:', authCode.fullCode);
}
return
Promise<AuthCode | null>
required
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.
const build = WPP.conn.getBuildConstants();
if (build) {
  console.log('Version:', build.VERSION_STR);      // e.g. '2.3000.1234567'
  console.log('Primary:', build.PARSED.PRIMARY);   // e.g. 2
  console.log('Windows build:', build.WINDOWS_BUILD);
}
return
BuildConstants | null
required

getPlatform()

Returns the platform identifier of the connected phone, as reported by WhatsApp’s Conn model.
const platform = WPP.conn.getPlatform();
console.log(platform); // e.g. 'android', 'iphone', 'wp'
return
string
required
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.
if (WPP.conn.needsUpdate()) {
  console.warn('WhatsApp Web update required — reload the page');
}
return
boolean
required
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.
const props = WPP.conn.getABProps();
props.forEach((prop) => {
  console.log(`${prop.name}: ${prop.configValue}`);
});
return
ABPropConfig[]
required
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).
if (WPP.conn.isMainInit()) {
  console.log('Main interface is initialising');
}
return
boolean
required
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.
if (WPP.conn.isMainLoaded()) {
  console.log('Main interface loaded (may still be syncing)');
}
return
boolean
required
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.
if (WPP.conn.isMainReady()) {
  console.log('Main interface is fully ready');
}
return
boolean
required
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.
const info = WPP.conn.getHistorySyncProgress();
console.log('Progress:', info.progress);      // 0–100
console.log('In progress:', info.inProgress); // true while syncing
console.log('Paused:', info.paused);          // true if sync is paused
return
HistorySyncProgress
required

getMigrationState()

Returns the LID (Linked Identity) migration state for the current account. Useful for debugging multi-device identity issues.
const state = WPP.conn.getMigrationState();
console.log('LID migrated:', state.isLidMigrated);
console.log('Current LID:', state.currentLid?.toString());
console.log('Current PN:', state.currentPn?.toString());
return
MigrationState
required

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.
const deviceWid = WPP.conn.getMyDeviceId();
console.log(deviceWid?.toString()); // e.g. '5511999999999:4@c.us'
return
Wid | undefined
required
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.
Switching modes requires a session re-link. Only use this if you need to downgrade to legacy mode for compatibility with older infrastructure.
// Upgrade to multi-device mode (default)
WPP.conn.setMultiDevice(true);

// Downgrade to legacy single-device mode
WPP.conn.setMultiDevice(false);
md
boolean
default:"true"
true to switch to multi-device (calls Cmd.upgradeToMDProd()), false to downgrade to legacy (calls Cmd.downgradeWebclient()).
return
boolean
required
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.
// Join the beta program
await WPP.conn.joinWebBeta(true);

// Leave the beta program
await WPP.conn.joinWebBeta(false);
value
boolean
required
true to join the beta, false to leave. Throws a WPPError with code value_not_a_boolean if the value is not a boolean.
return
Promise<boolean>
required
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).
// Toggle between Web and Windows environment
WPP.conn.changeEnviromentDevice();
return
void

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.
WPP.on('conn.stream_mode_changed', (mode) => {
  console.log('Stream mode:', mode);
});
mode
StreamMode
required
The new stream mode. Possible values:
ValueMeaning
'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.
WPP.on('conn.stream_info_changed', (info) => {
  console.log('Stream info:', info);
});
info
StreamInfo
required
The new connection state. Possible values:
ValueMeaning
'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

Fired once after a successful QR code scan.
WPP.on('conn.authenticated', () => {
  console.log('Session authenticated');
});
Fired when the session is logged out.
WPP.on('conn.logout', () => {
  console.log('Session logged out');
});
Fired when the network online status changes.
WPP.on('conn.online', (online) => {
  console.log(online ? 'Now online' : 'Now offline');
});
Payload is a boolean: true for online, false for offline.
Lifecycle events for the WhatsApp Web main interface.
WPP.on('conn.main_init', () => console.log('Interface booting'));
WPP.on('conn.main_loaded', () => console.log('Interface loaded, syncing'));
WPP.on('conn.main_ready', () => console.log('Interface ready'));
  • conn.main_init — interface has started booting
  • conn.main_loaded — interface is loaded but may still be syncing
  • conn.main_ready — interface is loaded, authenticated, and ready to send messages
Fired when a new QR code or auth code becomes available.
WPP.on('conn.auth_code_change', (authCode) => {
  if (authCode) {
    console.log('New auth code:', authCode.fullCode);
  }
});
Payload is AuthCode | null.
Fired when WhatsApp Web signals that an update is required.
WPP.on('conn.needs_update', () => {
  console.warn('Update required — reload the page');
});
Fired when the QR code has been shown for too long without a scan and has become idle.
WPP.on('conn.qrcode_idle', () => {
  console.log('QR code idle — call refreshQR() to get a new one');
});
Passes through every event emitted by WhatsApp Web’s internal BackendEventBus. The first argument is the event name; additional arguments vary per event.
WPP.on('conn.backend_event', (eventName, ...args) => {
  if (eventName === 'storage_initialization_error') {
    // IndexedDB failed — clear profile and restart
  }
});

Build docs developers (and LLMs) love