wa-multi-session

Install the package using npm to get started with multi-session WhatsApp connectivity.

npm install wa-multi-session@latest

To use the library, you must create a new Whatsapp instance and provide an adapter for session persistence. The RedisAdapter is the default recommended adapter, but SQLiteAdapter is also supported.

You can also provide lifecycle callbacks: onConnecting, onConnected, and onDisconnected.

import { Whatsapp, RedisAdapter } from "wa-multi-session";

const whatsapp = new Whatsapp({
  adapter: new RedisAdapter({
    url: "redis://localhost:6379",
  }),

  // Optional: Add Listener/Callback
  onConnecting: (sessionId) => {
    console.log(`[${sessionId}] Connecting...`);
  },
  onConnected: (sessionId) => {
    console.log(`[${sessionId}] Connected`);
  },
  onDisconnected: (sessionId) => {
    console.log(`[${sessionId}] Disconnected`);
  },
});

Adapters can be customized during initialization:

• RedisAdapter: Supports a url for the connection and a keyPrefix to namespace keys in Redis.
• SQLiteAdapter: Supports a databasePath to specify where the .db file is stored.

// Redis with custom prefix
const adapter = new RedisAdapter({
  url: "redis://localhost:6379",
  keyPrefix: "my_app:",
});

// SQLite with custom path
const adapter = new SQLiteAdapter({
  databasePath: "my_custom_dir/database.db",
});

To use the library, instantiate the Whatsapp class. You must provide an adapter (to handle session persistence) and can optionally specify a debugLevel. If autoLoad is set to true (default), the class will automatically attempt to restart all existing sessions found in the adapter upon initialization.

import { Whatsapp } from './path-to-library';

const whatsapp = new Whatsapp({
  adapter: myAdapter, // Must implement the Adapter interface
  debugLevel: 'info', // Optional: 'silent', 'error', 'warn', 'info', 'debug'
  autoLoad: true     // Optional: defaults to true
});

Use getSQLiteSessionIds to retrieve an array of all unique session_id values currently stored in the SQLite auth_store table. This allows you to list all active WhatsApp sessions managed by the application.

import { getSQLiteSessionIds } from 'wa-multi-session/src/Store/Sqlite';

const sessionIds = await getSQLiteSessionIds();
console.log('Active sessions:', sessionIds);

Send a text message to a user or group using sendText. The to field should be a phone number string, and isGroup determines the target type.

await whatsapp.sendText({
  sessionId: 'my-session-id',
  to: '1234567890',
  isGroup: false,
  text: 'Hello, this is a test message!',
  answering: someMessageKey // Optional: to reply to a specific message
});

Use StartSessionWithPairingCodeParams when you want to connect via a phone number and pairing code instead of scanning a QR code.

Required field:

• phoneNumber: The phone number including the country code.

Available event handlers:

• onPairingCode: Triggered when the pairing code is generated.
• onQRUpdated, onConnected, onConnecting, onDisconnected, onMessageReceived, onMessageUpdated: Same as StartSessionParams.
• store: Optional LegacyStore for session persistence.

const params: StartSessionWithPairingCodeParams = {
  phoneNumber: '861234567890',
  onPairingCode: (code) => console.log('Your pairing code is:', code),
  onConnected: () => console.log('Connected via pairing code!')
};

Use sendDocument to send files like PDFs or other documents. Unlike other media functions, you must provide a filename string. The function will automatically determine the mimetype based on the file extension.

await sendDocument({
  sessionId: 'my-session',
  to: '1234567890',
  media: documentBuffer,
  filename: 'report.pdf',
  text: 'Here is the report',
  isGroup: false
});

The library provides specialized methods for different media types. For most methods, media can be either a local file path/buffer or a URL string.

// Send Image
await whatsapp.sendImage({
  sessionId: 'my-session-id',
  to: '1234567890',
  isGroup: false,
  media: 'https://example.com/image.jpg',
  text: 'Check this out!'
});

// Send Document (requires filename for mimetype detection)
await whatsapp.sendDocument({
  sessionId: 'my-session-id',
  to: '1234567890',
  isGroup: false,
  media: './files/report.pdf',
  filename: 'report.pdf',
  text: 'Here is your file'
});

// Send Audio as Voice Note
await whatsapp.sendAudio({
  sessionId: 'my-session-id',
  to: '1234567890',
  isGroup: false,
  media: './audio.mp3',
  asVoiceNote: true
});