Connection Lifecycle

Managing WebSocket connections, handling disconnects, and implementing reconnection logic

Overview

Baileys manages a WebSocket connection to WhatsApp servers. Understanding the connection lifecycle, disconnect reasons, and reconnection strategies is essential for building reliable applications.

Connection States

The connection can be in one of three states:

type WAConnectionState = 'open' | 'connecting' | 'close'

Connection State Object

From src/Types/State.ts:17:

type ConnectionState = {
  /** Connection is now open, connecting or closed */
  connection: WAConnectionState
  
  /** The error that caused the connection to close */
  lastDisconnect?: {
    error: Boom | Error | undefined
    date: Date
  }
  
  /** Is this a new login */
  isNewLogin?: boolean
  
  /** The current QR code */
  qr?: string
  
  /** Has the device received all pending notifications */
  receivedPendingNotifications?: boolean
  
  /** If the client is shown as an active, online client */
  isOnline?: boolean
}

Disconnect Reasons

From src/Types/index.ts:27:

enum DisconnectReason {
  connectionClosed = 428,
  connectionLost = 408,
  connectionReplaced = 440,
  timedOut = 408,
  loggedOut = 401,
  badSession = 500,
  restartRequired = 515,
  multideviceMismatch = 411,
  forbidden = 403,
  unavailableService = 503
}

Understanding Each Reason

• loggedOut (401) - User logged out from WhatsApp. Do NOT reconnect.
• connectionClosed (428) - Normal connection closure. Safe to reconnect.
• connectionLost (408) - Network issue or timeout. Reconnect.
• connectionReplaced (440) - Another device took over. Reconnect carefully.
• restartRequired (515) - Server requests restart. Reconnect immediately.
• timedOut (408) - Connection attempt timed out. Retry.
• badSession (500) - Invalid session data. May require re-authentication.
• multideviceMismatch (411) - Multi-device protocol mismatch. Update library.
• forbidden (403) - Access denied. Check credentials.
• unavailableService (503) - WhatsApp service temporarily unavailable.

Handling Connection Updates

Listen to connection.update events to track connection state:

import makeWASocket, { DisconnectReason } from '@whiskeysockets/baileys'
import { Boom } from '@hapi/boom'

const sock = makeWASocket({ /* config */ })

sock.ev.on('connection.update', (update) => {
  const { connection, lastDisconnect, qr } = update
  
  if (connection === 'close') {
    const shouldReconnect = 
      (lastDisconnect?.error as Boom)?.output?.statusCode 
        !== DisconnectReason.loggedOut
    
    console.log(
      'Connection closed:', 
      lastDisconnect?.error, 
      'Reconnecting:', 
      shouldReconnect
    )
    
    if (shouldReconnect) {
      connectToWhatsApp() // Reconnect
    }
  } else if (connection === 'open') {
    console.log('Connection opened')
  } else if (connection === 'connecting') {
    console.log('Connecting...')
  }
  
  if (qr) {
    console.log('QR Code:', qr)
    // Display QR code to user
  }
})

Complete Connection Example

From Example/example.ts:40:

import makeWASocket, { 
  DisconnectReason, 
  useMultiFileAuthState 
} from '@whiskeysockets/baileys'
import { Boom } from '@hapi/boom'

async function connectToWhatsApp() {
  const { state, saveCreds } = await useMultiFileAuthState(
    'auth_info_baileys'
  )
  
  const sock = makeWASocket({
    auth: state,
    printQRInTerminal: true
  })
  
  sock.ev.on('connection.update', (update) => {
    const { connection, lastDisconnect } = update
    
    if (connection === 'close') {
      const statusCode = (lastDisconnect?.error as Boom)
        ?.output?.statusCode
      const shouldReconnect = statusCode !== DisconnectReason.loggedOut
      
      console.log(
        'Connection closed due to', 
        lastDisconnect?.error, 
        'reconnecting', 
        shouldReconnect
      )
      
      // Reconnect if not logged out
      if (shouldReconnect) {
        connectToWhatsApp()
      } else {
        console.log('Connection closed. You are logged out.')
      }
    } else if (connection === 'open') {
      console.log('Opened connection')
    }
  })
  
  // Save credentials when updated
  sock.ev.on('creds.update', saveCreds)
  
  return sock
}

connectToWhatsApp()

Reconnection Strategies

Basic Reconnection

function reconnect() {
  setTimeout(() => {
    connectToWhatsApp()
  }, 3000) // Wait 3 seconds before reconnecting
}

Exponential Backoff

let reconnectAttempts = 0
const MAX_RECONNECT_ATTEMPTS = 5
const BASE_DELAY = 1000 // 1 second

function reconnectWithBackoff() {
  if (reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
    console.log('Max reconnection attempts reached')
    return
  }
  
  const delay = BASE_DELAY * Math.pow(2, reconnectAttempts)
  reconnectAttempts++
  
  console.log(`Reconnecting in ${delay}ms (attempt ${reconnectAttempts})`)
  
  setTimeout(() => {
    connectToWhatsApp()
  }, delay)
}

sock.ev.on('connection.update', (update) => {
  if (update.connection === 'close') {
    reconnectWithBackoff()
  } else if (update.connection === 'open') {
    reconnectAttempts = 0 // Reset on successful connection
  }
})

Smart Reconnection

function shouldReconnect(
  statusCode: number | undefined
): boolean {
  // Never reconnect on logout
  if (statusCode === DisconnectReason.loggedOut) {
    return false
  }
  
  // Don't reconnect on bad session - may need re-auth
  if (statusCode === DisconnectReason.badSession) {
    console.log('Bad session - clearing auth state')
    // Clear auth state and restart
    return false
  }
  
  // Reconnect on all other errors
  return true
}

QR Code Generation

When connecting for the first time, a QR code is generated:

sock.ev.on('connection.update', (update) => {
  const { qr } = update
  
  if (qr) {
    // Option 1: Print to terminal
    console.log('Scan this QR code:', qr)
    
    // Option 2: Generate QR code image
    // Use a library like 'qrcode' to generate an image
    QRCode.toDataURL(qr, (err, url) => {
      // Display url as image
    })
  }
})

Set printQRInTerminal: true in socket config to automatically print the QR code to the terminal.

Pairing Code Flow

From Example/example.ts:88:

const usePairingCode = true

sock.ev.on('connection.update', async (update) => {
  const { qr } = update
  
  if (qr && usePairingCode && !sock.authState.creds.registered) {
    const phoneNumber = await question('Enter your phone number:\n')
    const code = await sock.requestPairingCode(phoneNumber)
    console.log(`Pairing code: ${code}`)
  }
})

Connection Configuration

Important socket configuration options for connection management:

const sock = makeWASocket({
  // Browser identification
  browser: Browsers.ubuntu('My App'),
  
  // Print QR to terminal
  printQRInTerminal: true,
  
  // Receive full message history
  syncFullHistory: true,
  
  // Mark as online when connecting
  markOnlineOnConnect: true, // Set false for notifications
  
  // Connection retry settings
  connectTimeoutMs: 60_000,
  
  // Custom logger
  logger: pino({ level: 'info' })
})

If markOnlineOnConnect is true, your phone won’t receive notifications while Baileys is connected. Set to false if you want to receive notifications on your phone.

Monitoring Connection Health

Check if Connected

function isConnected(sock: WASocket): boolean {
  return sock.ws?.readyState === WebSocket.OPEN
}

Presence Updates

// Send presence to indicate online status
await sock.sendPresenceUpdate('available', jid)

// Mark as unavailable to receive notifications
await sock.sendPresenceUpdate('unavailable')

If a desktop client is active, WhatsApp doesn’t send push notifications to the device. Mark your Baileys client as unavailable to receive notifications.

Received Pending Notifications

The receivedPendingNotifications flag indicates when all offline messages have been received:

sock.ev.on('connection.update', (update) => {
  if (update.receivedPendingNotifications) {
    console.log('All pending notifications received')
    // Safe to proceed with operations
  }
})

History Synchronization

On first connection, WhatsApp sends message history:

sock.ev.on('messaging-history.set', ({ 
  chats, 
  contacts, 
  messages, 
  isLatest 
}) => {
  console.log(`Received ${messages.length} messages`)
  console.log(`Received ${chats.length} chats`)
  console.log(`Received ${contacts.length} contacts`)
  console.log('Is latest history:', isLatest)
})

Best Practices

Connection Management Tips:

1. Always check loggedOut - Never reconnect when user logged out
2. Implement backoff - Use exponential backoff for reconnection attempts
3. Save credentials - Listen to creds.update and save immediately
4. Handle QR expiry - QR codes expire; generate new ones
5. Monitor health - Track connection state and last disconnect reason
6. Graceful shutdown - Properly close the socket before exiting
7. Log errors - Log lastDisconnect.error for debugging

Graceful Shutdown

process.on('SIGINT', async () => {
  console.log('Shutting down gracefully...')
  
  // Close the socket
  sock.ws?.close()
  
  // Save any pending data
  await saveCreds()
  
  process.exit(0)
})

See Also

• Authentication - Managing auth state
• Events - Connection-related events
• WhatsApp IDs - Understanding JID format