Connection management

The JavaScript Chat SDK provides connection management methods to handle subscription errors and restore connections when network issues occur. These methods give you full control over your chat app's connectivity and subscription state.

Connection status listener

The addConnectionStatusListener method provides real-time updates about your connection status.

Use this method to track subscription status and react to any subscription errors, such as network connectivity issues or authentication problems.

Method signature

chat.addConnectionStatusListener(
  callback: (status: ConnectionStatus) => void
): () => 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.

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);
        });

show all 20 lines

Reconnect subscriptions

The reconnectSubscriptions() method restores the previous subscriptions with all subscribed channels and all added listeners. Call this method if disconnectSubscriptions() was called previously or if you received PN_CONNECTION_ERROR from the connection status listener to restore all existing subscriptions and listeners.

Method signature

reconnectSubscriptions(): Promise<void>

Output

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

Sample code

Reconnect all subscriptions after a connection error.

await chat.reconnectSubscriptions();

Disconnect subscriptions

The disconnectSubscriptions() method disconnects (pauses) all active subscriptions and listeners. Call this method when you want to pause real-time updates.

Method signature

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.

await chat.disconnectSubscriptions();

Troubleshooting

The recommended workflow for handling subscription errors is:

1. Initialize connection monitoring: Add the connection status listener immediately after creating the Chat object instance.
2. Handle connection errors: When receiving PN_CONNECTION_ERROR status, use reconnectSubscriptions() to restore the connection.
3. Manual control: Use disconnectSubscriptions() when you want to manually pause real-time updates (for example, when the app goes to background).
4. Restore connection: Use reconnectSubscriptions() to restore subscriptions when needed.

This pattern ensures your chat app maintains stable connectivity and can automatically recover from network issues without requiring users to restart the application or lose their chat state.