whatsapp-web.js

# Authentication

By default, whatsapp-web.js does not save session information. This means that you would have to scan the QR code to reauthenticate every time you restart the client. If you'd like to persist the session, you can pass an authStrategy as a client option. The library provides a few authentication strategies to choose from, but you can also choose to extend them or build your own.

For most cases we recommend using the LocalAuth strategy or the RemoteAuth strategy for more flexibility.

# NoAuth Strategy

This is the default authentication strategy used when you don't provide one. It does not provide any means of saving and restoring sessions. You can set this if you'd like to be explicit about getting a fresh session every time the client is restarted:

const { Client, NoAuth } = require('whatsapp-web.js');

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

INFO

The code above is equivalent to:

const { Client } = require('whatsapp-web.js');
const client = new Client();

# LocalAuth Strategy

IMPORTANT

LocalAuth requires a persistent filesystem to be able to restore sessions. This means that out of the box it is not compatible with hosts that provide ephemeral file systems, such as Heroku.

This strategy enables session-restore functionality by passing a persistent user data directory (opens new window) to the browser. This means that other data, such as message history, will also be persisted and restored:

const { Client, LocalAuth } = require('whatsapp-web.js');

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

By default, the relevant session files are stored under a .wwebjs_auth directory, but you can change this by specifying the dataPath option when instantiating LocalAuth:

const { Client, LocalAuth } = require('whatsapp-web.js');

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

This will create a yourFolderName folder with a stored session.

# Multiple Sessions

If you're using multiple clients belonging to different sessions, you can pass a clientId to segregate them:

const { Client, LocalAuth } = require('whatsapp-web.js');

const client1 = new Client({
    authStrategy: new LocalAuth({ clientId: 'client-one' })
});

const client2 = new Client({
    authStrategy: new LocalAuth({ clientId: 'client-two' })
});

This will create a wwebjs_auth folder with folders session-client-one and session-client-two in it respectively.

# RemoteAuth Strategy

(opens new window)

The RemoteAuth strategy allows you to save the WhatsApp session into a remote database. Instead of depending on a persistent file system, RemoteAuth is able to save, extract & restore sessions efficiently. It also generates periodic backups so that the saved session is always on sync and this avoids data-loss.

# Remote Stores

Stores are external-independent database plugins that allow storing the session into different databases. New stores will need to implement the following interface in order to work with RemoteAuth:

You can implement your own store or use already implemented ones.

# Cross Platform Compatibility

Status OS
✅ MacOS
✅ Ubuntu 20.04 (Heroku Compatible)
✅ Windows

# Implemented Stores

There is a couple of already implemented stores that are ready to use:

  1. MongoDB Store
  2. AWS S3 Store

# MongoDB Store

(opens new window)

To use this authentication strategy you need to install the wwebjs-mongo module in your terminal first:

# Usage Example

const { Client, RemoteAuth } = require('whatsapp-web.js');

// Require database
const { MongoStore } = require('wwebjs-mongo');
const mongoose = require('mongoose');

// Load the session data
mongoose.connect(process.env.MONGODB_URI).then(() => {
    const store = new MongoStore({ mongoose: mongoose });
    const client = new Client({
        authStrategy: new RemoteAuth({
            store: store,
            backupSyncIntervalMs: 300000
        })
    });

    client.initialize();
});

After the initial QR scan to link the device, RemoteAuth takes about 1 minute to successfully save the WhatsApp session into the remote database, therefore the ready event does not mean the session has been saved yet.

In order to listen to this event, you can now use the following:

client.on('remote_session_saved', () => {
    // Do Stuff...
});

# AWS S3 Store

(opens new window)

To use this authentication strategy you need to install the wwebjs-aws-s3 module in your terminal first:

# Usage Example

const { Client, RemoteAuth } = require('whatsapp-web.js');
const { AwsS3Store } = require('wwebjs-aws-s3');
const {
    S3Client,
    PutObjectCommand,
    HeadObjectCommand,
    GetObjectCommand,
    DeleteObjectCommand
} = require('@aws-sdk/client-s3');

const s3 = new S3Client({
    region: 'AWS_REGION',
    credentials: {
        accessKeyId: 'AWS_ACCESS_KEY_ID',
        secretAccessKey: 'AWS_SECRET_ACCESS_KEY'
    }
});

const putObjectCommand = PutObjectCommand;
const headObjectCommand = HeadObjectCommand;
const getObjectCommand = GetObjectCommand;
const deleteObjectCommand = DeleteObjectCommand;

const store = new AwsS3Store({
    bucketName: 'example-bucket',
    remoteDataPath: 'example/path/',
    s3Client: s3,
    putObjectCommand,
    headObjectCommand,
    getObjectCommand,
    deleteObjectCommand
});

const client = new Client({
    authStrategy: new RemoteAuth({
        clientId: 'yourSessionName',
        dataPath: './.wwebjs_auth',
        store: store,
        backupSyncIntervalMs: 600000
    })
});

client.initialize();

← Handling Attachments →