Reconnection and network resilience

Network switches and short connectivity drops can interrupt call media. The SDK handles reconnection automatically in most cases — use media lifecycle events and reconnect APIs to keep users informed and recover where possible.

How automatic reconnection works

When the SDK detects a media interruption (ICE connection failure, network switch), it automatically attempts to restore the connection by performing an ICE restart on the peer connection.

Timing and retry behavior

Parameter	Value	Description
Max automatic retries	5	The SDK retries up to 5 times before giving up
Retry interval	3 seconds	Fixed delay between each reconnection attempt (no exponential backoff)
Media timeout	10 seconds	If no media is established within 10s of a connection attempt, the SDK treats it as failed
Total automatic recovery window	~15 seconds	5 retries x 3s interval = up to 15s of automatic recovery before failure

What happens at each stage

1. Reconnecting — The SDK detects a media interruption and fires onCallMediaReconnecting. It performs up to 5 ICE restart attempts, spaced 3 seconds apart. No developer action is needed during this phase.

2. Reconnected — If any retry succeeds, the SDK fires onCallMediaReconnection. The audio stream is restored and the call continues normally.

3. Failed — If all 5 automatic retries are exhausted, or if the server returns an error during reconnection, the SDK fires onCallMediaDisconnect. At this point:

   • Audio has stopped
   • The call session may still be active on the server
   • The developer can attempt manual recovery with reconnectCall(callId) if network connectivity has returned
   • If no recovery occurs, the server will eventually terminate the call and onCallHangup fires with mediaTimeout reason

Developer action summary

• During reconnecting: No action required. Show a "reconnecting" UI indicator.
• On reconnection success: Remove the indicator, return to normal call UI.
• On disconnect (failure): Optionally attempt reconnectCall(callId) if you detect network is back. Otherwise, inform the user the call was lost.

---

Session-level reconnection

Separately from media reconnection, the SDK also automatically reconnects the WebSocket session when connectivity drops:

Parameter	Value
Max reconnection attempts	5
Reconnection delay	5 seconds (with 0.75 randomization factor)

Session reconnection fires onReconnecting and onReconnection events (distinct from the call media events above).

---

onCallMediaDisconnect

Fires when the media connection is terminally lost — after all 5 automatic reconnection attempts have been exhausted, or after an unrecoverable server error. At this point the audio stream has stopped, but the call session may still be active on the server. You can attempt manual recovery with reconnectCall(callId).

 client.setOnCallMediaDisconnectListener { legId, reason ->
     when (reason) {
         CallDisconnectReason.networkChange -> println("Received call media disconnect $reason for Call $legId")
     }

 }

onCallMediaReconnecting

Fires when the SDK detects a media interruption (such as a network switch between Wi-Fi and cellular) and is automatically attempting to restore the connection. No user action is required — show a "reconnecting" indicator in your UI.

 client.setOnCallMediaReconnectingListener { legId ->
     println("Received call media reconnecting for Call $legId")
 }

onCallMediaReconnection

Fires when the SDK successfully restores the media connection after an interruption. Remove the reconnecting indicator and return to normal call UI.

 client.setOnCallMediaReconnectionListener { legId ->
     println("Received call media reconnection for Call $legId")
 }

Manual reconnect

Use reconnectCall(callId) when your app decides to trigger recovery explicitly — for example, after receiving onCallMediaDisconnect and confirming that network connectivity has returned.

Manual reconnection also follows the same retry logic (up to 5 attempts, 3s apart) once triggered.

 // Callback
 client.reconnectCall("callId") {
     it?.let { err ->
         // Handle Error in reconnecting call
         println("Error in reconnecting call: $err")
     }
 }
 // Coroutine
 try {
     client.reconnectCall("callId")
 }
 catch (e:Error) {
     // Handle Error in reconnecting call
 }

Android requirement

Automatic network-change recovery on Android requires:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Failure behavior and UX

• If all automatic retries fail and no manual reconnection succeeds, onCallHangup eventually fires with mediaTimeout reason.
• Show a reconnecting indicator when onCallMediaReconnecting fires.
• Return to normal call UI only after onCallMediaReconnection fires.
• On onCallMediaDisconnect, inform the user and optionally offer a "Retry" button that calls reconnectCall(callId).