RemoteAuth

RemoteAuth saves sessions to a remote store, a database or cloud storage service. This makes it suitable for Docker, Kubernetes, serverless, and any setup where the local filesystem cannot be trusted to persist data.

When to Use RemoteAuth

Your app runs in a container that can be recreated
You need more than one app instance sharing the same account
You deploy to a platform without persistent disk (e.g. Heroku, Railway, serverless)

Installation

RemoteAuth itself is built in, but it needs three helper packages and a store adapter:

npm install fs-extra unzipper archiver

Then install the adapter for your storage backend:

# MongoDB
npm install wwebjs-mongo mongoose

# AWS S3
npm install wwebjs-aws-s3 aws-sdk

With MongoDB

const { Client, RemoteAuth } = require('whatsapp-web.js')
const { MongoStore } = require('wwebjs-mongo')
const mongoose = require('mongoose')

async function start() {
  await mongoose.connect(process.env.MONGODB_URL)

  const client = new Client({
    authStrategy: new RemoteAuth({
      store: new MongoStore({ mongoose }),
      backupSyncIntervalMs: 600000, // Sync every 10 minutes
    }),
  })

  client.on('qr', qr => {
    console.log('Scan QR code')
  })

  client.on('ready', () => {
    console.log('Ready!')
  })

  client.initialize()
}

start()

Options

new RemoteAuth({
  store, // Required, the storage adapter instance
  clientId: 'my-app', // Unique ID when running multiple instances
  dataPath: './sessions', // Temporary local path during sync
  backupSyncIntervalMs: 600000, // How often to sync (minimum 60000 ms)
})

`backupSyncIntervalMs`

Sessions are synced to the remote store on an interval while the app is running. The minimum allowed value is 60000 (1 minute). For most apps, 5–10 minutes (300000–600000) is a good balance.

`clientId`

Lets you run multiple apps against the same remote store without them overwriting each other's sessions:

const clientA = new Client({
  authStrategy: new RemoteAuth({
    store: myStore,
    clientId: 'app-a',
  }),
})

const clientB = new Client({
  authStrategy: new RemoteAuth({
    store: myStore,
    clientId: 'app-b',
  }),
})

Session Lifecycle Events

client.on('remote_session_saved', () => {
  console.log('Session backed up to remote store')
})

client.on('disconnected', reason => {
  console.log('Disconnected:', reason)
  // Re-initialize or exit depending on your strategy
})

Best Practices

Store database credentials in environment variables, never in source code
Set backupSyncIntervalMs low enough that a crash won't lose too much session state
Handle disconnected to restart or alert on unexpected disconnections