Monitor connection status

The Chat SDK provides a ConnectionStatusHandler that reports real-time changes in the connection state. Use it to update your UI or trigger business logic based on the current connection status.

Connection states

When the connection state changes, the SDK invokes your ConnectionStatusHandler callback with the current state. The table below describes each state.

State	Value	Description
NETWORK_UNAVAILABLE	-1	The device has no network connectivity.
CONNECTED	0	Successfully connected to the server.
CONNECTING	1	A connection attempt is in progress.
UNCONNECTED	2	Not connected. The app has not called connect yet.
KICKED_OFFLINE_BY_OTHER_CLIENT	3	The user signed in on another device, and this device was kicked offline.
TOKEN_INCORRECT	4	The access token is expired or invalid.
CONN_USER_BLOCKED	6	The user is blocked.
SIGNED_OUT	12	The user disconnected manually. See Disconnect.
SUSPENDED	13	The connection is temporarily suspended, usually due to a network issue. The SDK reconnects automatically.
TIMEOUT	14	The connection timed out. The SDK stops reconnecting. Handle the timeout in your app and call connect again if needed.
PROXY_UNAVAILABLE	17	The proxy server is unreachable.
USER_ABANDON	19	The user abandoned the connection.

Add or remove a connection status handler

The SDK supports multiple concurrent handlers. Register handlers early in the app lifecycle. Remove them when they are no longer needed to avoid memory leaks.

Kotlin

kotlin

// Add a connection status handler
NCEngine.addConnectionStatusHandler("CONNECTION_HANDLER_ID", object : ConnectionStatusHandler {
    override fun onConnectionStatusChanged(event: ConnectionStatusChangedEvent) {
        when (event.status) {
            ConnectionStatus.CONNECTED -> {
                Log.d("Connection", "Connected")
                updateUI(connected = true)
            }
            ConnectionStatus.CONNECTING -> {
                Log.d("Connection", "Connecting...")
                showConnecting()
            }
            ConnectionStatus.SUSPENDED -> {
                // Temporarily suspended — SDK reconnects automatically
                Log.d("Connection", "Suspended")
                showNetworkError()
            }
            ConnectionStatus.NETWORK_UNAVAILABLE -> {
                Log.d("Connection", "Network unavailable")
                showNetworkUnavailable()
            }
            ConnectionStatus.KICKED_OFFLINE_BY_OTHER_CLIENT -> {
                Log.d("Connection", "Kicked offline")
                showKickedOfflineDialog()
            }
            ConnectionStatus.TOKEN_INCORRECT -> {
                Log.d("Connection", "Access token expired")
                refreshTokenAndConnect()
            }
            else -> {
                Log.d("Connection", "Status: ${event.status}")
            }
        }
    }
})

// Remove the connection status handler
NCEngine.removeConnectionStatusHandler("CONNECTION_HANDLER_ID")

Java

Java

// Add a connection status handler
NCEngine.addConnectionStatusHandler("CONNECTION_HANDLER_ID", new ConnectionStatusHandler() {
    @Override
    public void onConnectionStatusChanged(ConnectionStatusChangedEvent event) {
        switch (event.getStatus()) {
            case CONNECTED:
                Log.d("Connection", "Connected");
                updateUI(true);
                break;
            case CONNECTING:
                Log.d("Connection", "Connecting...");
                showConnecting();
                break;
            case SUSPENDED:
                // Temporarily suspended — SDK reconnects automatically
                Log.d("Connection", "Suspended");
                showNetworkError();
                break;
            case NETWORK_UNAVAILABLE:
                Log.d("Connection", "Network unavailable");
                showNetworkUnavailable();
                break;
            case KICKED_OFFLINE_BY_OTHER_CLIENT:
                Log.d("Connection", "Kicked offline");
                showKickedOfflineDialog();
                break;
            case TOKEN_INCORRECT:
                Log.d("Connection", "Access token expired");
                refreshTokenAndConnect();
                break;
            default:
                Log.d("Connection", "Status: " + event.getStatus());
                break;
        }
    }
});

// Remove the connection status handler
NCEngine.removeConnectionStatusHandler("CONNECTION_HANDLER_ID");

Parameters

Parameter	Type	Description
identifier	String	A unique ID for this handler. Use it later to remove the handler.
handler	ConnectionStatusHandler	The callback invoked when the connection state changes.

Get the current connection status

Call getConnectionStatus() to retrieve the current connection state at any time.

tip

If the SDK begins reconnecting at the moment you call this method, the returned state may still show CONNECTED briefly.

Kotlin

kotlin

val currentState = NCEngine.getConnectionStatus()
when (currentState) {
    ConnectionStatus.CONNECTED -> {
        // Connected
    }
    ConnectionStatus.CONNECTING -> {
        // Connecting
    }
    else -> {
        // Other state
    }
}

Java

Java

ConnectionStatus currentState = NCEngine.getConnectionStatus();
if (currentState == ConnectionStatus.CONNECTED) {
    // Connected
} else if (currentState == ConnectionStatus.CONNECTING) {
    // Connecting
} else {
    // Other state
}