Skip to main content

Class: Client

Defined in: client/Client.ts:69

WhatsApp Web client without a browser, with a built-in command router.

Example​

const wa = createClient({ session: 'my-bot' });
wa.command('ping', (ctx) => ctx.reply('pong 🏓'));
wa.hears(/hola/i, (ctx) => ctx.reply('hi!'));
wa.on('ready', (me) => console.log('Connected:', me.number));
await wa.start();

Extends​

  • EventEmitter

Constructors​

Constructor​

new Client(options?): Client

Defined in: client/Client.ts:85

Parameters​

options?​

ClientOptions = {}

Returns​

Client

Overrides​

EventEmitter.constructor

Properties​

info?​

optional info?: ClientInfo

Defined in: client/Client.ts:83

Account information once connected.

Accessors​

commandPrefixes​

Get Signature​

get commandPrefixes(): string[]

Defined in: client/Client.ts:116

Configured command prefixes (used by Context).

Returns​

string[]

socket​

Get Signature​

get socket(): object

Defined in: client/Client.ts:121

Raw Baileys socket (low-level access). Throws if there is no connection.

Returns​

object

Methods​

addGroupParticipants()​

addGroupParticipants(jid, participants): Promise<object[]>

Defined in: client/Client.ts:759

Parameters​

jid​

string

participants​

string | string[]

Returns​

Promise<object[]>

blockUser()​

blockUser(jid): Promise<void>

Defined in: client/Client.ts:683

Blocks a contact.

Parameters​

jid​

string

Returns​

Promise<void>

chat()​

chat(id, name?): Chat

Defined in: client/Client.ts:582

Returns a fluent handle for a chat.

Parameters​

id​

string

name?​

string

Returns​

Chat

clearHistory()​

clearHistory(chatId?): void

Defined in: client/Client.ts:605

Clears message history for one chat, or all chats.

Parameters​

chatId?​

string

Returns​

void

command()​

command(name, handler): this

Defined in: client/Client.ts:340

Registers a handler for one or more commands (!ping, /start, …).

Parameters​

name​

string | string[]

handler​

Handler

Returns​

this

conversation()​

conversation(id, expectedSender?): Conversation

Defined in: client/Client.ts:590

Returns a rich per-user handle: send + persistent state + history + ask. expectedSender (used by ctx.conversation) scopes ask to a participant.

Parameters​

id​

string

expectedSender?​

string

Returns​

Conversation

createGroup()​

createGroup(subject, participants): Promise<GroupMetadata>

Defined in: client/Client.ts:745

Creates a group with the given subject and participants.

Parameters​

subject​

string

participants​

string[]

Returns​

Promise<GroupMetadata>

deleteMessage()​

deleteMessage(chatId, key): Promise<void>

Defined in: client/Client.ts:561

Deletes a message for everyone.

Parameters​

chatId​

string

key​

WAMessageKey

Returns​

Promise<void>

demoteGroupParticipants()​

demoteGroupParticipants(jid, participants): Promise<object[]>

Defined in: client/Client.ts:771

Parameters​

jid​

string

participants​

string | string[]

Returns​

Promise<object[]>

destroy()​

destroy(): Promise<void>

Defined in: client/Client.ts:821

Closes the connection without unlinking the device.

Returns​

Promise<void>

editMessage()​

editMessage(chatId, key, newText): Promise<Message>

Defined in: client/Client.ts:566

Edits a previously sent (own) message.

Parameters​

chatId​

string

key​

WAMessageKey

newText​

string

Returns​

Promise<Message>

emit()​

emit<K>(event, ...args): boolean

Defined in: client/Client.ts:870

Synchronously calls each of the listeners registered for the event named eventName, in the order they were registered, passing the supplied arguments to each.

Returns true if the event had listeners, false otherwise.

import { EventEmitter } from 'node:events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

console.log(myEmitter.listeners('event'));

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// [
//   [Function: firstListener],
//   [Function: secondListener],
//   [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener

Type Parameters​

K​

K extends keyof ClientEvents

Parameters​

event​

K

args​

...ClientEvents[K]

Returns​

boolean

Since​

v0.1.26

Overrides​

EventEmitter.emit

forwardMessage()​

forwardMessage(to, message, options?): Promise<Message>

Defined in: client/Client.ts:571

Forwards a message to another chat.

Parameters​

to​

string

message​

WAMessage

options?​

MiscMessageGenerationOptions

Returns​

Promise<Message>

getBlocklist()​

getBlocklist(): Promise<string[]>

Defined in: client/Client.ts:693

Returns the list of blocked JIDs.

Returns​

Promise<string[]>

getGroupInviteLink(jid): Promise<string>

Defined in: client/Client.ts:790

Current invite link of a group (https://chat.whatsapp.com/…).

Parameters​

jid​

string

Returns​

Promise<string>

getGroupMetadata()​

getGroupMetadata(jid): Promise<GroupMetadata>

Defined in: client/Client.ts:740

Full metadata of a group.

Parameters​

jid​

string

Returns​

Promise<GroupMetadata>

getLid()​

getLid(number): Promise<string | undefined>

Defined in: client/Client.ts:616

Gets the LID associated with a phone number, if WhatsApp exposes it.

Parameters​

number​

string

Returns​

Promise<string | undefined>

getProfilePictureUrl()​

getProfilePictureUrl(jid, highRes?): Promise<string | undefined>

Defined in: client/Client.ts:651

Profile picture URL of a chat/contact, or undefined if not available.

Parameters​

jid​

string

highRes?​

boolean = false

Returns​

Promise<string | undefined>

getStatus()​

getStatus(jid): Promise<string | undefined>

Defined in: client/Client.ts:677

Fetches a contact's status/about text, if visible.

Parameters​

jid​

string

Returns​

Promise<string | undefined>

group()​

group(id): Group

Defined in: client/Client.ts:735

Returns a fluent handle for a group.

Parameters​

id​

string

Returns​

Group

hears()​

hears(trigger, handler): this

Defined in: client/Client.ts:349

Registers a handler that fires when the text matches a pattern.

Parameters​

trigger​

Trigger | Trigger[]

handler​

Handler

Returns​

this

historyFor()​

historyFor(chatId): Message[]

Defined in: client/Client.ts:600

Recent in-memory message history for a chat.

Parameters​

chatId​

string

Returns​

Message[]

initialize()​

initialize(): Promise<void>

Defined in: client/Client.ts:137

Starts the connection. Emits qr (or pairing_code) the first time and ready once it is operational.

Returns​

Promise<void>

isRegisteredUser()​

isRegisteredUser(number): Promise<boolean>

Defined in: client/Client.ts:610

Is the number registered on WhatsApp?

Parameters​

number​

string

Returns​

Promise<boolean>

joinGroupViaLink(linkOrCode): Promise<string | undefined>

Defined in: client/Client.ts:802

Joins a group via an invite link or code. Returns the group JID.

Parameters​

linkOrCode​

string

Returns​

Promise<string | undefined>

leaveGroup()​

leaveGroup(jid): Promise<void>

Defined in: client/Client.ts:785

Leaves a group.

Parameters​

jid​

string

Returns​

Promise<void>

logout()​

logout(): Promise<void>

Defined in: client/Client.ts:810

Logs out of WhatsApp and deletes the local credentials.

Returns​

Promise<void>

messages()​

messages(options?): AsyncIterableIterator<Context>

Defined in: client/Client.ts:207

Async iterator over incoming messages (not your own). Lets you handle messages with a linear for await loop instead of registering callbacks. Messages are buffered between iterations, so none are lost.

Parameters​

options?​
signal?​

AbortSignal

Returns​

AsyncIterableIterator<Context>

Example​

for await (const ctx of wa.messages()) {
  if (ctx.command === 'ping') await ctx.reply('pong');
}

next()​

next<K>(event, options?): Promise<ClientEvents[K][0]>

Defined in: client/Client.ts:220

Awaits the next occurrence of an event (one-shot promise).

Type Parameters​

K​

K extends keyof ClientEvents

Parameters​

event​

K

options?​
signal?​

AbortSignal

Returns​

Promise<ClientEvents[K][0]>

off()​

off<K>(event, listener): this

Defined in: client/Client.ts:863

Alias for emitter.removeListener().

Type Parameters​

K​

K extends keyof ClientEvents

Parameters​

event​

K

listener​

(...args) => void

Returns​

this

Since​

v10.0.0

Overrides​

EventEmitter.off

on()​

on<K>(event, listener): this

Defined in: client/Client.ts:849

Adds the listener function to the end of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

server.on('connection', (stream) => {
  console.log('someone connected!');
});

Returns a reference to the EventEmitter, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The emitter.prependListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

Type Parameters​

K​

K extends keyof ClientEvents

Parameters​

event​

K

listener​

(...args) => void

The callback function

Returns​

this

Since​

v0.1.101

Overrides​

EventEmitter.on

once()​

once<K>(event, listener): this

Defined in: client/Client.ts:856

Adds a one-time listener function for the event named eventName. The next time eventName is triggered, this listener is removed and then invoked.

server.once('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

Returns a reference to the EventEmitter, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The emitter.prependOnceListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

Type Parameters​

K​

K extends keyof ClientEvents

Parameters​

event​

K

listener​

(...args) => void

The callback function

Returns​

this

Since​

v0.3.0

Overrides​

EventEmitter.once

promoteGroupParticipants()​

promoteGroupParticipants(jid, participants): Promise<object[]>

Defined in: client/Client.ts:767

Parameters​

jid​

string

participants​

string | string[]

Returns​

Promise<object[]>

react()​

react(to, key, emoji): Promise<void>

Defined in: client/Client.ts:517

Reacts to a message with an emoji (empty string to remove the reaction).

Parameters​

to​

string

key​

WAMessageKey

emoji​

string

Returns​

Promise<void>

removeGroupParticipants()​

removeGroupParticipants(jid, participants): Promise<object[]>

Defined in: client/Client.ts:763

Parameters​

jid​

string

participants​

string | string[]

Returns​

Promise<object[]>

removeProfilePicture()​

removeProfilePicture(jid?): Promise<void>

Defined in: client/Client.ts:662

Removes a profile picture (your own by default).

Parameters​

jid?​

string

Returns​

Promise<void>

revokeGroupInviteLink(jid): Promise<string>

Defined in: client/Client.ts:796

Revokes a group's invite link and returns the new one.

Parameters​

jid​

string

Returns​

Promise<string>

send()​

send(to, content, options?): Promise<Message>

Defined in: client/Client.ts:393

Sends raw Baileys content (or text) to a chat.

Parameters​

to​

string

content​

string | AnyMessageContent

options?​

MiscMessageGenerationOptions = {}

Returns​

Promise<Message>

sendAudio()​

sendAudio(to, source, options?): Promise<Message>

Defined in: client/Client.ts:424

Parameters​

to​

string

source​

MediaSource

options?​

AudioOptions = {}

Returns​

Promise<Message>

sendContact()​

sendContact(to, contacts, options?): Promise<Message>

Defined in: client/Client.ts:542

Sends one or more contact cards (vCards).

Parameters​

to​

string

contacts​

ContactCard | ContactCard[]

options?​

MiscMessageGenerationOptions

Returns​

Promise<Message>

sendDocument()​

sendDocument(to, source, options?): Promise<Message>

Defined in: client/Client.ts:443

Parameters​

to​

string

source​

MediaSource

options?​

DocumentOptions = {}

Returns​

Promise<Message>

sendFromLink(to, link, options?): Promise<Message>

Defined in: client/Client.ts:488

Sends whatever a link points to, auto-detecting the media kind (image/video/audio/document) from the extension or Content-Type. Works with any http(s) URL, including S3 public or presigned URLs, or a local path. Pass type to skip detection.

Parameters​

to​

string

string

options?​

SendFromLinkOptions = {}

Returns​

Promise<Message>

Example​

await wa.sendFromLink('34600112233', 'https://my-bucket.s3.amazonaws.com/report.pdf');
await wa.sendFromLink('34600112233', 'https://cdn.example.com/clip.mp4', { caption: 'look' });

sendImage()​

sendImage(to, source, options?): Promise<Message>

Defined in: client/Client.ts:412

Parameters​

to​

string

source​

MediaSource

options?​

CaptionOptions = {}

Returns​

Promise<Message>

sendLocation()​

sendLocation(to, location, options?): Promise<Message>

Defined in: client/Client.ts:457

Parameters​

to​

string

location​

LocationInput

options?​

MiscMessageGenerationOptions

Returns​

Promise<Message>

sendPoll()​

sendPoll(to, poll, options?): Promise<Message>

Defined in: client/Client.ts:522

Sends a poll.

Parameters​

to​

string

poll​

PollInput

options?​

MiscMessageGenerationOptions

Returns​

Promise<Message>

sendSticker()​

sendSticker(to, source, options?): Promise<Message>

Defined in: client/Client.ts:533

Sends a sticker (a WebP image works best).

Parameters​

to​

string

source​

MediaSource

options?​

MiscMessageGenerationOptions

Returns​

Promise<Message>

sendText()​

sendText(to, text, options?): Promise<Message>

Defined in: client/Client.ts:407

Parameters​

to​

string

text​

string

options?​

TextOptions = {}

Returns​

Promise<Message>

sendVideo()​

sendVideo(to, source, options?): Promise<Message>

Defined in: client/Client.ts:418

Parameters​

to​

string

source​

MediaSource

options?​

CaptionOptions = {}

Returns​

Promise<Message>

sendVoice()​

sendVoice(to, source, options?): Promise<Message>

Defined in: client/Client.ts:435

Voice note (audio with ptt: true).

Parameters​

to​

string

source​

MediaSource

options?​

MiscMessageGenerationOptions = {}

Returns​

Promise<Message>

setName()​

setName(name): Promise<void>

Defined in: client/Client.ts:667

Updates your display name.

Parameters​

name​

string

Returns​

Promise<void>

setPresence()​

setPresence(state, to?): Promise<void>

Defined in: client/Client.ts:638

Updates your presence, optionally scoped to a chat.

Parameters​

state​

"unavailable" | "available" | "composing" | "recording" | "paused"

to?​

string

Returns​

Promise<void>

setProfilePicture()​

setProfilePicture(source, jid?): Promise<void>

Defined in: client/Client.ts:656

Sets a profile picture (your own by default, or a group you admin).

Parameters​

source​

MediaSource

jid?​

string

Returns​

Promise<void>

setStatus()​

setStatus(status): Promise<void>

Defined in: client/Client.ts:672

Updates your status/about text.

Parameters​

status​

string

Returns​

Promise<void>

start()​

start(): Promise<void>

Defined in: client/Client.ts:129

Starts the connection (alias of initialize).

Returns​

Promise<void>

stateFor()​

stateFor(chatId): ConversationState

Defined in: client/Client.ts:595

The persistent state for a chat.

Parameters​

chatId​

string

Returns​

ConversationState

stream()​

stream<K>(event, options?): AsyncIterableIterator<ClientEvents[K][0]>

Defined in: client/Client.ts:212

Async iterator over any client event ('qr', 'reaction', …).

Type Parameters​

K​

K extends keyof ClientEvents

Parameters​

event​

K

options?​
signal?​

AbortSignal

Returns​

AsyncIterableIterator<ClientEvents[K][0]>

subscribeToPresence()​

subscribeToPresence(jid): Promise<void>

Defined in: client/Client.ts:646

Subscribes to a contact's presence so 'presence' events start arriving.

Parameters​

jid​

string

Returns​

Promise<void>

unblockUser()​

unblockUser(jid): Promise<void>

Defined in: client/Client.ts:688

Unblocks a contact.

Parameters​

jid​

string

Returns​

Promise<void>

updateGroupDescription()​

updateGroupDescription(jid, description): Promise<void>

Defined in: client/Client.ts:755

Updates a group's description.

Parameters​

jid​

string

description​

string

Returns​

Promise<void>

updateGroupSubject()​

updateGroupSubject(jid, subject): Promise<void>

Defined in: client/Client.ts:750

Updates a group's subject (name).

Parameters​

jid​

string

subject​

string

Returns​

Promise<void>

use()​

use(middleware): this

Defined in: client/Client.ts:334

Registers a global middleware (runs for every incoming message).

Parameters​

middleware​

Middleware

Returns​

this

waitForMessage()​

waitForMessage(filter?, options?): Promise<Context>

Defined in: client/Client.ts:706

Waits for the next incoming message that matches filter (any message by default). Useful for question→answer flows.

Parameters​

filter?​

(ctx) => boolean

options?​
signal?​

AbortSignal

timeoutMs?​

number

Returns​

Promise<Context>

Throws​

if it times out or the signal aborts before a match.

waitUntilReady()​

waitUntilReady(timeoutMs?): Promise<ClientInfo>

Defined in: client/Client.ts:175

Waits until the connection is ready.

Parameters​

timeoutMs?​

number

Returns​

Promise<ClientInfo>