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 runs entirely inside the browser. The compiled bundle (dist/wppconnect-wa.js) must be added to the WhatsApp Web page before your code calls any WPP.* function. Once the script loads, the loader initializes automatically, discovers WhatsApp’s internal module system, and fires lifecycle events to tell you when the API is ready.

​
Injection methods

There are two primary ways to inject the bundle, depending on your environment. 
// ==UserScript==
// @name         WA-JS example
// @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');
  });
})();
Inject the WA-JS bundle as early as possible — before the user interacts with the WhatsApp Web page. Injecting after WhatsApp has already booted can cause the Webpack loader to miss the chunk callback window, falling back to a polling strategy that may delay or fail initialization. With the Meta loader (WA >= 2.3000.0) this is less of a concern, but injecting early is still the safest approach.

​
Injection lifecycle

After the script is added to the page, WA-JS moves through a fixed sequence of states. Each state has a corresponding flag and callback hook.
1

Injection

The loader captures WhatsApp’s module system (Meta or Webpack). WPP.loader.isInjected becomes true and the internal loader.injected event fires.
2

Ready

Core WhatsApp modules are resolvable. WPP.loader.isReady and the top-level WPP.isReady both become true. The loader.ready event fires, and WPP.loader.onReady(callback) callbacks run.
3

Full ready

All runtime chunks have loaded, including locale bundles. WPP.loader.isFullReady becomes true and WPP.loader.onFullReady(callback) callbacks run. Most features are already available at the ready step; full ready is only needed for less common modules.

​
Checking readiness

Use the appropriate method depending on whether you are inside the page or orchestrating from outside. 
// Poll the flag directly
if (window.WPP?.isReady) {
  // already ready
}

// Or register a callback — fires immediately if already ready
WPP.loader.onReady(function () {
  console.log('WA-JS ready');
});

// Wait for all chunks too
WPP.loader.onFullReady(function () {
  console.log('WA-JS fully ready');
});

​
WhatsApp ID format

Every entity in WhatsApp is identified by a WhatsApp ID (Wid). The format depends on the entity type:
EntityFormatExample
Contact / individual{phone}@c.us15551234567@c.us
Group{groupId}@g.us120363000000000001@g.us
Newsletter (Channel){id}@newsletter123456789@newsletter
Status broadcaststatus@broadcaststatus@broadcast
Always include the suffix when passing IDs to WA-JS functions: 
// Send a message to a contact
await WPP.chat.sendTextMessage('15551234567@c.us', 'Hello!');

// Send a message to a group
await WPP.chat.sendTextMessage('120363000000000001@g.us', 'Hello group!');

​
Checking connection state

Before sending messages or reading data, verify that the session is authenticated and the connection is in a usable state. 
WPP.loader.onReady(async function () {
  // Check authentication
  const authenticated = WPP.conn.isAuthenticated();
  console.log('Authenticated:', authenticated);

  // Get full connection state
  const streamData = WPP.conn.getStreamData();
  // { mode: 'MAIN', info: 'NORMAL' }
  console.log('Stream mode:', streamData.mode);
  console.log('Stream info:', streamData.info);
});
React to connection changes in real time: 
WPP.on('conn.stream_mode_changed', function (mode) {
  if (mode === 'MAIN') {
    console.log('WhatsApp is connected and ready');
  } else if (mode === 'QR') {
    console.log('Waiting for QR code scan');
  } else if (mode === 'OFFLINE') {
    console.log('Connection lost');
  }
});
See the Events page for the full list of stream modes and connection events.

Build docs developers (and LLMs) love

Get started for freeTalk to us