---
source_url: https://www.pubnub.com/docs/chat/kotlin-chat-sdk/build/features/connection-management
title: Connection management
updated_at: 2026-09-30T07:20:08.000Z
---

# Connection management

> For AI agents: documentation index at https://www.pubnub.com/llms-full.txt

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.

### Method signature

This method takes the following parameters:

```kotlin
chat.addConnectionStatusListener(
    callback: (ConnectionStatus) -> Unit
): AutoCloseable
```

#### Input

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

#### Output

| Type | Description |
| --- | --- |
| `AutoCloseable` | A handle you can call `close()` on to remove the listener. |

:::note Remove the listener
Call `close()` on the returned `AutoCloseable` 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 | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| category | ConnectionStatusCategory | Yes |  | Current connection status category. See [Connection status types](#connection-status-types). |
| exception | PubNubException? | Optional |  | Error details when `category` is `PN_CONNECTION_ERROR`; `null` otherwise. |

### Sample code

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

```kotlin
val statusListener = chat.addConnectionStatusListener { status: ConnectionStatus ->
    when (status.category) {
        ConnectionStatusCategory.PN_CONNECTION_ONLINE -> {
            println("Received status PN_CONNECTION_ONLINE")
        }
        ConnectionStatusCategory.PN_CONNECTION_OFFLINE -> {
            println("Received status PN_CONNECTION_OFFLINE")
        }
        ConnectionStatusCategory.PN_CONNECTION_ERROR -> {
            println("Received status PN_CONNECTION_ERROR with error: ${status.exception?.message}")
            // Attempt to recover all subscriptions
            chat.reconnectSubscriptions().async { result ->
                result.onSuccess {
                    println("Reconnected subscriptions")
                }.onFailure { ex ->
                    println("Reconnect failed: ${ex.message}")
                }
            }
        }
    }
    Unit
}

// Remove connection status listener
statusListener.close()
```

## Reconnect subscriptions

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

### Method signature

```kotlin
chat.reconnectSubscriptions(): PNFuture<Unit>
```

#### Output

| Type | Description |
| --- | --- |
| `PNFuture<Unit>` | A future that completes on success or fails with a `PubNubException`. |

### Sample code

Reconnect all subscriptions after a connection error.

```kotlin
chat.reconnectSubscriptions().async { result ->
    result.onSuccess {
        // handle success
    }.onFailure {
        // handle failure
    }
}
```

## Disconnect subscriptions

Pause all active subscriptions and listeners.

### Method signature

```kotlin
chat.disconnectSubscriptions(): PNFuture<Unit>
```

#### Output

| Type | Description |
| --- | --- |
| `PNFuture<Unit>` | A future that completes on success or fails with a `PubNubException`. |

### Sample code

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

```kotlin
chat.disconnectSubscriptions().async { result ->
    result.onSuccess {
        // handle success
    }.onFailure {
        // handle failure
    }
}
```

## Troubleshooting

Recommended workflow for handling subscription errors:

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

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

Last updated at: 2026-09-30T07:20:08.000Z