Documentation Index
Fetch the complete documentation index at: https://mintlify.com/whiskeysockets/baileys/llms.txt
Use this file to discover all available pages before exploring further.
Event Emitter
The WASocket instance includes an event emitter accessible via sock.ev. Use it to listen for WhatsApp events.
interface BaileysEventEmitter {
on<T extends BaileysEvent>(event: T, listener: (arg: BaileysEventMap[T]) => void): void
off<T extends BaileysEvent>(event: T, listener: (arg: BaileysEventMap[T]) => void): void
removeAllListeners<T extends BaileysEvent>(event: T): void
emit<T extends BaileysEvent>(event: T, arg: BaileysEventMap[T]): boolean
}
Example Usage
import makeWASocket from '@whiskeysockets/baileys'
const sock = makeWASocket({ auth: state })
// Listen to connection updates
sock.ev.on('connection.update', (update) => {
const { connection, lastDisconnect, qr } = update
if(qr) {
console.log('QR Code:', qr)
}
if(connection === 'close') {
console.log('Connection closed')
}
})
// Listen to new messages
sock.ev.on('messages.upsert', ({ messages, type }) => {
console.log('Received', messages.length, 'messages')
for(const msg of messages) {
console.log('Message from:', msg.key.remoteJid)
}
})
BaileysEventMap
All available events and their payload types.
Connection Events
Emitted when connection state changes (WebSocket opened, closed, connecting, etc.).sock.ev.on('connection.update', (update) => {
const { connection, lastDisconnect, qr, isNewLogin, isOnline } = update
if(connection === 'close') {
// Handle disconnect
const shouldReconnect = lastDisconnect?.error?.output?.statusCode !== DisconnectReason.loggedOut
if(shouldReconnect) {
// Reconnect
}
} else if(connection === 'open') {
console.log('Connected successfully')
}
})
connection
'open' | 'close' | 'connecting'
Current connection state
lastDisconnect
{ error?: Error; date?: Date }
Information about the last disconnection
QR code string for authentication (only during initial pairing)
Whether this is a new login session
Whether the phone is online
Authentication Events
creds.update
Partial<AuthenticationCreds>
Emitted when authentication credentials are updated. Always save these updates to maintain the session.const { state, saveCreds } = await useMultiFileAuthState('auth_info')
const sock = makeWASocket({ auth: state })
sock.ev.on('creds.update', saveCreds)
Message Events
Emitted when new messages are received or updated.sock.ev.on('messages.upsert', ({ messages, type }) => {
for(const msg of messages) {
if(!msg.key.fromMe && type === 'notify') {
console.log('New message from', msg.key.remoteJid)
console.log('Message:', msg.message)
}
}
})
type
MessageUpsertType
required
Type of upsert:
'notify' - Message received while connection was online'append' - Message from history sync
Present if message was received from the phone due to it being unavailable
Emitted when message metadata is updated (status, reactions, edits, etc.).sock.ev.on('messages.update', (updates) => {
for(const update of updates) {
console.log('Message', update.key.id, 'updated')
if(update.update.status) {
console.log('New status:', update.update.status)
}
}
})
update
Partial<WAMessage>
required
Updated fields (status, reactions, pollUpdates, etc.)
Emitted when messages are deleted.sock.ev.on('messages.delete', (deletion) => {
if('keys' in deletion) {
// Specific messages deleted
console.log('Deleted messages:', deletion.keys)
} else {
// All messages in chat deleted
console.log('All messages deleted in:', deletion.jid)
}
})
{ keys: WAMessageKey[] } - Specific messages deleted{ jid: string; all: true } - All messages in chat cleared
messages.reaction
Array<{ key: WAMessageKey; reaction: proto.IReaction }>
Emitted when messages receive reactions.sock.ev.on('messages.reaction', (reactions) => {
for(const { key, reaction } of reactions) {
console.log('Message', key.id, 'reacted with:', reaction.text)
if(!reaction.text) {
console.log('Reaction removed')
}
}
})
reaction.text is falsy, the reaction was removed. messages.media-update
Array<{ key: WAMessageKey; media?: object; error?: Boom }>
Emitted when media message metadata is updated.media
{ ciphertext: Uint8Array; iv: Uint8Array }
Updated media encryption data
Error if media update failed
message-receipt.update
MessageUserReceiptUpdate[]
Emitted when message receipts are updated (read, delivered, played).sock.ev.on('message-receipt.update', (receipts) => {
for(const receipt of receipts) {
console.log('Message', receipt.key.id, 'receipt updated')
}
})
Chat Events
Emitted when new chats are created.sock.ev.on('chats.upsert', (chats) => {
console.log('New chats:', chats.length)
for(const chat of chats) {
console.log('Chat ID:', chat.id)
}
})
Emitted when chat metadata is updated.sock.ev.on('chats.update', (updates) => {
for(const update of updates) {
console.log('Chat', update.id, 'updated')
if(update.unreadCount !== undefined) {
console.log('Unread count:', update.unreadCount)
}
}
})
Emitted when chats are deleted.sock.ev.on('chats.delete', (deletedChatIds) => {
console.log('Deleted chats:', deletedChatIds)
})
chats.lock
{ id: string; locked: boolean }
Emitted when a chat is locked or unlocked.
Emitted when new contacts are added.sock.ev.on('contacts.upsert', (contacts) => {
for(const contact of contacts) {
console.log('Contact:', contact.id, contact.name)
}
})
Emitted when contact information is updated.
Group Events
Emitted when new groups are created or joined.sock.ev.on('groups.upsert', (groups) => {
for(const group of groups) {
console.log('Group:', group.subject)
console.log('Participants:', group.participants.length)
}
})
Emitted when group metadata is updated (name, description, settings, etc.).sock.ev.on('groups.update', (updates) => {
for(const update of updates) {
console.log('Group', update.id, 'updated')
if(update.subject) {
console.log('New name:', update.subject)
}
}
})
group-participants.update
Emitted when group participants are added, removed, promoted, or demoted.sock.ev.on('group-participants.update', ({ id, participants, action }) => {
console.log('Group', id)
console.log('Action:', action) // 'add', 'remove', 'promote', 'demote'
console.log('Participants:', participants.map(p => p.id))
})
JID of the user who performed the action
participants
GroupParticipant[]
required
Affected participants
action
ParticipantAction
required
Action performed: 'add' | 'remove' | 'promote' | 'demote'
Emitted when someone requests to join a group.sock.ev.on('group.join-request', ({ id, participant, action }) => {
console.log('Join request in group', id)
console.log('Participant:', participant)
console.log('Action:', action) // 'created', 'revoked'
})
JID of the requesting user
action
RequestJoinAction
required
Action type
method
RequestJoinMethod
required
How the request was made
Emitted when labels are assigned to group members. Presence Events
presence.update
{ id: string; presences: { [participant: string]: PresenceData } }
Emitted when presence status of contacts changes (typing, recording, online, etc.).sock.ev.on('presence.update', ({ id, presences }) => {
console.log('Presence update in', id)
for(const [participant, presence] of Object.entries(presences)) {
console.log(participant, 'is', presence.lastKnownPresence)
// 'unavailable', 'available', 'composing', 'recording'
}
})
History Sync Events
Emitted when history sync is received (chats, contacts, messages from paired device).sock.ev.on('messaging-history.set', ({ chats, contacts, messages, isLatest }) => {
console.log('Received', chats.length, 'chats')
console.log('Received', contacts.length, 'contacts')
console.log('Received', messages.length, 'messages')
console.log('Is latest:', isLatest)
})
Whether this is the most recent sync
syncType
proto.HistorySync.HistorySyncType | null
Type of history sync
Blocklist Events
Emitted when the complete blocklist is set.sock.ev.on('blocklist.set', ({ blocklist }) => {
console.log('Blocked users:', blocklist)
})
blocklist.update
{ blocklist: string[]; type: 'add' | 'remove' }
Emitted when users are added to or removed from the blocklist.sock.ev.on('blocklist.update', ({ blocklist, type }) => {
if(type === 'add') {
console.log('Blocked:', blocklist)
} else {
console.log('Unblocked:', blocklist)
}
})
Call Events
Emitted when calls are received, accepted, or rejected.sock.ev.on('call', (calls) => {
for(const call of calls) {
console.log('Call from:', call.from)
console.log('Call status:', call.status) // 'offer', 'accept', 'reject', etc.
console.log('Is video:', call.isVideo)
console.log('Is group:', call.isGroup)
}
})
Label Events
Emitted when a label is created, edited, or deleted.sock.ev.on('labels.edit', (label) => {
console.log('Label:', label.id, label.name)
})
labels.association
{ association: LabelAssociation; type: 'add' | 'remove' }
Emitted when a label is associated with or removed from a chat/message.sock.ev.on('labels.association', ({ association, type }) => {
console.log('Label', association.labelId, type, 'to', association.chatId)
})
Newsletter Events
Emitted when a newsletter message receives a reaction.reaction
{ code?: string; count?: number; removed?: boolean }
required
Reaction data
newsletter.view
{ id: string; server_id: string; count: number }
Emitted when newsletter message view count is updated.
newsletter-participants.update
Emitted when newsletter participants are updated. newsletter-settings.update
{ id: string; update: any }
Emitted when newsletter settings are updated.
Settings Events
Emitted when WhatsApp settings are updated. Multiple types of settings:sock.ev.on('settings.update', (setting) => {
switch(setting.setting) {
case 'unarchiveChats':
console.log('Unarchive chats:', setting.value)
break
case 'locale':
console.log('Locale:', setting.value)
break
// ... other settings
}
})
{ setting: 'unarchiveChats'; value: boolean }{ setting: 'locale'; value: string }{ setting: 'disableLinkPreviews'; value: proto.SyncActionValue.IPrivacySettingDisableLinkPreviewsAction }{ setting: 'timeFormat'; value: proto.SyncActionValue.ITimeFormatAction }- And more…
LID Mapping Events
Emitted when phone number to LID (Linkable Identifier) mappings are updated.This is used internally for WhatsApp’s multi-device protocol.