Reconnection and device conflict

Automatic reconnection

The Chat SDK includes a built-in automatic reconnection mechanism. Once the initial connection succeeds, the SDK takes over all reconnection handling. When the connection drops due to network issues, the SDK automatically attempts to reconnect — no additional action is required on your part.

The SDK triggers reconnection in the following scenarios:

• Weak network — The SDK continuously retries. A heartbeat mechanism between the client and server detects connectivity loss, and the SDK reconnects until a stable connection is established.
• No network — Reconnection pauses. As soon as network connectivity is restored, the SDK resumes reconnection attempts.
• App in background — The system may restrict network access or suspend the process, causing a disconnection. If network access is restricted, the SDK retries until it succeeds. If the process is suspended, the SDK reconnects when the app returns to the foreground.

tip

Once a connection error callback fires, the SDK exits the reconnection loop. Handle the specific error code in your app logic.

Reconnection intervals

The SDK uses exponential backoff for reconnection attempts: 0.05s, 0.25s, 0.5s, 1s, 2s, 4s, 8s, 16s, 32s. After that, the SDK retries every 64 seconds.

When the app moves to the foreground or the network state changes, the backoff resets to the beginning to ensure a fast reconnection.

Exiting the reconnection loop

When your app explicitly calls disconnect, the SDK exits the reconnection loop and stops all retry attempts.

Reconnection device conflict

The reconnection device conflict policy controls whether the SDK kicks out other devices when it reconnects successfully.

By default, only one mobile device per user can be connected at a time. When a new device connects, it automatically kicks the previously connected device offline. In certain edge cases, this default behavior can cause unexpected results with the SDK's automatic reconnection.

Example scenario:

1. The user attempts to sign in on mobile device A, but A has an unstable connection and triggers automatic reconnection.
2. The user switches to mobile device B and signs in successfully. B is now the active device.
3. Device A's network stabilizes and the SDK reconnects. Because A is now the most recently connected device, device B gets kicked offline.

Configure the reconnection kick policy

To prevent the reconnection on device A from kicking device B offline (keeping device B as the active session), modify the reconnection kick policy for the user.

You can configure the reconnection kick policy on the client side by setting ConnectParams.reconnectKickEnable when calling connect. For details, see Connect.

• reconnectKickEnable = true — If another mobile device is already online when the SDK reconnects, the reconnecting device stops and does not go online. The existing session on the other device is preserved.

• reconnectKickEnable = false (default) — If another mobile device is already online when the SDK reconnects, the reconnecting device kicks the other device offline and takes over the session.