WPPConnect/WA-JS

WhatsApp uses two distinct systems for organizing chats:

Recommendation: Use WPP.labels for business management and WPP.lists for general chat organization on any account type.

The library uses specific naming conventions to help you distinguish between data structures, collections, and active instances:

• ...Model: Represents a class for a specific data structure (e.g., ClassModel, MsgModel).
• ...Collection: Represents a class for a collection of models (e.g., ChatCollection, MsgCollection).
• ...Store: Represents the default and global instance of a collection (e.g., ChatStore, MsgStore).

WPPConnect/WA-JS works by extracting functions directly from the WhatsApp Web source code.

To use it, you must inject the generated file dist/wppconnect-wa.js into the WhatsApp Web environment. Once successfully injected, the library exposes a global object named WPP which serves as the entry point for all available functionalities.

The WPP global object is the primary interface for interacting with WhatsApp Web. It is organized into several modules:

• WPP.loader: Contains the scripts responsible for exporting the WhatsApp functions.
• WPP.whatsapp: Provides access to the core exported WhatsApp functions.
• WPP.chat: Provides access to chat-related functions and events.
• Other modules (e.g., WPP.contact, WPP.group) are also available depending on the version.

You can use the compare-wa-versions.sh script to track API changes, identify signature changes, or find new/removed modules between WhatsApp Web versions.

Note: You must run the specific versions locally first using WA_VERSION="<version>" npm run launch:local to download the necessary scripts to the wa-source folder.

Available commands:

• Compare all module differences between two versions.
• Compare a specific module.
• List available versions.

# Compare two versions (overview of module differences)
./scripts/compare-wa-versions.sh 2.3000.1031980585 2.3000.1031992593

# Compare a specific module between versions
./scripts/compare-wa-versions.sh 2.3000.1031980585 2.3000.1031992593 WAWebUpdateUnreadChatAction

# List available versions
./scripts/compare-wa-versions.sh

To develop with WA-JS, follow these steps to install dependencies, build the project, and launch a local browser with automatic injection:

1. Install dependencies: npm install
2. Build the files: npm run build:prd (production) or npm run build:dev (development)
3. Launch local browser: npm run launch:local (this also caches files in the wa-source directory).

To run a specific version of WhatsApp Web, use the WA_VERSION environment variable:

npm run wa-source:clean
npm run build:prd
WA_VERSION="2.3000.1029560485" npm run launch:local

# install the dependencies
npm install

# build javascript files
npm run build:prd # or build:dev for development

# launch a local browser with automatic injection
npm run launch:local

The project uses Playwright for testing.

• Smoke tests: Verifies that every public WPP module still exposes its documented functions. This is useful for detecting when WhatsApp Web updates break existing patches. No QR scan is required.
• Full tests: Runs the entire test suite.

To bootstrap an authenticated session for tests that require login, run npm run test:prepare. This opens a browser for you to scan the QR code. The session is cached in your OS temp directory (wa-js-test-<browser>).

# Smoke tests — no QR scan needed.
npm test -- tests/smoke.spec.ts

# Full test project
npm test

# Bootstrap authenticated session
npm run test:prepare

By default, WA-JS exposes itself as window.WPP. If you are building an extension or tool that runs alongside other WA-JS projects on the same page, you should build it with a custom global name (e.g., window.MYWPP) to avoid conflicts.

Steps to build with a custom name:

1. Modify webpack.config.js: In the output.library block, replace 'WPP' with your custom name (e.g., 'MYWPP').
2. Modify src/config/index.ts: Replace all occurrences of WPPConfig with <YOURNAME>Config (e.g., MYWPPConfig).
3. Build: Run npm run build:prd.

The resulting file in dist/wppconnect-wa.js will use your custom global and configuration keys.

// webpack.config.js
output: {
  filename: 'wppconnect-wa.js',
  path: path.resolve(__dirname, 'dist'),
  library: {
    name: 'MYWPP', // <-- your custom global variable name
    type: 'global',
  },
},

WA-JS provides several functions to interact with WhatsApp Status (Stories). You can retrieve your own status, send various media types (text, image, video) as status updates, and manage status participants.

Key capabilities include:

• Retrieving Status: Use getMyStatus to get your current status information.
• Sending Text Status: Use sendTextStatus with TextStatusOptions.
• Sending Media Status: Use sendImageStatus or sendVideoStatus with their respective option types.
• Raw Status: Use sendRawStatus for more granular control via SendStatusOptions.
• Read Receipts: Use sendReadStatus to mark statuses as read.

The newsletter module provides functions to manage WhatsApp newsletter subscriptions and interactions. You can create, edit, follow, unfollow, and search for newsletters, as well as manage subscribers and mute notifications.

import { newsletter } from '@wppconnect/wa-js';

// Example usage pattern:
// await newsletter.follow(newsletterId);
// await newsletter.getSubscribers();

The chat.active_filter event is triggered when the native WhatsApp chat-list filter changes (e.g., switching between 'All', 'Unread', or specific Labels).

• The 'All' filter is represented by { kind: null, label: null }.
• WhatsApp label lists use kind: 'labels' and provide the specific label ID in the label field.
• Note: Custom filters created via setChatList are not considered native filters; WhatsApp will remain on the 'All' filter when using them.

WPP.on('chat.active_filter', ({ kind, label }) => {
  console.log('Active filter kind:', kind);
  console.log('Active filter label:', label);
});