Connection status management

Supported platforms: Web, Android, iOS, macOS, Windows, Unreal Engine, Electron, Flutter, React Native, Unity, and Unreal Blueprint.

In real-time audio and video implementations, the connection state between the app and Agora SDRTN® changes as the client joins or leaves the channel. The connection may also be interrupted due to network or authentication issues.

This page describes the various channel connection states, reasons for state changes, and how to handle these changes to better manage your users and troubleshoot network faults.

Understand the tech

The following figure shows the various connection states and how the connection state changes between a user joining and leaving a channel:

Disconnection and reconnection

During the communication process, if the user is disconnected due to network problems, the SDK automatically enables the disconnection and reconnection mechanism. The following figure shows the callbacks received by the local user UID1 and the remote user UID2 when:

A local user joins the channel
A network exception occurs
The connection is interrupted
The user rejoins the channel

The following platform-specific timelines explain the reconnection sequence in detail.

In the diagram:

T0: The RTC SDK receives a Client.join request from UID1.
T1: UID1 successfully joins the channel. UID1 receives AgoraRTCClient.on("connection-state-change") callback reporting "CONNECTING" during joining channel and "CONNECTED" after joining.
T2: Due to the transmission delay between networks, UID2 observes a delay of about 100 milliseconds for UID1 to join the channel, and at this point UID2 receives a AgoraRTCClient.on("user-joined") callback.
T3: At some point UID 1 calls AgoraRTCClient.publish to publish the local track.
T4: UID 2 receives the AgoraRTCClient.on("user-published") callback indicating that UID 1 has published the track. UID 2 can subscribe to UID 1's track by calling AgoraRTCClient.subscribe method.
T5: If the UID 1 network is interrupted during the communication process, the SDK automatically opens the disconnection and reconnection mechanism.
T6: The SDK triggers AgoraRTCClient.on("connection-state-change") callback to report "RECONNECTING" during automatic reconnection.
T7: If the Agora server does not receive the audio/video packet from UID 1 for 10 consecutive seconds, the server determines that UID 1 no longer publishes audio/video, and UID 2 will receive AgoraRTCClient.on("user-unpublished") callback.
T8: If the Agora server does not receive a heartbeat packet from UID 1 for 20 consecutive seconds, the server determines that UID 1 is offline, and UID 2 will receive the AgoraRTCClient.on("user-left") callback.
T9: After successfully re-establishing the connection, UID 1 receives the AgoraRTCClient.on("connection-state-change") callback reporting as "CONNECTED".
T10: UID 2 receives the AgoraRTCClient.on("user-joined") callback again.

Connection state	Description
DISCONNECTED	Connection disconnected. The SDK will not automatically reconnect while in this state. This state indicates that the user is in one of the following stages: Has not joined the channel using `join`. Has left the channel using `leave`. Kicked out of the channel by the Agora server or failed to connect.
CONNECTING	Joining. The instantaneous state after calling `join`.
CONNECTED	Occurs after the app has successfully joined the channel. At this point the user can publish or subscribe to the audio and video in the channel.
RECONNECTING	Occurs when the connection is interrupted due to a network disconnection or switch. The SDK automatically tries to reconnect after an interruption.
DISCONNECTING	Disconnecting. This is the state when `leave` is called.

Connection status management

Understand the tech

Disconnection and reconnection

Prerequisites

Implement connection status management

Reference

Connection states

API reference

Contact Us

Contact Us