Skip to main content

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>

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.
'chats.upsert': Chat[]
id
string
Chat JID
conversationTimestamp
number
Last message timestamp
unreadCount
number
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 }

Contact events

contacts.upsert

New contacts or contact updates.
'contacts.upsert': Contact[]
id
string
Contact JID
name
string
Contact display name
notify
string
Push name

contacts.update

Partial contact updates.
'contacts.update': Partial<Contact>[]

Message events

messages.upsert

New messages received or sent.
'messages.upsert': {
  messages: WAMessage[]
  type: MessageUpsertType
  requestId?: string
}
messages
WAMessage[]
required
Array of new messages
type
'notify' | 'append'
required
  • notify: New message requiring notification
  • append: Add to history silently
requestId
string
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
}>
key
WAMessageKey
required
Message being reacted to
reaction
proto.IReaction
required
Reaction data (emoji or removal)

messages.media-update

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 
  }
}
id
string
required
Chat JID
presences
object
required
Map of participant JID to presence data

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
}
id
string
required
Group JID
author
string
required
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.
'call': WACallEvent[]
chatId
string
JID of caller
from
string
Caller JID
id
string
Call ID
isGroup
boolean
Whether it’s a group call
isVideo
boolean
Whether it’s a video call
status
string
Call status: 'offer', 'ringing', 'accept', 'reject', 'timeout'

Label events

labels.edit

Label created, edited, or deleted.
'labels.edit': Label

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
}
chats
Chat[]
required
All synced chats
contacts
Contact[]
required
All synced contacts
messages
WAMessage[]
required
All synced messages (reverse chronological)
isLatest
boolean
Whether this is the latest history batch
progress
number
Sync progress (0-100)

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`)
})

Build docs developers (and LLMs) love