---
source_url: https://www.pubnub.com/docs/chat/chat-sdk/build/features/connection-management
title: Connection management
updated_at: 2026-05-19T12:09:42.455Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Connection management

Handle subscription errors and restore connections when network issues occur.

## Connection status listener

Monitor connection status in real time to track subscription state and react to network or authentication errors.

:::warning Required configuration
Requires `enableEventEngine: true` in your [configuration](https://www.pubnub.com/docs/chat/chat-sdk/build/configuration).
:::

### Method signature

```ts
chat.addConnectionStatusListener(
  callback: (status: ConnectionStatus) => void
): () => void
```

#### Input

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| callback | (status: | Yes |  | Function invoked on every connection status change with a [ConnectionStatus](#connectionstatus) object. |

#### Output

| Type | Description |
| --- | --- |
| `() => void` | Function you can call to remove the listener. |

### Connection status types

The connection status listener reports the following status types:

| Status | Description |
| --- | --- |
| `PN_CONNECTION_ONLINE` | The connection has been established and is ready to receive real-time updates. |
| `PN_CONNECTION_OFFLINE` | The connection has been intentionally terminated. |
| `PN_CONNECTION_ERROR` | The connection was unexpectedly lost or failed to establish. Contains error details. |

### ConnectionStatus

| Property | Description |
| --- | --- |
| `category` *Type: `ConnectionStatusCategory` | Current connection status category. See [Connection status types](#connection-status-types). |
| `exception`Type: `PubNub.PubNubError` | Error details when `category` is `PN_CONNECTION_ERROR`; otherwise undefined. |

### Sample code

Set up a connection status listener to monitor your chat connection and automatically reconnect on errors.

```ts
const statusListener = chat.addConnectionStatusListener((status) => {
    const statusValue = status.category.value;

    if (statusValue === ConnectionStatusCategory.PN_CONNECTION_ONLINE.value) {
        console.log("Received status PN_CONNECTION_ONLINE");
    }
    else if (statusValue === ConnectionStatusCategory.PN_CONNECTION_OFFLINE.value) {
        console.log("Received status PN_CONNECTION_OFFLINE");
    }
    else if (statusValue === ConnectionStatusCategory.PN_CONNECTION_ERROR.value) {
        console.log(`Received status PN_CONNECTION_ERROR with error: ${status.exception?.message}`);
        // Attempt to recover all subscriptions
        chat.reconnectSubscriptions().catch((e) => {
            console.error("Reconnect failed", e);
        });
    }
});

// Remove connection status listener
statusListener();
```

## Reconnect subscriptions

Restore previous subscriptions with all subscribed channels and listeners. Call after `disconnectSubscriptions()` or when receiving `PN_CONNECTION_ERROR`.

### Method signature

```ts
reconnectSubscriptions(): Promise<void>
```

#### Output

| Type | Description |
| --- | --- |
| `Promise<void>` | Resolves on success, rejects on error. |

### Sample code

Reconnect all subscriptions after a connection error.

```ts
await chat.reconnectSubscriptions();
```

## Disconnect subscriptions

Pause all active subscriptions and listeners.

### Method signature

```ts
disconnectSubscriptions(): Promise<void>
```

#### Output

| Type | Description |
| --- | --- |
| `Promise<void>` | Resolves on success, rejects on error. |

### Sample code

Disconnect all subscriptions when you want to pause real-time updates.

```ts
await chat.disconnectSubscriptions();
```

## Troubleshooting

Recommended workflow for handling subscription errors:

1. Initialize monitoring: Add the connection status listener immediately after creating the Chat instance.
2. Handle errors: On PN_CONNECTION_ERROR, call reconnectSubscriptions().
3. Manual control: Call disconnectSubscriptions() when pausing real-time updates (for example, when the app backgrounds).
4. Restore connection: Call reconnectSubscriptions() to resume.

This pattern maintains stable connectivity and automatic recovery from network issues.