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 ships as a single UMD bundle (wppconnect-wa.js) that you inject into a running WhatsApp Web page. There is no server component — all calls happen inside the browser context. This page covers every supported way to get the bundle into the page, plus how to confirm it is ready before you call any WPP function.

​
npm package

Install the package from the npm registry if you are using a Node.js-based automation framework such as Playwright or Puppeteer. 
npm install @wppconnect/wa-js
The package exports the compiled bundle as its default entry point. TypeScript type definitions are included at dist/index.d.ts.

​
CDN / script tag

If you are writing a userscript or loading WA-JS directly in a browser extension, reference the nightly release URL. This always points to the latest published build.
tampermonkey-header.js
// ==UserScript==
// @name         My WA-JS Script
// @namespace    http://tampermonkey.net/
// @version      0.1
// @match        https://web.whatsapp.com/*
// @require      https://github.com/wppconnect-team/wa-js/releases/download/nightly/wppconnect-wa.js
// @grant        none
// ==/UserScript==

/* globals WPP */

(function () {
  'use strict';

  WPP.loader.onReady(function () {
    console.log('WA-JS is ready!');
  });
})();
The nightly release is rebuilt automatically from the latest commit on the main branch. Use it when you need access to the most recent bug fixes and WhatsApp Web compatibility patches without waiting for a versioned npm release.

​
Playwright injection

With Playwright (or Puppeteer), use addScriptTag with require.resolve to locate the bundle on disk after installing the npm package. This avoids hard-coding an absolute path.
playwright.ts
import * as playwright from 'playwright-chromium';

async function main() {
  const browser = await playwright.chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto('https://web.whatsapp.com/');

  // Inject the WA-JS bundle into the page
  await page.addScriptTag({
    path: require.resolve('@wppconnect/wa-js'),
  });

  // Wait until WA-JS has finished loading WhatsApp's internal modules
  await page.waitForFunction(() => window.WPP?.isReady);

  console.log('WA-JS is ready. You can now call WPP functions.');
}

main();
require.resolve('@wppconnect/wa-js') returns the absolute path to dist/wppconnect-wa.js inside node_modules. Playwright reads the file from disk and evaluates it inside the page, so it works even in environments without internet access.

​
Detecting the ready state

WA-JS initialises asynchronously. Calling WPP functions before initialisation completes will throw errors or return unexpected results. Use one of the two approaches below depending on your context. Inside the page (userscripts, inline scripts)
browser-context.js
// Fires once WA-JS has loaded all core WhatsApp modules
WPP.loader.onReady(function () {
  console.log('Ready — WPP.isReady is', WPP.isReady); // true
});
From Node.js (Playwright / Puppeteer)
playwright.ts
// Poll until WPP.isReady is truthy; Playwright throws on timeout
await page.waitForFunction(() => window.WPP?.isReady);
WPP.isReady becomes true once the core modules are loaded. A separate WPP.isFullReady flag is set when every runtime chunk has been loaded — you only need this for advanced use cases.

​
Version compatibility

WA-JS requires WhatsApp Web 2.2326.10-beta or later (the engines.whatsapp-web field in package.json). The library is actively maintained to stay compatible with new WhatsApp Web versions as they roll out. If WhatsApp Web ships an update that breaks an existing function, update your WA-JS dependency to pick up the latest compatibility patch: 
npm update @wppconnect/wa-js
Pinning to an old version of WA-JS while WhatsApp Web updates can cause silent failures or runtime errors. Keep your WA-JS version current, especially in production automation pipelines.

Build docs developers (and LLMs) love

Get started for freeTalk to us