Event types

Type definitions for Baileys event system and BaileysEventMap

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

connection · WAConnectionState

Current connection state: 'close', 'open', 'connecting'

lastDisconnect · { error: Error; date: Date }

Information about last disconnect

qr · string

QR code for pairing (only when using pairing code auth)

isNewLogin · boolean

Whether this is a new login session

isOnline · boolean

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.

'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

Show PresenceData fields

lastKnownPresence · WAPresence

'available', 'unavailable', 'composing', 'recording', 'paused'

lastSeen · number

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
}

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