BaileysEventMap
The event map defines all events emitted by the Baileys socket. Subscribe to these events to handle WhatsApp updates.
export type BaileysEventMap = {
'connection.update': Partial<ConnectionState>
'creds.update': Partial<AuthenticationCreds>
'messaging-history.set': HistorySet
'chats.upsert': Chat[]
'chats.update': ChatUpdate[]
'chats.delete': string[]
'chats.lock': { id: string; locked: boolean }
'contacts.upsert': Contact[]
'contacts.update': Partial<Contact>[]
'presence.update': PresenceUpdate
'messages.upsert': MessagesUpsert
'messages.update': WAMessageUpdate[]
'messages.delete': MessagesDelete
'messages.reaction': MessageReaction[]
'messages.media-update': MediaUpdate[]
'message-receipt.update': MessageUserReceiptUpdate[]
'groups.upsert': GroupMetadata[]
'groups.update': Partial<GroupMetadata>[]
'group-participants.update': GroupParticipantsUpdate
'group.join-request': GroupJoinRequest
'group.member-tag.update': MemberTagUpdate
'blocklist.set': { blocklist: string[] }
'blocklist.update': BlocklistUpdate
'call': WACallEvent[]
'labels.edit': Label
'labels.association': LabelAssociation
'newsletter.reaction': NewsletterReaction
'newsletter.view': NewsletterView
'newsletter-participants.update': NewsletterParticipantsUpdate
'newsletter-settings.update': NewsletterSettingsUpdate
'settings.update': SettingsUpdate
'lid-mapping.update': LIDMapping
}
Connection events
connection.update
Connection state changes (connecting, open, close).
'connection.update': Partial<ConnectionState>
Show ConnectionState fields
Current connection state: 'close', 'open', 'connecting'
lastDisconnect
{ error: Error; date: Date }
Information about last disconnect
QR code for pairing (only when using pairing code auth)
Whether this is a new login session
Whether the socket is currently online
creds.update
Authentication credentials updated.
'creds.update': Partial<AuthenticationCreds>
Emitted when credentials change (e.g., new keys, registration). Save these to your auth store.
Chat events
chats.upsert
New chats added or existing chats updated.
Number of unread messages
chats.update
Partial updates to existing chats.
'chats.update': ChatUpdate[]
chats.delete
Chats deleted.
'chats.delete': string[] // Array of chat JIDs
chats.lock
Chat lock status changed.
'chats.lock': { id: string; locked: boolean }
New contacts or contact updates.
'contacts.upsert': Contact[]
Partial contact updates.
'contacts.update': Partial<Contact>[]
Message events
messages.upsert
New messages received or sent.
'messages.upsert': {
messages: WAMessage[]
type: MessageUpsertType
requestId?: string
}
type
'notify' | 'append'
required
notify: New message requiring notification
append: Add to history silently
ID if message was received from phone sync
messages.update
Existing messages updated (delivery status, read receipts, etc.).
'messages.update': WAMessageUpdate[]
type WAMessageUpdate = {
key: WAMessageKey
update: Partial<WAMessage>
}
messages.delete
Messages deleted.
'messages.delete':
| { keys: WAMessageKey[] }
| { jid: string; all: true }
Either specific messages deleted or all messages in a chat cleared.
messages.reaction
Message reactions added or removed.
'messages.reaction': Array<{
key: WAMessageKey
reaction: proto.IReaction
}>
Reaction data (emoji or removal)
Media retry/update status.
'messages.media-update': Array<{
key: WAMessageKey
media?: { ciphertext: Uint8Array; iv: Uint8Array }
error?: Boom
}>
message-receipt.update
User-level read receipts.
'message-receipt.update': MessageUserReceiptUpdate[]
type MessageUserReceiptUpdate = {
key: WAMessageKey
receipt: MessageUserReceipt
}
Presence events
presence.update
User presence (online/offline, typing, recording).
'presence.update': {
id: string
presences: {
[participant: string]: PresenceData
}
}
Map of participant JID to presence data
'available', 'unavailable', 'composing', 'recording', 'paused'
Unix timestamp of last seen
Group events
groups.upsert
New groups or group metadata updates.
'groups.upsert': GroupMetadata[]
groups.update
Partial group metadata updates.
'groups.update': Partial<GroupMetadata>[]
group-participants.update
Group participants added, removed, promoted, or demoted.
'group-participants.update': {
id: string
author: string
authorPn?: string
participants: GroupParticipant[]
action: ParticipantAction
}
JID of user who made the change
participants
GroupParticipant[]
required
Affected participants
action
ParticipantAction
required
Action: 'add', 'remove', 'promote', 'demote'
group.join-request
Group join request.
'group.join-request': {
id: string
author: string
authorPn?: string
participant: string
participantPn?: string
action: RequestJoinAction
method: RequestJoinMethod
}
group.member-tag.update
Group member label/tag updated.
'group.member-tag.update': {
groupId: string
participant: string
participantAlt?: string
label: string
messageTimestamp?: number
}
Blocklist events
blocklist.set
Full blocklist synchronized.
'blocklist.set': { blocklist: string[] }
blocklist.update
Blocklist items added or removed.
'blocklist.update': {
blocklist: string[]
type: 'add' | 'remove'
}
Call events
call
Incoming call, call accepted, or call rejected.
Whether it’s a group call
Whether it’s a video call
Call status: 'offer', 'ringing', 'accept', 'reject', 'timeout'
Label events
labels.edit
Label created, edited, or deleted.
labels.association
Label associated or disassociated with a chat.
'labels.association': {
association: LabelAssociation
type: 'add' | 'remove'
}
Newsletter events
newsletter.reaction
Reaction on newsletter message.
'newsletter.reaction': {
id: string
server_id: string
reaction: {
code?: string
count?: number
removed?: boolean
}
}
newsletter.view
Newsletter message view count update.
'newsletter.view': {
id: string
server_id: string
count: number
}
newsletter-participants.update
Newsletter participant update.
'newsletter-participants.update': {
id: string
author: string
user: string
new_role: string
action: string
}
newsletter-settings.update
Newsletter settings changed.
'newsletter-settings.update': {
id: string
update: any
}
Settings events
settings.update
App settings synchronized.
'settings.update':
| { setting: 'unarchiveChats'; value: boolean }
| { setting: 'locale'; value: string }
| { setting: 'disableLinkPreviews'; value: proto.SyncActionValue.IPrivacySettingDisableLinkPreviewsAction }
| { setting: 'timeFormat'; value: proto.SyncActionValue.ITimeFormatAction }
| { setting: 'privacySettingRelayAllCalls'; value: proto.SyncActionValue.IPrivacySettingRelayAllCalls }
| { setting: 'statusPrivacy'; value: proto.SyncActionValue.IStatusPrivacyAction }
| { setting: 'notificationActivitySetting'; value: proto.SyncActionValue.NotificationActivitySettingAction.NotificationActivitySetting }
| { setting: 'channelsPersonalisedRecommendation'; value: proto.SyncActionValue.IPrivacySettingChannelsPersonalisedRecommendationAction }
History sync events
messaging-history.set
Full chat history synchronized from phone.
'messaging-history.set': {
chats: Chat[]
contacts: Contact[]
messages: WAMessage[]
lidPnMappings?: LIDMapping[]
isLatest?: boolean
progress?: number | null
syncType?: proto.HistorySync.HistorySyncType | null
peerDataRequestSessionId?: string | null
}
All synced messages (reverse chronological)
Whether this is the latest history batch
LID mapping events
lid-mapping.update
LID to phone number mapping updated.
'lid-mapping.update': LIDMapping
Emitted when WhatsApp’s LID (Locally Identifiable Device) mappings are updated.
Event emitter interface
export interface BaileysEventEmitter {
on<T extends keyof BaileysEventMap>(
event: T,
listener: (arg: BaileysEventMap[T]) => void
): void
off<T extends keyof BaileysEventMap>(
event: T,
listener: (arg: BaileysEventMap[T]) => void
): void
removeAllListeners<T extends keyof BaileysEventMap>(event: T): void
emit<T extends keyof BaileysEventMap>(
event: T,
arg: BaileysEventMap[T]
): boolean
}
Usage example
import makeWASocket from '@whiskeysockets/baileys'
const sock = makeWASocket({ /* config */ })
// Listen to connection updates
sock.ev.on('connection.update', (update) => {
const { connection, lastDisconnect } = update
if(connection === 'close') {
console.log('Connection closed')
} else if(connection === 'open') {
console.log('Connection opened')
}
})
// Listen to new messages
sock.ev.on('messages.upsert', ({ messages, type }) => {
for(const msg of messages) {
if(type === 'notify') {
console.log('New message:', msg)
}
}
})
// Listen to group updates
sock.ev.on('group-participants.update', ({ id, participants, action }) => {
console.log(`Group ${id}: ${action} ${participants.length} participants`)
})