docs(android): ringing through the Calls SDK and Push Notifications SDK

calls/android/actions.mdx

@@ -14,12 +14,12 @@
 <Tabs>
 <Tab title="Kotlin">
 ```kotlin
 val callSession = CallSession.getInstance()
 ```
 </Tab>
 <Tab title="Java">
 ```java
 CallSession callSession = CallSession.getInstance();
 ```
 </Tab>
 </Tabs>
@@ -47,9 +47,9 @@
 </Tab>
 </Tabs>
 
 ### Unmute Audio
 
 Unmutes your local microphone, resuming audio transmission.
 
 <Tabs>
 <Tab title="Kotlin">
@@ -382,33 +382,37 @@
 <Tabs>
 <Tab title="Kotlin">
 ```kotlin
 val isActive = callSession.isSessionActive()
 ```
 </Tab>
 <Tab title="Java">
 ```java
 boolean isActive = callSession.isSessionActive();
 ```
 </Tab>
 </Tabs>
 
 ### Leave Session
 
-Ends your participation and disconnects gracefully. The call continues for other participants.
+Ends your participation and disconnects gracefully. In a 1:1 call this is the hang-up: the other side receives `onParticipantLeft` and the backend records the end. In a group call the session continues for the other participants.
 
 <Tabs>
 <Tab title="Kotlin">
 ```kotlin
-callSession.leaveSession()
+callSession.leave()
 ```
 </Tab>
 <Tab title="Java">
 ```java
-callSession.leaveSession();
+callSession.leave();
 ```
 </Tab>
 </Tabs>
 
+<Note>
+`leaveSession()` is deprecated since 5.1 and only calls `leave()`. To end a call that is still ringing use `CometChatCalls.endCall(sessionId, status, listener)` with `cancelled` (caller) as described in [Ringing](/calls/android/ringing); `leave()` alone does not tell the other side why.
+</Note>
+
 ### Raise Hand
 
 Shows a hand-raised indicator to get attention from other participants.

calls/android/custom-control-panel.mdx

@@ -36,14 +36,14 @@
 <Tabs>
 <Tab title="Kotlin">
 ```kotlin
 val sessionSettings = CometChatCalls.SessionSettingsBuilder()
     .hideControlPanel(true)
     .build()
 ```
 </Tab>
 <Tab title="Java">
 ```java
 SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder()
     .hideControlPanel(true)
     .build();
 ```
@@ -206,7 +206,7 @@
         }
 
         btnEndCall.setOnClickListener {
-            callSession.leaveSession()
+            callSession.leave()
             finish()
         }
     }
@@ -261,7 +261,7 @@
         btnSwitchCamera.setOnClickListener(v -> callSession.switchCamera());
 
         btnEndCall.setOnClickListener(v -> {
-            callSession.leaveSession();
+            callSession.leave();
             finish();
         });
     }
@@ -470,7 +470,7 @@
         }
 
         btnEndCall.setOnClickListener {
-            callSession.leaveSession()
+            callSession.leave()
             finish()
         }
     }
@@ -601,7 +601,7 @@
         btnSwitchCamera.setOnClickListener(v -> callSession.switchCamera());
 
         btnEndCall.setOnClickListener(v -> {
-            callSession.leaveSession();
+            callSession.leave();
             finish();
         });
     }

calls/android/events.mdx

@@ -5,7 +5,7 @@
 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 event listener interfaces to monitor session status, participant activities, media changes, button clicks, and layout changes. 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. Each listener is lifecycle-aware and automatically cleaned up when the Activity or Fragment is destroyed.
 
 ## Get CallSession Instance
 
@@ -14,16 +14,18 @@
 <Tabs>
 <Tab title="Kotlin">
 ```kotlin
-val callSession = CallSession.getInstance()
+val callSession = CometChatCalls.getActiveSession()   // null when no session is prepared or joined
 ```
 </Tab>
 <Tab title="Java">
 ```java
-CallSession callSession = CallSession.getInstance();
+CallSession callSession = CometChatCalls.getActiveSession();   // null when no session is prepared or joined
 ```
 </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.
+
 <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.
 </Note>
@@ -60,7 +62,8 @@
     }
 
     override fun onConnectionClosed() {
-        // Connection permanently closed
+        // Connection permanently closed. On a session that was only prepared
+        // (an outgoing call still ringing), this means the call ended before anyone joined.
         finish()
     }
 })
@@ -108,11 +111,11 @@
 | Event | Description |
 |-------|-------------|
 | `onSessionJoined()` | Successfully connected and joined the session |
-| `onSessionLeft()` | Left the session via `leaveSession()` or was removed |
-| `onSessionTimedOut()` | Session ended due to inactivity timeout |
+| `onSessionLeft()` | Left the session via `leave()` or was removed |
+| `onSessionTimedOut()` | Session ended due to inactivity timeout. On a prepared session: nobody joined in time |
 | `onConnectionLost()` | Network interrupted, SDK attempting reconnection |
 | `onConnectionRestored()` | Connection restored after being lost |
-| `onConnectionClosed()` | Connection permanently closed, cannot reconnect |
+| `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` |
 
 ---
 
@@ -124,8 +127,13 @@
 <Tab title="Kotlin">
 ```kotlin
 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.
+    }
+
     override fun onParticipantJoined(participant: Participant) {
-        // A participant joined the call
+        // A participant joined the call. On an outgoing call: the callee answered.
     }
 
     override fun onParticipantLeft(participant: Participant) {
@@ -153,9 +161,15 @@
 <Tab title="Java">
 ```java
 callSession.addParticipantEventListener(this, new ParticipantEventListener() {
+    @Override
+    public void 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.
+    }
+
     @Override
     public void onParticipantJoined(Participant participant) {
-        // A participant joined the call
+        // A participant joined the call. On an outgoing call: the callee answered.
     }
 
     @Override
@@ -176,11 +190,12 @@
 
 | Event | Parameter | Description |
 |-------|-----------|-------------|
-| `onParticipantJoined` | `Participant` | A participant connected to the call |
+| `onParticipantConnected` | `Participant` | A participant's device prepared the session without joining. On the caller's prepared session this is the callee ringing |
+| `onParticipantJoined` | `Participant` | A participant joined the call. On the caller's prepared session this is the callee answering: join now |
 | `onParticipantLeft` | `Participant` | A participant disconnected from the call |
 | `onParticipantListChanged` | `List<Participant>` | Participant list updated |
 | `onParticipantAudioMuted` | `Participant` | A participant muted their microphone |
 | `onParticipantAudioUnmuted` | `Participant` | A participant unmuted their microphone |
 | `onParticipantVideoPaused` | `Participant` | A participant turned off their camera |
 | `onParticipantVideoResumed` | `Participant` | A participant turned on their camera |
 | `onParticipantHandRaised` | `Participant` | A participant raised their hand |
@@ -288,7 +303,7 @@
 | Event | Parameter | Description |
 |-------|-----------|-------------|
 | `onAudioMuted` | - | Your microphone was muted |
 | `onAudioUnMuted` | - | Your microphone was unmuted |
 | `onVideoPaused` | - | Your camera was turned off |
 | `onVideoResumed` | - | Your camera was turned on |
 | `onRecordingStarted` | - | Call recording started |
@@ -474,3 +489,88 @@
 | `LayoutType.TILE` | Grid layout with equally-sized tiles | Group discussions, team meetings |
 | `LayoutType.SPOTLIGHT` | Large view for active speaker, small tiles for others | Presentations, one-on-one calls |
 </Accordion>
+
+---
+
+## Incoming Call Events
+
+`CometChatCalls.addIncomingCallListener` is a global listener, not tied to a session. It reports a call for the logged-in user starting and ending, on both sides of the call, whether the call arrived by push while the app was killed or while it was running. It is how a caller learns why an outgoing call ended, and how your own screens stay in sync with calls the Push SDK rings.
+
+<Tabs>
+<Tab title="Kotlin">
+```kotlin
+CometChatCalls.addIncomingCallListener("my-screen", object : CometChatCalls.IncomingCallListener() {
+    override fun onIncomingCallReceived(call: InitiatedCall) {
+        // A call for this user is ringing (the Push SDK already shows it)
+    }
+
+    override fun onIncomingCallEnded(call: InitiatedCall, reason: String) {
+        // The ring ended, or your outgoing call ended: "rejected", "busy", "unanswered", "cancelled", "ongoing"
+    }
+})
+
+CometChatCalls.removeIncomingCallListener("my-screen")
+```
+</Tab>
+<Tab title="Java">
+```java
+CometChatCalls.addIncomingCallListener("my-screen", new CometChatCalls.IncomingCallListener() {
+    @Override
+    public void onIncomingCallReceived(InitiatedCall call) {
+        // A call for this user is ringing (the Push SDK already shows it)
+    }
+
+    @Override
+    public void onIncomingCallEnded(InitiatedCall call, String reason) {
+        // The ring ended, or your outgoing call ended: "rejected", "busy", "unanswered", "cancelled", "ongoing"
+    }
+});
+
+CometChatCalls.removeIncomingCallListener("my-screen");
+```
+</Tab>
+</Tabs>
+
+| 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` |
+
+`InitiatedCall` carries `sessionId`, `messageId`, `conversationId`, `sender`, `senderName`, `senderAvatar`, `receiver`, `receiverType`, `type`, `status` and `initiatedAt`.
+
+<Note>
+Listener ids are keys: registering the same id twice replaces the earlier listener. This listener is not lifecycle-aware; remove it when the screen is destroyed.
+</Note>
+
+---
+
+## Login Events
+
+`CometChatCalls.addLoginListener` reports the Calls SDK login state. The Push SDK uses it to register and unregister the push token and to stop a ring when the user logs out; your app can use it to gate call UI.
+
+<Tabs>
+<Tab title="Kotlin">
+```kotlin
+CometChatCalls.addLoginListener("my-app", object : CometChatCalls.LoginListener() {
+    override fun loginSuccess(user: CallUser) {}
+    override fun loginFailure(e: CometChatException) {}
+    override fun logoutSuccess() {}
+    override fun logoutFailure(e: CometChatException) {}
+})
+
+CometChatCalls.removeLoginListener("my-app")
+```
+</Tab>
+<Tab title="Java">
+```java
+CometChatCalls.addLoginListener("my-app", new CometChatCalls.LoginListener() {
+    @Override public void loginSuccess(CallUser user) {}
+    @Override public void loginFailure(CometChatException e) {}
+    @Override public void logoutSuccess() {}
+    @Override public void logoutFailure(CometChatException e) {}
+});
+
+CometChatCalls.removeLoginListener("my-app");
+```
+</Tab>
+</Tabs>