wwebjs-electron

About

A WhatsApp API client optimized for Electron applications

wwebjs-electron is a fork of whatsapp-web.js specifically optimized for use with Electron applications. It works seamlessly with puppeteer-in-electron to provide a native desktop WhatsApp experience. The library connects through WhatsApp Web using Puppeteer within Electron's BrowserView, providing access to all WhatsApp Web features while maintaining the security and performance benefits of Electron.

[!IMPORTANT] It is not guaranteed you will not be blocked by using this method. WhatsApp does not allow bots or unofficial clients on their platform, so this shouldn't be considered totally safe.

Links

• Website
• Guide (source) (work in progress)
• Documentation (source)
• WWebJS Discord
• GitHub
• npm

Installation

The module is now available on npm! npm i wwebjs-electron

Required Dependencies for Electron Integration

For proper Electron integration, you also need to install these dependencies:

npm i wwebjs-electron puppeteer-core puppeteer-in-electron

[!NOTE] Node v18+ is required.

QUICK STEPS TO UPGRADE NODE

Windows

Manual

Just get the latest LTS from the official node website.

npm

sudo npm install -g n
sudo n stable

Choco

choco install nodejs-lts

Winget

winget install OpenJS.NodeJS.LTS

Ubuntu / Debian

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - &&\
sudo apt-get install -y nodejs

Example usage

Basic Electron Implementation

const { app, BrowserWindow, BrowserView } = require('electron');
const { Client, LocalAuth } = require('wwebjs-electron');
const pie = require('puppeteer-in-electron');
const puppeteer = require('puppeteer-core');

// Initialize puppeteer-in-electron
pie.initialize(app);

app.whenReady().then(async () => {
    // Create main window
    const mainWindow = new BrowserWindow({
        width: 1200,
        height: 800,
        webPreferences: {
            nodeIntegration: false,
            contextIsolation: true
        }
    });

    // Connect browser
    const browser = await pie.connect(app, puppeteer);

    // Create BrowserView for WhatsApp
    const whatsappView = new BrowserView({
        webPreferences: {
            nodeIntegration: false,
            contextIsolation: true,
            webSecurity: false
        }
    });

    // Get Puppeteer page from BrowserView
    const page = await pie.getPage(browser, whatsappView);

    // Set user agent
    await page.setUserAgent(
        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36'
    );

    // Create WhatsApp client using the Puppeteer page
    const client = new Client({
        authStrategy: new LocalAuth(),
        page: page
    });

    client.on('qr', (qr) => {
        console.log('QR RECEIVED', qr);
        // Display QR code to user
    });

    client.on('ready', () => {
        console.log('WhatsApp Client is ready!');
    });

    client.on('message', async (msg) => {
        if (msg.body === '!ping') {
            await msg.reply('🤖 Pong!');
        }
    });

    // Add BrowserView to window
    mainWindow.addBrowserView(whatsappView);
    mainWindow.setBrowserView(whatsappView);
    
    // Set BrowserView bounds
    const { width, height } = mainWindow.getContentBounds();
    whatsappView.setBounds({ x: 0, y: 0, width, height });

    // Initialize client
    await client.initialize();
});

Standalone Usage (Compatible with original whatsapp-web.js)

const { Client, LocalAuth } = require('wwebjs-electron');

const client = new Client({
    authStrategy: new LocalAuth()
});

client.on('qr', (qr) => {
    console.log('QR RECEIVED', qr);
});

client.on('ready', () => {
    console.log('Client is ready!');
});

client.on('message', msg => {
    if (msg.body == '!ping') {
        msg.reply('pong');
    }
});

client.initialize();

Take a look at example.js for another examples with additional use cases.
For further details on saving and restoring sessions, explore the provided Authentication Strategies.

Key Differences from whatsapp-web.js

wwebjs-electron provides several enhancements specifically designed for Electron applications:

• Native Electron Integration: Works seamlessly with Electron's BrowserView and BrowserWindow
• puppeteer-in-electron Support: Optimized to work with puppeteer-in-electron for better performance
• Enhanced Security: Maintains Electron's security model while providing full WhatsApp functionality
• Desktop-First Design: Built specifically for desktop applications rather than web browsers
• Improved Resource Management: Better memory and CPU usage in Electron environments
• Custom User Agent Support: Easy configuration for desktop-specific user agents

Installation with Electron

• Install the required packages:

  npm install wwebjs-electron puppeteer-core puppeteer-in-electron
  

• Initialize puppeteer-in-electron in your main process:

  const pie = require('puppeteer-in-electron');
  pie.initialize(app);
  

• Use the provided Electron integration pattern as shown in the examples above.

Recommended Versions

For optimal compatibility, use these specific versions:

{
  "wwebjs-electron": "^1.33.2",
  "puppeteer-core": "^24.19.0", 
  "puppeteer-in-electron": "^3.0.5"
}

These versions have been tested together and provide the most stable experience.

Supported features

Feature	Status
Multi Device	✅
Send messages	✅
Receive messages	✅
Send media (images/audio/documents)	✅
Send media (video)	✅ (requires Google Chrome)
Send stickers	✅
Receive media (images/audio/video/documents)	✅
Send contact cards	✅
Send location	✅
Send buttons	❌ (DEPRECATED)
Send lists	❌ (DEPRECATED)
Receive location	✅
Message replies	✅
Join groups by invite	✅
Get invite for group	✅
Modify group info (subject, description)	✅
Modify group settings (send messages, edit info)	✅
Add group participants	✅
Kick group participants	✅
Promote/demote group participants	✅
Mention users	✅
Mention groups	✅
Mute/unmute chats	✅
Block/unblock contacts	✅
Get contact info	✅
Get profile pictures	✅
Set user status message	✅
React to messages	✅
Create polls	✅
Channels	✅
Vote in polls	🔜
Communities	🔜

Something missing? Make an issue and let us know!

Contributing

Feel free to open pull requests; we welcome contributions! However, for significant changes, it's best to open an issue beforehand. Make sure to review our contribution guidelines before creating a pull request. Before creating your own issue or pull request, always check to see if one already exists!

Supporting the project

You can support the maintainer of this project through the links below

• Support via GitHub Sponsors
• Support via PayPal
• Sign up for DigitalOcean and get $200 in credit when you sign up (Referral)

Disclaimer

This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with WhatsApp or any of its subsidiaries or its affiliates. The official WhatsApp website can be found at whatsapp.com. "WhatsApp" as well as related names, marks, emblems and images are registered trademarks of their respective owners. Also it is not guaranteed you will not be blocked by using this method. WhatsApp does not allow bots or unofficial clients on their platform, so this shouldn't be considered totally safe.

License

Copyright 2019 Pedro S Lopez

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this project except in compliance with the License.
You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.