Property

new Client(options)

Parameters

Name Type Optional Description

options

 

 

Client options

Values in options have the following properties:

Name Type Optional Description

authStrategy

 

 

Determines how to save and restore sessions. Will use LegacySessionAuth if options.session is set. Otherwise, NoAuth will be used.

webVersion

 

 

The version of WhatsApp Web to use. Use options.webVersionCache to configure how the version is retrieved.

webVersionCache

 

 

Determines how to retrieve the WhatsApp Web version. Defaults to a local cache (LocalWebCache) that falls back to latest if the requested version is not found.

authTimeoutMs

 

 

Timeout for authentication selector in puppeteer

puppeteer

 

 

Puppeteer launch options. View docs here: https://github.com/puppeteer/puppeteer/

qrMaxRetries

 

 

How many times should the qrcode be refreshed before giving up

restartOnAuthFail

 

 

@deprecated This option should be set directly on the LegacySessionAuth.

session

 

 

@deprecated Only here for backwards-compatibility. You should move to using LocalAuth, or set the authStrategy to LegacySessionAuth explicitly.

takeoverOnConflict

 

 

If another whatsapp web session is detected (another browser), take over the session in the current browser

takeoverTimeoutMs

 

 

How much time to wait before taking over the session

userAgent

 

 

User agent to use in puppeteer

ffmpegPath

 

 

Ffmpeg path to use when formating videos to webp while sending stickers

bypassCSP

 

 

Sets bypassing of page's Content-Security-Policy.

proxyAuthentication

 

 

Proxy Authentication object.

Extends
EventEmitter
Fires
Client#event:qr
Client#event:authenticated
Client#event:auth_failure
Client#event:ready
Client#event:message
Client#event:message_ack
Client#event:message_create
Client#event:message_revoke_me
Client#event:message_revoke_everyone
Client#event:media_uploaded
Client#event:group_join
Client#event:group_leave
Client#event:group_update
Client#event:disconnected
Client#event:change_state
Client#event:contact_changed
Client#event:group_admin_changed
Client#event:group_membership_request

Property

info  ClientInfo

Current connection information

Methods

async

acceptGroupV4Invite(inviteInfo) → Promise containing Object

Accepts a private invitation to join a group

Parameter

Name Type Optional Description

inviteInfo

object

 

Invite V4 Info

Returns

Promise containing Object 

async

acceptInvite(inviteCode) → Promise containing string

Accepts an invitation to join a group

Parameter

Name Type Optional Description

inviteCode

string

 

Invitation code

Returns

Promise containing string 

Id of the joined Chat

async

addOrRemoveLabels(labelIds, chatIds) → Promise containing void

Change labels in chats

Parameters

Name Type Optional Description

labelIds

Array of (number or string)

 

chatIds

Array of string

 

Returns

Promise containing void 

async

approveGroupMembershipRequests(groupId, options) → Promise containing Array of MembershipRequestActionResult

Approves membership requests if any

Parameters

Name Type Optional Description

groupId

string

 

The group ID to get the membership request for

options

MembershipRequestActionOptions

 

Options for performing a membership request action

Returns

Promise containing Array of MembershipRequestActionResult 

Returns an array of requester IDs whose membership requests were approved and an error for each requester, if any occurred during the operation. If there are no requests, an empty array will be returned

async

archiveChat() → boolean

Enables and returns the archive state of the Chat

Returns

boolean 

async

createGroup(title, participants, options) → Promise containing (CreateGroupResult or string)

Creates a new group

Parameters

Name Type Optional Description

title

string

 

Group title

participants

(string, Contact, Array of (Contact or string), or undefined)

 

A single Contact object or an ID as a string or an array of Contact objects or contact IDs to add to the group

options

CreateGroupOptions

 

An object that handles options for group creation

Returns

Promise containing (CreateGroupResult or string) 

Object with resulting data or an error message as a string

async

deleteProfilePicture() → Promise containing boolean

Deletes the current user's profile picture.

Returns

Promise containing boolean 

Returns true if the picture was properly deleted.

async

destroy()

Closes the client

async

getBlockedContacts() → Promise containing Array of Contact

Gets all blocked contacts by host account

Returns

Promise containing Array of Contact 

async

getChatById(chatId) → Promise containing Chat

Get chat instance by ID

Parameter

Name Type Optional Description

chatId

string

 

Returns

Promise containing Chat 

async

getChatLabels(chatId) → Promise containing Array of Label

Get all Labels assigned to a chat

Parameter

Name Type Optional Description

chatId

string

 

Returns

Promise containing Array of Label 

async

getChats() → Promise containing Array of Chat

Get all current chat instances

Returns

Promise containing Array of Chat 

async

getChatsByLabelId(labelId) → Promise containing Array of Chat

Get all Chats for a specific Label

Parameter

Name Type Optional Description

labelId

string

 

Returns

Promise containing Array of Chat 

async

getCommonGroups(contactId) → Promise containing Array of WAWebJS.ChatId

Gets the Contact's common groups with you. Returns empty array if you don't have any common group.

Parameter

Name Type Optional Description

contactId

string

 

the whatsapp user's ID (_serialized format)

Returns

Promise containing Array of WAWebJS.ChatId 

async

getContactById(contactId) → Promise containing Contact

Get contact instance by ID

Parameter

Name Type Optional Description

contactId

string

 

Returns

Promise containing Contact 

async

getContacts() → Promise containing Array of Contact

Get all current contact instances

Returns

Promise containing Array of Contact 

async

getCountryCode(number) → Promise containing string

Get the country code of a WhatsApp ID.

Parameter

Name Type Optional Description

number

string

 

Number or ID

Returns

Promise containing string 

async

getFormattedNumber(number) → Promise containing string

Get the formatted number of a WhatsApp ID.

Parameter

Name Type Optional Description

number

string

 

Number or ID

Returns

Promise containing string 

async

getGroupMembershipRequests(groupId) → Promise containing Array of GroupMembershipRequest

Gets an array of membership requests

Parameter

Name Type Optional Description

groupId

string

 

The ID of a group to get membership requests for

Returns

Promise containing Array of GroupMembershipRequest 

An array of membership requests

async

getInviteInfo(inviteCode) → Promise containing object

Returns an object with information about the invite code's group

Parameter

Name Type Optional Description

inviteCode

string

 

Returns

Promise containing object 

Invite information

async

getLabelById(labelId) → Promise containing Label

Get Label instance by ID

Parameter

Name Type Optional Description

labelId

string

 

Returns

Promise containing Label 

async

getLabels() → Promise containing Array of Label

Get all current Labels

Returns

Promise containing Array of Label 

async

getNumberId(number) → Promise containing (Object or null)

Get the registered WhatsApp ID for a number. Will return null if the number is not registered on WhatsApp.

Parameter

Name Type Optional Description

number

string

 

Number or ID ("@c.us" will be automatically appended if not specified)

Returns

Promise containing (Object or null) 

async

getProfilePicUrl(contactId) → Promise containing string

Returns the contact ID's profile picture URL, if privacy settings allow it

Parameter

Name Type Optional Description

contactId

string

 

the whatsapp user's ID

Returns

Promise containing string 

async

getState() → WAState

Gets the current connection state for the client

Returns

WAState 

async

getWWebVersion() → Promise containing string

Returns the version of WhatsApp Web currently being run

Returns

Promise containing string 

async

initialize()

Sets up events and requirements, kicks off authentication request

async

isRegisteredUser(id) → Promise containing Boolean

Check if a given ID is registered in whatsapp

Parameter

Name Type Optional Description

id

string

 

the whatsapp user's ID

Returns

Promise containing Boolean 

async

logout()

Logs out the client, closing the current session

async

markChatUnread(chatId)

Mark the Chat as unread

Parameter

Name Type Optional Description

chatId

string

 

ID of the chat that will be marked as unread

async

muteChat(chatId, unmuteDate)

Mutes this chat forever, unless a date is specified

Parameters

Name Type Optional Description

chatId

string

 

ID of the chat that will be muted

unmuteDate

Date

 

Date when the chat will be unmuted, leave as is to mute forever

Value can be null.

async

pinChat() → Promise containing boolean

Pins the Chat

Returns

Promise containing boolean 

New pin state. Could be false if the max number of pinned chats was reached.

async

rejectGroupMembershipRequests(groupId, options) → Promise containing Array of MembershipRequestActionResult

Rejects membership requests if any

Parameters

Name Type Optional Description

groupId

string

 

The group ID to get the membership request for

options

MembershipRequestActionOptions

 

Options for performing a membership request action

Returns

Promise containing Array of MembershipRequestActionResult 

Returns an array of requester IDs whose membership requests were rejected and an error for each requester, if any occurred during the operation. If there are no requests, an empty array will be returned

async

resetState()

Force reset of connection state for the client

async

searchMessages(query[, options]) → Promise containing Array of Message

Searches for messages

Parameters

Name Type Optional Description

query

string

 

options

Object

Yes

Values in options have the following properties:

Name Type Optional Description

page

number

Yes

limit

number

Yes

chatId

string

Yes

Returns

Promise containing Array of Message 

async

sendMessage(chatId, content[, options]) → Promise containing Message

Send a message to a specific chatId

Parameters

Name Type Optional Description

chatId

string

 

content

(string, MessageMedia, Location, Poll, Contact, Array of Contact, Buttons, or List)

 

options

MessageSendOptions

Yes

Options used when sending the message

Returns

Promise containing Message 

Message that was just sent

async

sendPresenceAvailable()

Marks the client as online

async

sendPresenceUnavailable()

Marks the client as unavailable

async

sendSeen(chatId) → Promise containing boolean

Mark as seen for the Chat

Parameter

Name Type Optional Description

chatId

string

 

Returns

Promise containing boolean 

result

async

setDisplayName(displayName) → Promise containing Boolean

Sets the current user's display name. This is the name shown to WhatsApp users that have not added you as a contact beside your number in groups and in your profile.

Parameter

Name Type Optional Description

displayName

string

 

New display name

Returns

Promise containing Boolean 

async

setProfilePicture(media) → Promise containing boolean

Sets the current user's profile picture.

Parameter

Name Type Optional Description

media

MessageMedia

 

Returns

Promise containing boolean 

Returns true if the picture was properly updated.

async

setStatus(status)

Sets the current user's status message

Parameter

Name Type Optional Description

status

string

 

New status message

async

unarchiveChat() → boolean

Changes and returns the archive state of the Chat

Returns

boolean 

async

unmuteChat(chatId)

Unmutes the Chat

Parameter

Name Type Optional Description

chatId

string

 

ID of the chat that will be unmuted

async

unpinChat() → Promise containing boolean

Unpins the Chat

Returns

Promise containing boolean 

New pin state

Events

auth_failure

Emitted when there has been an error while trying to restore an existing session

Parameter

Name Type Optional Description

message

string

 

authenticated

Emitted when authentication is successful

change_battery

Emitted when the battery percentage for the attached device changes. Will not be sent if using multi-device.

Parameters

Name Type Optional Description

batteryInfo

object

 

Values in batteryInfo have the following properties:

Name Type Optional Description

battery

number

 

The current battery percentage

plugged

boolean

 

Indicates if the phone is plugged in (true) or not (false)

Deprecated

change_state

Emitted when the connection state changes

Parameter

Name Type Optional Description

state

WAState

 

the new connection state

chat_archived

Emitted when a chat is archived/unarchived

Parameters

Name Type Optional Description

chat

Chat

 

currState

boolean

 

prevState

boolean

 

chat_removed

Emitted when a chat is removed

Parameter

Name Type Optional Description

chat

Chat

 

contact_changed

Emitted when a contact or a group participant changes their phone number.

Parameters

Name Type Optional Description

message

Message

 

Message with more information about the event.

oldId

String

 

The user's id (an old one) who changed their phone number and who triggered the notification.

newId

String

 

The user's new id after the change.

isContact

Boolean

 

Indicates if a contact or a group participant changed their phone number.

disconnected

Emitted when the client has been disconnected

Parameter

Name Type Optional Description

reason

(WAState or "NAVIGATION")

 

reason that caused the disconnect

group_admin_changed

Emitted when a current user is promoted to an admin or demoted to a regular user.

Parameter

Name Type Optional Description

notification

GroupNotification

 

GroupNotification with more information about the action

group_join

Emitted when a user joins the chat via invite link or is added by an admin.

Parameter

Name Type Optional Description

notification

GroupNotification

 

GroupNotification with more information about the action

group_leave

Emitted when a user leaves the chat or is removed by an admin.

Parameter

Name Type Optional Description

notification

GroupNotification

 

GroupNotification with more information about the action

group_membership_request

Emitted when some user requested to join the group that has the membership approval mode turned on

Parameters

Name Type Optional Description

notification

GroupNotification

 

GroupNotification with more information about the action

Values in notification have the following properties:

Name Type Optional Description

chatId

string

 

The group ID the request was made for

author

string

 

The user ID that made a request

timestamp

number

 

The timestamp the request was made at

group_update

Emitted when group settings are updated, such as subject, description or picture.

Parameter

Name Type Optional Description

notification

GroupNotification

 

GroupNotification with more information about the action

incoming_call

Emitted when a call is received

Parameters

Name Type Optional Description

call

object

 

Values in call have the following properties:

Name Type Optional Description

id

number

 

Call id

peerJid

string

 

Who called

isVideo

boolean

 

if is video

isGroup

boolean

 

if is group

canHandleLocally

boolean

 

if we can handle in waweb

outgoing

boolean

 

if is outgoing

webClientShouldHandle

boolean

 

If Waweb should handle

participants

object

 

Participants

media_uploaded

Emitted when media has been uploaded for a message sent by the client.

Parameter

Name Type Optional Description

message

Message

 

The message with media that was uploaded

message

Emitted when a new message is received.

Parameter

Name Type Optional Description

message

Message

 

The message that was received

message_ack

Emitted when an ack event occurrs on message type.

Parameters

Name Type Optional Description

message

Message

 

The message that was affected

ack

MessageAck

 

The new ACK value

message_create

Emitted when a new message is created, which may include the current user's own messages.

Parameter

Name Type Optional Description

message

Message

 

The message that was created

message_edit

Emitted when messages are edited

Parameters

Name Type Optional Description

message

Message

 

newBody

string

 

prevBody

string

 

message_reaction

Emitted when a reaction is sent, received, updated or removed

Parameters

Name Type Optional Description

reaction

object

 

Values in reaction have the following properties:

Name Type Optional Description

id

object

 

Reaction id

orphan

number

 

Orphan

orphanReason

string

 

Orphan reason

Value can be null.

timestamp

number

 

Timestamp

reaction

string

 

Reaction

read

boolean

 

Read

msgId

object

 

Parent message id

senderId

string

 

Sender id

ack

number

 

Ack

Value can be null.

message_revoke_everyone

Emitted when a message is deleted for everyone in the chat.

Parameters

Name Type Optional Description

message

Message

 

The message that was revoked, in its current state. It will not contain the original message's data.

revoked_msg

Message

 

The message that was revoked, before it was revoked. It will contain the message's original data. Note that due to the way this data is captured, it may be possible that this param will be undefined.

Value can be null.

message_revoke_me

Emitted when a message is deleted by the current user.

Parameter

Name Type Optional Description

message

Message

 

The message that was revoked

qr

Emitted when a QR code is received

Parameter

Name Type Optional Description

qr

string

 

QR Code

ready

Emitted when the client has initialized and is ready to receive messages.