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.

WA-JS (@wppconnect/wa-js) is a browser injection library. After being injected into the WhatsApp Web page at runtime, it discovers WhatsApp’s internal module system, extracts the functions and data models it needs, and re-exports them through a single stable public API: the global window.WPP object. None of the internals are exposed directly — everything passes through a feature layer that WA-JS controls.

​
The WPP global object

When the bundle is injected and the loader finishes, window.WPP becomes available in the browser context. Its top-level namespaces map directly to src/index.ts:
NamespacePurpose
WPP.loaderLoader state (isReady, isFullReady) and lifecycle hooks (onReady, onFullReady)
WPP.whatsappLow-level bindings to WhatsApp internals (models, collections, stores, functions)
WPP.chatChat functions and events (sendTextMessage, get, deleteMessage, …)
WPP.connConnection management (isAuthenticated, getStreamData, logout, refreshQR, …)
WPP.contactContact lookup and management
WPP.groupGroup creation, participant management, invite codes
WPP.blocklistBlock and unblock contacts
WPP.communityCommunity and subgroup management
WPP.newsletterWhatsApp Channels (newsletters)
WPP.catalog / WPP.cart / WPP.orderBusiness catalog and ordering
WPP.statusStatus (story) posting and reading
WPP.labels / WPP.listsChat organization features
WPP.profile / WPP.privacyProfile and privacy settings
WPP.evGlobal event emitter (also re-exported as top-level WPP.on, WPP.off, etc.)
Event methods (WPP.on, WPP.off, WPP.once, WPP.onAny, WPP.waitFor) are re-exported at the top level directly from the event emitter for convenience.

​
The loader system

The most critical piece of WA-JS is src/loader/. Because WhatsApp Web’s module bundler has changed over time, the loader detects which module system is active and adapts accordingly.

Meta loader

Used for WhatsApp Web >= 2.3000.0. Calls global.require() wrapped with ErrorGuard.skipGuardGlobal() to bypass WhatsApp’s internal error guards. Installs setter traps on global.__d and global.require to start the moment those globals are assigned.

Webpack loader

Used for legacy versions. Intercepts webpack chunk callbacks at startup by pushing into webpackChunkwhatsapp_web_client before WhatsApp’s own bundles run, obtaining a reference to __webpack_require__ and all loaded modules.
Both loaders expose the same moduleRequire interface to the rest of WA-JS, so all src/whatsapp/ imports resolve transparently through whichever loader is active. The loader progresses through three lifecycle states:
StateFlagMeaning
InjectedWPP.loader.isInjectedLoader has captured the module system
ReadyWPP.loader.isReadyCore WhatsApp modules are resolvable
Full readyWPP.loader.isFullReadyAll runtime chunks have loaded

​
Module layout

Feature modules follow a consistent internal structure. Taking src/chat/ as an example: 
src/chat/
├── index.ts          # Re-exports functions and registers patches/events
├── types.ts          # TypeScript types for the feature
├── patch.ts          # Monkey-patches WhatsApp internals (if needed)
├── functions/        # One file per exported public function
└── events/           # Event registration and re-emission
Every feature module in src/<feature>/ wraps the low-level bindings in src/whatsapp/. The whatsapp directory is organized by type: 
src/whatsapp/
├── models/           # WhatsApp data model classes (Chat, Message, Contact…)
├── collections/      # Backbone-style collections of models
├── stores/           # Singleton global collection instances (ChatStore, MsgStore…)
├── functions/        # Raw WhatsApp functions extracted from the bundle
├── enums/            # WhatsApp enumerations (StreamMode, StreamInfo…)
├── multidevice/      # Multi-device protocol
└── websocket/        # WebSocket layer
Naming conventions for exported WhatsApp bindings:
  • ...Model — a data model class (e.g. ChatModel, MsgModel)
  • ...Collection — a collection of models (e.g. ChatCollection, MsgCollection)
  • ...Store — the global singleton instance of a collection (e.g. ChatStore, MsgStore)

​
Architectural layers

The following table shows how data flows from WhatsApp Web’s internals to your code:
LayerLocationRole
WhatsApp Web internalsBrowser JS bundleModels, collections, stores, raw functions
WA-JS loadersrc/loader/Captures the module system; resolves internal modules
src/whatsapp/ bindingssrc/whatsapp/Typed wrappers around the raw internal modules
Feature modulessrc/<feature>/Public, versioned API: functions, patches, events
window.WPPdist/wppconnect-wa.jsSingle UMD global your code calls

​
Build output

Webpack (configured in webpack.config.js) bundles everything from src/index.ts into a single UMD file: 
dist/wppconnect-wa.js
The output library is configured as type: 'global' with name: 'WPP', so after injection the object is available on window.WPP without any import statement. The src/tools/ directory contains development utilities that are excluded from the bundle. 
// webpack.config.js (excerpt)
output: {
  filename: 'wppconnect-wa.js',
  path: path.resolve(__dirname, 'dist'),
  library: {
    name: 'WPP',
    type: 'global',
  },
},
src/whatsapp/ bindings are internal implementation details, not public API. They expose raw WhatsApp internals and may break whenever WhatsApp ships an update. Always use the feature modules (WPP.chat, WPP.conn, WPP.contact, etc.) in your own code.

Build docs developers (and LLMs) love

Get started for freeTalk to us