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.

TamperMonkey and GreaseMonkey are browser extensions that run userscripts on pages you visit. Because they let you load external JavaScript before a page’s own scripts run, they are the fastest way to get WA-JS into WhatsApp Web without installing Node.js or building anything locally. Write your automation logic once, and it runs every time you open web.whatsapp.com.

​
Prerequisites

Install one of these extensions in your browser before continuing:
  • TamperMonkey — Chrome, Firefox, Edge, Safari
  • GreaseMonkey — Firefox only

​
The userscript

The following script is the minimal working example from the WA-JS README. Copy it exactly into a new userscript in TamperMonkey or GreaseMonkey: 
// ==UserScript==
// @name         WA-JS Teste
// @namespace    http://tampermonkey.net/
// @version      0.1
// @description  Simple example of WA-JS
// @author       You
// @match        https://web.whatsapp.com/*
// @icon         https://www.google.com/s2/favicons?domain=whatsapp.com
// @require      https://github.com/wppconnect-team/wa-js/releases/download/nightly/wppconnect-wa.js
// @grant        none
// ==/UserScript==

(function () {
  'use strict';

  WPP.loader.onReady(function () {
    alert('Ready to use WPPConnect WA-JS');
  });

  // Your code here...
})();

​
Header field reference

Each // @field line in the ==UserScript== block controls how and where the script runs:
FieldPurpose
@nameDisplay name shown in the TamperMonkey dashboard.
@namespaceA unique URI that scopes the script. The value is arbitrary but must be present.
@versionScript version. Increment this when you update the script so TamperMonkey detects the change.
@descriptionShort description shown in the dashboard.
@authorYour name or handle.
@matchURL pattern where the script is injected. https://web.whatsapp.com/* covers every path on the WhatsApp Web domain.
@iconIcon shown in the TamperMonkey popup.
@requireURL of an external script to load before your code runs. This is where WA-JS is pulled in.
@grantGrants access to TamperMonkey APIs. none runs the script in the page’s own context, which is required so your code shares the same window.WPP object.

​
Using @require with a pinned version

The example above uses the nightly tag, which always resolves to the latest build. For a production userscript, pin a specific release to prevent unexpected breakage when a new version ships: 
// @require      https://github.com/wppconnect-team/wa-js/releases/download/4.3.0/wppconnect-wa.js
Replace 4.3.0 with the version you want. You can find all release tags on the GitHub releases page.
Pin your @require URL to a specific release tag in scripts that run in production or that other people use. The nightly tag is fine for personal experimentation but can break when WA-JS ships a breaking change.

​
Installing and running the script

1

Open the TamperMonkey dashboard

Click the TamperMonkey icon in your browser toolbar, then select Dashboard.
2

Create a new script

Click the + tab to open the script editor.
3

Paste the userscript

Delete the placeholder content and paste the userscript from the section above. Replace the alert inside WPP.loader.onReady with your own logic.
4

Save the script

Press Ctrl+S (or Cmd+S on macOS), or click File → Save.
5

Open WhatsApp Web

Navigate to https://web.whatsapp.com/. TamperMonkey injects the script automatically. Once WA-JS finishes loading, WPP.loader.onReady fires and your callback runs.

​
Working with the WPP object

Inside WPP.loader.onReady, the full WPP API is available. Replace the alert in the example with real logic: 
WPP.loader.onReady(function () {
  // Check authentication state
  console.log('Authenticated:', WPP.conn.isAuthenticated());

  // Listen for incoming messages
  WPP.on('chat.new_message', function (msg) {
    console.log('New message from', msg.from, ':', msg.body);
  });
});

​
Common use cases

Userscripts are well suited for lightweight, browser-local automation:
  • Auto-responders — listen for chat.new_message and reply to specific keywords with WPP.chat.sendTextMessage.
  • Message logging — write incoming messages to localStorage or IndexedDB for later review.
  • Quick API exploration — run Object.keys(WPP.chat).sort() in the DevTools console while the script is active to see every available function.
  • UI enhancements — inject custom buttons or styles into the WhatsApp Web interface alongside WA-JS calls.
Because the userscript runs inside the browser page, all data stays on your machine. Nothing is sent to an external server unless your own code does so explicitly.

Build docs developers (and LLMs) love

Get started for freeTalk to us