> ## 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.

# 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:

```typescript theme={null}
type WAConnectionState = 'open' | 'connecting' | 'close'
```

### Connection State Object

From `src/Types/State.ts:17`:

```typescript theme={null}
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`:

```typescript theme={null}
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:

```typescript theme={null}
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`:

```typescript theme={null}
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

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

### Exponential Backoff

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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
    })
  }
})
```

<Info>
  Set `printQRInTerminal: true` in socket config to automatically print the QR code to the terminal.
</Info>

## Pairing Code Flow

From `Example/example.ts:88`:

```typescript theme={null}
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:

```typescript theme={null}
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' })
})
```

<Warning>
  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.
</Warning>

## Monitoring Connection Health

### Check if Connected

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

### Presence Updates

```typescript theme={null}
// Send presence to indicate online status
await sock.sendPresenceUpdate('available', jid)

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

<Note>
  If a desktop client is active, WhatsApp doesn't send push notifications to the device. Mark your Baileys client as unavailable to receive notifications.
</Note>

## Received Pending Notifications

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

```typescript theme={null}
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:

```typescript theme={null}
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

<Tip>
  **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
</Tip>

## Graceful Shutdown

```typescript theme={null}
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](/concepts/authentication) - Managing auth state
* [Events](/concepts/events) - Connection-related events
* [WhatsApp IDs](/concepts/whatsapp-ids) - Understanding JID format