hritika-cometchat · Oct 20, 2026 · Oct 20, 2026
diff --git a/calls/android/events.mdx b/calls/android/events.mdx
@@ -5,7 +5,7 @@ sdk_version: "5.x"
 description: "Handle CometChat Calls SDK v5 events on Android for call lifecycle, participants, media state, errors, and real-time updates."
 ---
 
-Handle call session events to build responsive UIs. The SDK provides five session listener interfaces to monitor session status, participant activities, media changes, button clicks, and layout changes, plus two global listeners for incoming calls and login state. Each listener is lifecycle-aware and automatically cleaned up when the Activity or Fragment is destroyed.
+Handle call session events to build responsive UIs. The SDK provides five session listener interfaces to monitor session status, participant activities, media changes, button clicks, and layout changes, plus two global listeners for incoming calls and login state. The five session listeners are lifecycle-aware and automatically cleaned up when the Activity or Fragment is destroyed; the two global listeners are not, so remove those yourself.
 
 ## Get CallSession Instance
 
@@ -24,10 +24,10 @@ CallSession callSession = CometChatCalls.getActiveSession();   // null when no s
 </Tab>
 </Tabs>
 
-`getActiveSession()` returns the session as soon as it is **prepared**, which is what `CometChatCalls.initiateCall` does on the caller and what the Push SDK's ring does on the callee, before anyone joins. That is what lets a caller listen for "ringing" and "answered" without joining (see [Ringing](/calls/android/ringing)). `CallSession.getInstance()` still works and returns the same object.
+`getActiveSession()` returns the session as soon as it is **prepared**, which is what `CometChatCalls.initiateCall` does on the caller and what the Push SDK's ring does on the callee, before anyone joins. That is what lets a caller listen for "ringing" and "answered" without joining (see [Ringing](/calls/android/ringing)). Before a session is prepared or joined, `getActiveSession()` returns null, so a listener added through it is skipped; the samples below use `callSession?.` for that reason. Add listeners once `joinSession` (or a prepare) has succeeded, or register them earlier through `CallSession.getInstance()`, which returns the same object.
 
 <Note>
-All event listeners are lifecycle-aware and automatically removed when the `LifecycleOwner` (Activity/Fragment) is destroyed. You don't need to manually remove listeners.
+All session event listeners are lifecycle-aware and automatically removed when the `LifecycleOwner` (Activity/Fragment) is destroyed. You don't need to manually remove listeners.
 </Note>
 
 ---
@@ -39,7 +39,7 @@ Monitor the call session lifecycle including join/leave events and connection st
 <Tabs>
 <Tab title="Kotlin">
 ```kotlin
-callSession.addSessionStatusListener(this, object : SessionStatusListener() {
+callSession?.addSessionStatusListener(this, object : SessionStatusListener() {
     override fun onSessionJoined() {
         // Successfully connected to the session
     }
@@ -112,10 +112,10 @@ callSession.addSessionStatusListener(this, new SessionStatusListener() {
 |-------|-------------|
 | `onSessionJoined()` | Successfully connected and joined the session |
 | `onSessionLeft()` | Left the session via `leave()` or was removed |
-| `onSessionTimedOut()` | Session ended due to inactivity timeout. On a prepared session: nobody joined in time |
+| `onSessionTimedOut()` | Session ended due to inactivity timeout. Not used on a prepared session: one nobody joins within 5 minutes reports `onConnectionClosed` |
 | `onConnectionLost()` | Network interrupted, SDK attempting reconnection |
 | `onConnectionRestored()` | Connection restored after being lost |
-| `onConnectionClosed()` | Connection permanently closed, cannot reconnect. On a prepared session: the call ended before anyone joined (declined, cancelled from another device, or the room went away); the reason arrives through `onIncomingCallEnded` |
+| `onConnectionClosed()` | Connection permanently closed, cannot reconnect. On a prepared session: the call ended before anyone joined (declined, cancelled from another device, the room went away, or nobody joined within 5 minutes); the reason arrives through `onIncomingCallEnded` |
 
 ---
 
@@ -126,7 +126,7 @@ Monitor participant activities including join/leave, audio/video state, hand rai
 <Tabs>
 <Tab title="Kotlin">
 ```kotlin
-callSession.addParticipantEventListener(this, object : ParticipantEventListener() {
+callSession?.addParticipantEventListener(this, object : ParticipantEventListener() {
     override fun onParticipantConnected(participant: Participant) {
         // A participant's device prepared the session but has not joined yet.
         // On an outgoing call: the callee's phone is ringing.
@@ -215,7 +215,7 @@ Monitor your local media state changes including audio/video status, recording,
 <Tabs>
 <Tab title="Kotlin">
 ```kotlin
-callSession.addMediaEventsListener(this, object : MediaEventsListener() {
+callSession?.addMediaEventsListener(this, object : MediaEventsListener() {
     override fun onAudioMuted() {
         // Your microphone was muted
     }
@@ -347,7 +347,7 @@ Intercept UI button clicks from the default call interface to add custom behavio
 <Tabs>
 <Tab title="Kotlin">
 ```kotlin
-callSession.addButtonClickListener(this, object : ButtonClickListener() {
+callSession?.addButtonClickListener(this, object : ButtonClickListener() {
     override fun onLeaveSessionButtonClicked() {
         // Leave button tapped
     }
@@ -420,7 +420,7 @@ Monitor layout changes including layout type switches and Picture-in-Picture mod
 <Tabs>
 <Tab title="Kotlin">
 ```kotlin
-callSession.addLayoutListener(this, object : LayoutListener() {
+callSession?.addLayoutListener(this, object : LayoutListener() {
     override fun onCallLayoutChanged(layoutType: LayoutType) {
         // Layout changed (TILE, SPOTLIGHT)
     }
@@ -534,7 +534,7 @@ CometChatCalls.removeIncomingCallListener("my-screen");
 | Event | Parameters | Description |
 |-------|------------|-------------|
 | `onIncomingCallReceived` | `InitiatedCall` | A call for the logged-in user is ringing |
-| `onIncomingCallEnded` | `InitiatedCall`, `reason` | The call ended before being answered here. Caller: `rejected`, `busy`, `unanswered`, `cancelled`. Callee still ringing: `cancelled`, `ongoing` (answered elsewhere), `rejected` / `busy` (declined here), `unanswered` |
+| `onIncomingCallEnded` | `InitiatedCall`, `reason` | The call ended before being answered here. Caller: `rejected`, `busy`, `unanswered`, `cancelled`. Callee still ringing: `cancelled`, `ongoing` (answered elsewhere), `rejected` / `busy` (declined here), `unanswered`, `ended` (the prepared session closed before the answer). Treat any other reason as "the ring is over" |
 
 `InitiatedCall` carries `sessionId`, `messageId`, `conversationId`, `sender`, `senderName`, `senderAvatar`, `receiver`, `receiverType`, `type`, `status` and `initiatedAt`.
 

diff --git a/calls/android/migrating-from-legacy-ringing.mdx b/calls/android/migrating-from-legacy-ringing.mdx
@@ -167,17 +167,17 @@ Everything in this list is now done by the Push SDK. Remove it, or it will fight
 - The incoming-call overlay, snackbar, dialog or activity you launched from it
 - Your own ringtone / sound manager for incoming calls
 - The "already in a call → reject with busy" check
-- `CometChatVoIP`, `PhoneAccount` registration, `CometChatVoIPConnectionService`, `CallConnection`, and the `READ_PHONE_STATE`, `MANAGE_OWN_CALLS` and `ANSWER_PHONE_CALLS` permission chain
+- `CometChatVoIP`, `PhoneAccount` registration, `CometChatVoIPConnectionService`, `CallConnection`, and your own `READ_PHONE_STATE` and `ANSWER_PHONE_CALLS` requests. (`MANAGE_OWN_CALLS` still merges in from the Calls SDK's manifest; leave it.)
 - Any `isAppInForeground()` gate around call pushes
 
-Keep: `RECORD_AUDIO`, `CAMERA` and `POST_NOTIFICATIONS` in the manifest. The SDKs request them but do not declare them.
+`RECORD_AUDIO`, `CAMERA` and `POST_NOTIFICATIONS` merge into your manifest from the Calls SDK and the Push SDK's calls module, so you can remove your own declarations; keep requesting them at runtime.
 
 ## Step 6: Rewrite the call code
 
 | Legacy | Now | Notes |
 |--------|-----|-------|
 | `CometChat.initiateCall(Call(uid, RECEIVER_TYPE_USER, type), listener)` | `CometChatCalls.initiateCall(context, uid, InitiateCallOptions, listener<InitiatedCall>)` | Set `options.sessionSettings` with the session type, or an audio call opens the camera |
-| `CometChat.initiateCall(call, timeoutSeconds, listener)` | No client timeout. The ring window is 45 s on both sides (or the push's `ringTimeout`) | Run your own 45 s timer on the caller if you want the screen to close on its own |
+| `CometChat.initiateCall(call, timeoutSeconds, listener)` | No client timeout. The callee's device rings for 45 s (or the push's `ringTimeout`) and then ends the call as `unanswered` | Run your own 45 s timer on the caller: if the callee's device is never reached, nothing else ends the caller's ringing for 5 minutes |
 | `CallListener.onIncomingCallReceived(call)` | Nothing to write; the Push SDK rings. For your own state use `IncomingCallListener.onIncomingCallReceived(InitiatedCall)` | One listener whether the call came by push on a killed process or on a live one |
 | `CallListener.onOutgoingCallAccepted(call)` | `ParticipantEventListener.onParticipantJoined(participant)` on the session `initiateCall` prepared, via `CometChatCalls.getActiveSession()` | New in-between event: `onParticipantConnected` = the callee's device is ringing |
 | `CallListener.onOutgoingCallRejected(call)` | `IncomingCallListener.onIncomingCallEnded(call, "rejected")` or `"busy"` | |
@@ -190,7 +190,7 @@ Keep: `RECORD_AUDIO`, `CAMERA` and `POST_NOTIFICATIONS` in the manifest. The SDK
 | `CallSession.leaveSession()` + `CometChat.endCall(sessionId, listener)` | `CallSession.leave()` | No status to send on a hang-up; the room tells the other side and the backend logs it |
 | `CometChat.getActiveCall()` / `clearActiveCall()` | `CometChatCalls.getActiveSession()` (null when no session is prepared or joined) | |
 | `CometChat.startCall(...)`, `CallSettings`, `OngoingCallListener` | `joinSession` + the 5.x listeners (see the [v5 migration guide](/calls/android/migration-guide-v5)) | |
-| `CometChatCallsConstants.*` | `com.cometchat.calls.constants.Constants.*` | The whole `CometChatCallsConstants` class is deprecated in 5.1 |
+| `CometChatCallsConstants.*` | `com.cometchat.calls.constants.Constants.*` | The whole `CometChatCallsConstants` class has been deprecated since 5.0 |
 | `CometChat.logout(...)` | `CometChatCalls.logout(...)` as well (the UI Kit's `CometChatUIKit.logout` does both) | Otherwise the Calls SDK stays signed in as the old user and a ring is not stopped |
 
 ### Caller screen, before and after
@@ -291,9 +291,9 @@ Details on the [Push ringing](/calls/android/voip-calling) page.
 
 ## What users will notice
 
-- Calls ring with the app killed, from the lock screen, without Telecom permissions.
+- Calls ring with the app killed, from the lock screen, without a `ConnectionService`.
 - The caller sees "Ringing…" once the callee's phone is reached, and the reason when a call is declined or missed.
-- Both sides stop ringing after 45 seconds.
+- The callee stops ringing after 45 seconds and the caller's screen closes with it (and on its own timer, if the callee's device was never reached).
 - Missed calls appear as notifications on the callee.
 - A call during a call is call waiting (answer ends the current call, decline sends busy), not an automatic reject.
 - The microphone and camera prompt appears on Answer the first time, on the device that answers.

diff --git a/calls/android/migration-guide-v5.mdx b/calls/android/migration-guide-v5.mdx
@@ -474,7 +474,7 @@ These classes still exist in v5 for backward compatibility but are deprecated:
 | Deprecated in 5.1 | Replacement |
 |-------------------|-------------|
 | `CallSession.leaveSession()` | `CallSession.leave()` |
-| `CometChatCallsConstants` (the whole class) | `com.cometchat.calls.constants.Constants` |
+| `CometChatCallsConstants` (the whole class; already deprecated since 5.0) | `com.cometchat.calls.constants.Constants` |
 | Chat SDK calling (superseded; deprecated in a coming Chat SDK release): `CometChat.initiateCall`, `acceptCall`, `rejectCall`, `endCall`, `startCall`, `getActiveCall`, `clearActiveCall`, `addCallListener`, `CallListener`, `CallSettings` | `CometChatCalls.initiateCall`, `endCall(sessionId, status)`, `addIncomingCallListener`, the Push Notifications SDK calls module, `leave()` |
 
 New in 5.1: `CometChatCalls.initiateCall`, `endCall(sessionId, status)`, `connect`, `getActiveSession`, `addIncomingCallListener` / `IncomingCallListener`, `addLoginListener` / `LoginListener`, `ParticipantEventListener.onParticipantConnected`.