# How OpenWA Handles Session Reconnection with Exponential Backoff

> Rely on OpenWA's exponential backoff for automatic WhatsApp session reconnection. Discover how it intelligently retries connections to keep you online.

- Repository: [Yudhi Armyndharis/OpenWA](https://github.com/rmyndharis/OpenWA)
- Tags: internals
- Published: 2026-05-21

---

**OpenWA automatically restores lost WhatsApp sessions using an exponential backoff algorithm that doubles the wait time between each retry attempt while adding random jitter to prevent server overload.**

OpenWA is an open-source WhatsApp automation library that provides enterprise-grade session management for Node.js applications. When network interruptions or authentication timeouts disconnect a session, the library implements **session reconnection with exponential backoff** to intelligently re-establish connections without overwhelming WhatsApp servers or consuming excessive client resources.

## Initializing Per-Session Reconnect State

The reconnection lifecycle begins when a session starts. In [`src/modules/session/session.service.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/modules/session/session.service.ts), the `start()` method initializes a dedicated `ReconnectState` object for each session ID:

```typescript
this.reconnectStates.set(id, {
  attempts: 0,
  timer: null,
  maxAttempts: config?.maxReconnectAttempts ?? 5,
  baseDelay: config?.reconnectBaseDelay ?? 5000,
});

```

This state object tracks the current retry count, the active timer reference, and configuration overrides. By default, OpenWA allows **5 reconnection attempts** with a **5-second base delay**, though both values can be customized via the session configuration object.

## Detecting Disconnections and Triggering Retries

When the WhatsApp engine reports a disconnection, the `onDisconnected` handler immediately invokes `scheduleReconnect()`:

```typescript
this.scheduleReconnect(id, session);

```

This entry point serves as the gateway to the backoff logic, ensuring that every unexpected disconnect initiates the automated recovery process rather than leaving the session in a dead state.

## Calculating Exponential Backoff with Jitter

The `scheduleReconnect` method in [`src/modules/session/session.service.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/modules/session/session.service.ts) first validates that the current attempt count has not exceeded the configured maximum. If attempts remain available, it calculates the next delay using exponential growth with randomized jitter:

```typescript
const delay = state.baseDelay * Math.pow(2, state.attempts) + Math.random() * 1000;
state.attempts++;

```

The algorithm applies three critical mechanics:

- **Exponential growth**: `Math.pow(2, attempts)` doubles the wait time with each retry (5s, 10s, 20s, 40s, etc.)
- **Random jitter**: `Math.random() * 1000` adds up to 1 second of randomness to prevent synchronized reconnection storms (thundering herd patterns)
- **Attempt tracking**: The counter increments immediately, ensuring the next failure uses the next exponent in the sequence

## Executing Timed Reconnection Attempts

After calculating the delay, the service schedules the actual reconnection attempt:

```typescript
state.timer = setTimeout(() => {
  void this.executeReconnect(id, session, state);
}, delay);

```

When the timer fires, `executeReconnect` performs the heavy lifting by cleaning up the stale engine instance and initializing a fresh connection via `initializeEngine()`:

```typescript
await this.initializeEngine(id, session);

```

If this attempt fails, the error is logged and `scheduleReconnect` is called recursively, which reads the incremented attempt counter and applies the next level of exponential delay.

## Resetting State on Successful Connection

Once the WhatsApp session successfully authenticates and reaches the ready state, the `onReady` handler resets the backoff progression:

```typescript
const reconnectState = this.reconnectStates.get(id);
if (reconnectState) reconnectState.attempts = 0;

```

This reset ensures that subsequent disconnections start the backoff sequence from the initial 5-second delay rather than carrying over accumulated wait times from previous network issues.

## Configuring Reconnection Behavior

Developers can override the default backoff parameters by passing configuration options when starting a session:

```typescript
await sessionService.start('business-session', {
  maxReconnectAttempts: 8,
  reconnectBaseDelay: 3000  // Start with 3 seconds instead of 5
});

```

Alternatively, configuration can be defined in a session JSON object:

```json
{
  "name": "MySession",
  "config": {
    "maxReconnectAttempts": 10,
    "reconnectBaseDelay": 2000
  }
}

```

Setting `maxReconnectAttempts` to `0` effectively disables automatic reconnection, causing the service to log a terminal error immediately upon the first disconnect.

## Summary

- **State tracking**: Each session maintains an isolated `ReconnectState` object in [`src/modules/session/session.service.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/modules/session/session.service.ts) that tracks attempts, timers, and configuration.
- **Exponential delays**: The backoff formula `baseDelay * Math.pow(2, attempts)` creates progressively longer wait times between retries, capped by configurable limits.
- **Jitter protection**: Random values up to 1000ms prevent synchronized client reconnections that could overwhelm servers.
- **Automatic cleanup**: The `executeReconnect` method destroys stale engine instances before creating new connections, preventing memory leaks.
- **Reset mechanism**: Successful connections immediately reset the attempt counter to zero, ensuring fresh backoff calculations for future disconnections.

## Frequently Asked Questions

### What is the default maximum number of reconnection attempts in OpenWA?

According to the source code in [`src/modules/session/session.service.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/modules/session/session.service.ts), the default value for `maxReconnectAttempts` is **5**, and the default `reconnectBaseDelay` is **5000 milliseconds** (5 seconds). These defaults apply when no configuration overrides are provided in the session config object.

### How does OpenWA prevent the thundering herd problem during mass reconnections?

The implementation adds **random jitter** to each calculated delay using `Math.random() * 1000`, which introduces up to 1 second of randomness to the wait time. This desynchronizes reconnection attempts across multiple sessions or distributed instances, preventing simultaneous connection floods that could trigger rate limits.

### Can I disable automatic reconnection entirely?

Yes. Setting `maxReconnectAttempts` to `0` in the session configuration disables the retry mechanism. When this value is set, the `scheduleReconnect` method will log an error and terminate the reconnection cycle immediately upon the first disconnect rather than entering the exponential backoff loop.

### Where is the reconnection logic implemented in the OpenWA codebase?

The core logic resides in [`src/modules/session/session.service.ts`](https://github.com/rmyndharis/OpenWA/blob/main/src/modules/session/session.service.ts), specifically within the `scheduleReconnect()` and `executeReconnect()` methods. The `onDisconnected` handler triggers the process, while `onReady` handles the attempt counter reset, creating a complete lifecycle managed entirely within the SessionService class.