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 that wraps WhatsApp Web’s internal modules and exposes them as the global WPP object. By the end of this guide you will have WA-JS running in a real WhatsApp Web session and will have sent your first message programmatically.

​
Prerequisites

Before you begin, make sure you have the following:
  • Node.js 18 or later — required if you are automating via Playwright or a similar framework
  • A WhatsApp account — you need an active account to authenticate with WhatsApp Web
  • A Chromium-based browser — WA-JS injects into the WhatsApp Web page; Chrome, Edge, or Playwright’s bundled Chromium all work

​
Steps

1

Install the package

Add @wppconnect/wa-js to your project using your preferred package manager.
npm install @wppconnect/wa-js
If you are using a userscript manager such as TamperMonkey or GreaseMonkey instead, skip this step and use the CDN script tag shown in the next step.
2

Inject WA-JS into WhatsApp Web

WA-JS must run inside the WhatsApp Web page context. Choose the approach that matches your setup.CDN / userscript — add a @require directive pointing to the nightly release:
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==
Playwright — inject the built bundle with addScriptTag after navigating to WhatsApp Web:
playwright.ts
import * as playwright from 'playwright-chromium';

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

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

await page.addScriptTag({
  path: require.resolve('@wppconnect/wa-js'),
});
3

Wait for WA-JS to be ready

WA-JS initialises asynchronously while WhatsApp Web loads its own modules. Always wait for the ready signal before calling any WPP function.In a userscript or inline browser script, use WPP.loader.onReady():
browser-context.js
WPP.loader.onReady(function () {
  console.log('WA-JS is ready!');
  // Your code here
});
In Playwright, poll the WPP.isReady flag from the Node.js side:
playwright.ts
// Wait until WA-JS signals it is ready
await page.waitForFunction(() => window.WPP?.isReady);

console.log('WA-JS is ready!');
4

Send your first message

Once WA-JS is ready, use WPP.chat.sendTextMessage() to send a text message. Pass the recipient’s WhatsApp ID and the message text.
browser-context.js
WPP.loader.onReady(async function () {
  await WPP.chat.sendTextMessage('5511999999999@c.us', 'Hello from WA-JS!');
  console.log('Message sent!');
});
From Playwright, evaluate the call inside the page context:
playwright.ts
await page.evaluate(
  ([to, message]) => WPP.chat.sendTextMessage(to, message),
  ['5511999999999@c.us', 'Hello from WA-JS!']
);
WhatsApp IDs follow a specific format. Use number@c.us for individual contacts (e.g. 5511999999999@c.us) and groupid@g.us for groups. The number must include the full country code with no +, spaces, or dashes.

​
Complete working example

The snippet below brings all four steps together in a single Playwright script. Scan the QR code when the browser opens, then watch your message arrive.
complete-example.ts
import * as playwright from 'playwright-chromium';

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

  // Navigate to WhatsApp Web
  await page.goto('https://web.whatsapp.com/');

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

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

  // Check that the session is authenticated before sending
  const isAuthenticated = await page.evaluate(() => WPP.conn.isAuthenticated());
  if (!isAuthenticated) {
    console.log('Please scan the QR code to log in.');
    await page.waitForFunction(() => WPP.conn.isAuthenticated(), { timeout: 60_000 });
  }

  // Send a text message
  await page.evaluate(
    ([to, message]) => WPP.chat.sendTextMessage(to, message),
    ['5511999999999@c.us', 'Hello from WA-JS!']
  );

  console.log('Message sent successfully.');
  await browser.close();
}

main();

Build docs developers (and LLMs) love

Get started for freeTalk to us