wa-js is a browser-side automation library, published as @wppconnect/wa-js, that exposes the internal functions of WhatsApp Web through a global WPP JavaScript API so that extension and browser-integration developers can script chats, messages, contacts, groups, media and events from inside the page.

What it is

WA-JS is a TypeScript project in the WPPConnect ecosystem, maintained by the WPPConnect Team and released under the Apache-2.0 licence. It builds a bundle, dist/wppconnect-wa.js, which is injected into a page running WhatsApp Web and there exposes chat, contact, connection and other modules under a single WPP global. The README is explicit that this is not a Node.js WhatsApp client: the code executes inside the browser, against the WhatsApp Web application itself, rather than against a server-side protocol implementation.

The concrete problem it solves is the absence of a stable, typed surface over WhatsApp Web's own internals. Anyone writing a browser extension or an injected script for WhatsApp Web would otherwise have to reach into undocumented page objects directly. WA-JS wraps those objects into named modules covering chat and media operations, groups, communities, channels and business catalog functions, plus connection events, profile and privacy settings, labels and chat lists, and it ships typed exports of the WhatsApp modules together with browser-injection tooling. It is the layer that powers WPPConnect integrations and extensions.

Key capabilities

• Exposes a browser-side WPP API with modules for chats, messages, contacts, groups, media and events, built into the dist/wppconnect-wa.js bundle.
• Covers group, community and channel operations alongside business catalog functions.
• Provides connection events, profile and privacy settings, labels and chat lists.
• Ships typed exported WhatsApp modules and browser-injection tooling written in TypeScript.
• Supports configuration through window.WPPConfig, set before injection, with options documented in src/config.
• Includes a local launcher that opens a browser with the bundle already injected, selectable against a cached or downloaded WhatsApp Web version via WA_VERSION.
• Offers lifecycle and state helpers in the page, such as WPP.loader.onReady() and WPP.conn.isAuthenticated().

Who uses it and how

• Extension developers who need to execute code inside a signed-in WhatsApp Web page and drive it from a browser context.
• Teams building on WPPConnect that want the browser-side layer directly rather than through the Node.js wrapper.
• Developers debugging compatibility, who pair it with the separate WA-Version project to track WhatsApp Web versions and retrieve stored page content.
• Integrations that need link-preview metadata and PNG payloads, which the companion WA-JS API SERVER is designed to serve.
• Contributors working on the wider ecosystem, since the same bundle underpins the Wppconnect Chrome extension for sending configured messages and attachments.

Getting started

Clone the repository, then run npm ci, npm run build:prd and npm run launch:local; the launcher opens a browser with the bundle injected, and after signing in you can evaluate WPP.loader.onReady(() => console.log(WPP.conn.isAuthenticated())) in the developer console. The package is also published to npm as @wppconnect/wa-js, and the API reference and events are documented at wppconnect.io/wa-js.

How it compares

The facts do not name any paid products that WA-JS replaces, so no licence or cost comparison can be drawn. Within its own ecosystem it sits at the bottom of the stack: WPPConnect controls WhatsApp Web from Node.js applications, the Wppconnect Extension puts a Chrome UI over WA-JS, and the WA-JS API SERVER supplies companion link-preview metadata, while WA-JS itself is the in-page library those projects build on.

When to use it — and when not to

Choose it when the automation genuinely has to run inside a browser page against WhatsApp Web, and when you can accept that package.json pins WhatsApp Web >=2.3000.1038792969-alpha with the caveat that individual capabilities may vary as WhatsApp updates. Do not pick it if you need a server-side or headless Node.js client, since the README states plainly that it is not one; WPPConnect is the ecosystem entry for that case. Self-hosters should also note the operational constraints: only one default WPP bundle should be loaded per page, and the documented path is a build from source rather than a hosted service.

git clone https://github.com/wppconnect-team/wa-js.git
cd wa-js
npm ci
npm run build:prd
npm run launch:local

WPP.loader.onReady(() => {
  console.log(WPP.conn.isAuthenticated());
});

npm run build:prd
npm run lint
npm test