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.

Required configuration

Requires enableEventEngine: true in your configuration.

Method signature

1chat.addConnectionStatusListener(
2  callback: (status: ConnectionStatus) => void
3): () => void

Input

* required

Parameter	Description
callback * Type: (status: ConnectionStatus) => void Default: n/a	Function invoked on every connection status change with a 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

* required

Property	Description
category * Type: ConnectionStatusCategory	Current connection status category. See 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.

1const statusListener = chat.addConnectionStatusListener((status) => {
2    const statusValue = status.category.value;
3

4    if (statusValue === ConnectionStatusCategory.PN_CONNECTION_ONLINE.value) {
5        console.log("Received status PN_CONNECTION_ONLINE");
6    }
7    else if (statusValue === ConnectionStatusCategory.PN_CONNECTION_OFFLINE.value) {
8        console.log("Received status PN_CONNECTION_OFFLINE");
9    }
10    else if (statusValue === ConnectionStatusCategory.PN_CONNECTION_ERROR.value) {
11        console.log(`Received status PN_CONNECTION_ERROR with error: ${status.exception?.message}`);
12        // Attempt to recover all subscriptions
13        chat.reconnectSubscriptions().catch((e) => {
14            console.error("Reconnect failed", e);
15        });
16    }
17});
18

19// Remove connection status listener
20statusListener();

show all 20 lines

Reconnect subscriptions

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

Method signature

1reconnectSubscriptions(): Promise<void>

Output

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

Sample code

Reconnect all subscriptions after a connection error.

1await chat.reconnectSubscriptions();

Disconnect subscriptions

Pause all active subscriptions and listeners.

Method signature

1disconnectSubscriptions(): 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.

1await 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.