Events

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

The CallSession is a singleton that manages the active call. All event listener registrations and session control methods are accessed through this instance.

Kotlin
Java

val callSession = CometChatCalls.getActiveSession()   // null when no session is prepared or joined

CallSession callSession = CometChatCalls.getActiveSession();   // null when no session is prepared or joined

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). Before a session is prepared or joined, getActiveSession() returns null, so a listener added through it is skipped; the Kotlin samples below use callSession?. for that reason, and in Java check callSession != null before adding one. Add listeners once joinSession (or a prepare) has succeeded, or register them earlier through CallSession.getInstance(), which returns the same object.

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.

Session Events

Monitor the call session lifecycle including join/leave events and connection status.

Kotlin
Java

callSession?.addSessionStatusListener(this, object : SessionStatusListener() {
    override fun onSessionJoined() {
        // Successfully connected to the session
    }

    override fun onSessionLeft() {
        finish() // Navigate away
    }

    override fun onSessionTimedOut() {
        // Session ended due to inactivity
        finish()
    }

    override fun onConnectionLost() {
        // Network interrupted, attempting reconnection
    }

    override fun onConnectionRestored() {
        // Connection restored after being lost
    }

    override fun onConnectionClosed() {
        // Connection permanently closed. On a session that was only prepared
        // (an outgoing call still ringing), this means the call ended before anyone joined.
        finish()
    }
})

callSession.addSessionStatusListener(this, new SessionStatusListener() {
    @Override
    public void onSessionJoined() {
        // Successfully connected to the session
    }

    @Override
    public void onSessionLeft() {
        finish(); // Navigate away
    }

    @Override
    public void onSessionTimedOut() {
        // Session ended due to inactivity
        finish();
    }

    @Override
    public void onConnectionLost() {
        // Network interrupted, attempting reconnection
    }

    @Override
    public void onConnectionRestored() {
        // Connection restored after being lost
    }

    @Override
    public void onConnectionClosed() {
        // Connection permanently closed
        finish();
    }
});

Event	Description
`onConnected()`	A prepared session (from `CometChatCalls.initiateCall` or `connect`) is connected and ready to join; not called for a session joined directly
`onSessionJoined()`	Successfully connected and joined the session
`onSessionLeft()`	Left the session via `leave()` or was removed
`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, the room went away, or nobody joined within 5 minutes); the reason arrives through `onIncomingCallEnded`

Participant Events

Monitor participant activities including join/leave, audio/video state, hand raise, screen sharing, and recording.

Kotlin
Java

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. On an outgoing call: the callee answered.
    }

    override fun onParticipantLeft(participant: Participant) {
        // A participant left the call
    }

    override fun onParticipantListChanged(participants: List<Participant>) {
        // Participant list updated
    }

    override fun onParticipantAudioMuted(participant: Participant) {}
    override fun onParticipantAudioUnmuted(participant: Participant) {}
    override fun onParticipantVideoPaused(participant: Participant) {}
    override fun onParticipantVideoResumed(participant: Participant) {}
    override fun onParticipantHandRaised(participant: Participant) {}
    override fun onParticipantHandLowered(participant: Participant) {}
    override fun onParticipantStartedScreenShare(participant: Participant) {}
    override fun onParticipantStoppedScreenShare(participant: Participant) {}
    override fun onParticipantStartedRecording(participant: Participant) {}
    override fun onParticipantStoppedRecording(participant: Participant) {}
    override fun onDominantSpeakerChanged(participant: Participant) {}
})

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. On an outgoing call: the callee answered.
    }

    @Override
    public void onParticipantLeft(Participant participant) {
        // A participant left the call
    }

    @Override
    public void onParticipantListChanged(List<Participant> participants) {
        // Participant list updated
    }

    // Other callbacks...
});

Event	Parameter	Description
`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
`onParticipantHandLowered`	`Participant`	A participant lowered their hand
`onParticipantStartedScreenShare`	`Participant`	A participant started screen sharing
`onParticipantStoppedScreenShare`	`Participant`	A participant stopped screen sharing
`onParticipantStartedRecording`	`Participant`	A participant started recording
`onParticipantStoppedRecording`	`Participant`	A participant stopped recording
`onDominantSpeakerChanged`	`Participant`	The active speaker changed

Media Events

Monitor your local media state changes including audio/video status, recording, and device changes.

Kotlin
Java

callSession?.addMediaEventsListener(this, object : MediaEventsListener() {
    override fun onAudioMuted() {
        // Your microphone was muted
    }

    override fun onAudioUnMuted() {
        // Your microphone was unmuted
    }

    override fun onVideoPaused() {
        // Your camera was turned off
    }

    override fun onVideoResumed() {
        // Your camera was turned on
    }

    override fun onRecordingStarted() {
        // Call recording started
    }

    override fun onRecordingStopped() {
        // Call recording stopped
    }


    override fun onAudioModeChanged(audioMode: AudioMode) {
        // Audio output device changed
    }

    override fun onCameraFacingChanged(facing: CameraFacing) {
        // Camera switched between front and back
    }
})

callSession.addMediaEventsListener(this, new MediaEventsListener() {
    @Override
    public void onAudioMuted() {
        // Your microphone was muted
    }

    @Override
    public void onAudioUnMuted() {
        // Your microphone was unmuted
    }

    @Override
    public void onVideoPaused() {
        // Your camera was turned off
    }

    @Override
    public void onVideoResumed() {
        // Your camera was turned on
    }

    @Override
    public void onRecordingStarted() {
        // Call recording started
    }

    @Override
    public void onRecordingStopped() {
        // Call recording stopped
    }

    @Override
    public void onAudioModeChanged(AudioMode audioMode) {
        // Audio output device changed
    }

    @Override
    public void onCameraFacingChanged(CameraFacing facing) {
        // Camera switched between front and back
    }

    // Other callbacks...
});

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
`onRecordingStopped`	-	Call recording stopped
`onStreamingStarted`	-	Live streaming started
`onStreamingStopped`	-	Live streaming stopped
`onAudioModeChanged`	`AudioMode`	Audio output device changed
`onAudioModesChanged`	`List<AudioModeInfo>`	The set of available audio devices changed
`onCameraFacingChanged`	`CameraFacing`	Camera switched between front and back

Screen sharing events are not on MediaEventsListener. A participant’s screen share is reported by ParticipantEventListener.onParticipantStartedScreenShare / onParticipantStoppedScreenShare — see Screen Sharing. Starting a screen share from Android is opt-in: the screen share button appears only after your app declares the mediaProjection service (see Enable Screen Sharing).

AudioMode Values

Value	Description
`AudioMode.SPEAKER`	Audio routed through device loudspeaker
`AudioMode.EARPIECE`	Audio routed through phone earpiece
`AudioMode.BLUETOOTH`	Audio routed through connected Bluetooth device
`AudioMode.HEADPHONES`	Audio routed through wired headphones

CameraFacing Values

Value	Description
`CameraFacing.FRONT`	Front-facing (selfie) camera is active
`CameraFacing.BACK`	Rear-facing (main) camera is active

Button Click Events

Intercept UI button clicks from the default call interface to add custom behavior or analytics.

Kotlin
Java

callSession?.addButtonClickListener(this, object : ButtonClickListener() {
    override fun onLeaveSessionButtonClicked() {
        // Leave button tapped
    }

    override fun onToggleAudioButtonClicked() {
        // Mute/unmute button tapped
    }

    override fun onToggleVideoButtonClicked() {
        // Video on/off button tapped
    }

    override fun onSwitchCameraButtonClicked() {}
    override fun onRaiseHandButtonClicked() {}
    override fun onShareInviteButtonClicked() {}
    override fun onChangeLayoutButtonClicked() {}
    override fun onParticipantListButtonClicked() {}
    override fun onChatButtonClicked() {}
    override fun onRecordingToggleButtonClicked() {}
})

callSession.addButtonClickListener(this, new ButtonClickListener() {
    @Override
    public void onLeaveSessionButtonClicked() {
        // Leave button tapped
    }

    @Override
    public void onToggleAudioButtonClicked() {
        // Mute/unmute button tapped
    }

    @Override
    public void onToggleVideoButtonClicked() {
        // Video on/off button tapped
    }

    // Other callbacks...
});

Event	Description
`onLeaveSessionButtonClicked`	Leave/end call button was tapped
`onToggleAudioButtonClicked`	Mute/unmute button was tapped
`onToggleVideoButtonClicked`	Video on/off button was tapped
`onSwitchCameraButtonClicked`	Camera switch button was tapped
`onRaiseHandButtonClicked`	Raise hand button was tapped
`onShareInviteButtonClicked`	Share/invite button was tapped
`onChangeLayoutButtonClicked`	Layout change button was tapped
`onParticipantListButtonClicked`	Participant list button was tapped
`onChatButtonClicked`	In-call chat button was tapped
`onRecordingToggleButtonClicked`	Recording toggle button was tapped

Button click events fire before the SDK’s default action executes. Use these to add custom logic alongside default behavior.

Layout Events

Monitor layout changes including layout type switches and Picture-in-Picture mode transitions.

Kotlin
Java

callSession?.addLayoutListener(this, object : LayoutListener() {
    override fun onCallLayoutChanged(layoutType: LayoutType) {
        // Layout changed (TILE, SPOTLIGHT)
    }

    override fun onParticipantListVisible() {
        // Participant list panel opened
    }

    override fun onParticipantListHidden() {
        // Participant list panel closed
    }

    override fun onPictureInPictureLayoutEnabled() {
        // Entered PiP mode
    }

    override fun onPictureInPictureLayoutDisabled() {
        // Exited PiP mode
    }
})

callSession.addLayoutListener(this, new LayoutListener() {
    @Override
    public void onCallLayoutChanged(LayoutType layoutType) {
        // Layout changed (TILE, SPOTLIGHT)
    }

    @Override
    public void onParticipantListVisible() {
        // Participant list panel opened
    }

    @Override
    public void onParticipantListHidden() {
        // Participant list panel closed
    }

    @Override
    public void onPictureInPictureLayoutEnabled() {
        // Entered PiP mode
    }

    @Override
    public void onPictureInPictureLayoutDisabled() {
        // Exited PiP mode
    }
});

Event	Parameter	Description
`onCallLayoutChanged`	`LayoutType`	Call layout changed
`onParticipantListVisible`	-	Participant list panel was opened
`onParticipantListHidden`	-	Participant list panel was closed
`onPictureInPictureLayoutEnabled`	-	Call entered Picture-in-Picture mode
`onPictureInPictureLayoutDisabled`	-	Call exited Picture-in-Picture mode

LayoutType Values

Value	Description	Best For
`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

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.

Kotlin
Java

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")

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");

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`, when a push delivers them through the Push SDK. Callee still ringing: `cancelled`, `ongoing` (answered elsewhere), `rejected` / `busy` (declined on another device), `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.

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.

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.

Kotlin
Java

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")

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");

Overview

Getting Started

Call Session

Features

Advanced

Migration Guide

Resources

Get CallSession Instance

Session Events

Participant Events

Media Events

Button Click Events

Layout Events

Incoming Call Events

​Get CallSession Instance

​Session Events

​Participant Events

​Media Events

​Button Click Events

​Layout Events

​Incoming Call Events

​Login Events

Get CallSession Instance

Session Events

Participant Events

Media Events

Button Click Events

Layout Events

Incoming Call Events

Login Events