Events

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.

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

val callSession = CallSession.getInstance()

Java

CallSession callSession = CallSession.getInstance();

All 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

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
        finish()
    }
})

Java

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
onSessionJoined()	Successfully connected and joined the session
onSessionLeft()	Left the session via leaveSession() or was removed
onSessionTimedOut()	Session ended due to inactivity timeout
onConnectionLost()	Network interrupted, SDK attempting reconnection
onConnectionRestored()	Connection restored after being lost
onConnectionClosed()	Connection permanently closed, cannot reconnect

---

Participant Events

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

Kotlin

callSession.addParticipantEventListener(this, object : ParticipantEventListener() {
    override fun onParticipantJoined(participant: Participant) {
        // A participant joined the call
    }

    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) {}
})

Java

callSession.addParticipantEventListener(this, new ParticipantEventListener() {
    @Override
    public void onParticipantJoined(Participant participant) {
        // A participant joined the call
    }

    @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
onParticipantJoined	Participant	A participant connected to the call
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

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 onScreenShareStarted() {}
    override fun onScreenShareStopped() {}

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

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

Java

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
onScreenShareStarted	-	You started screen sharing
onScreenShareStopped	-	You stopped screen sharing
onAudioModeChanged	AudioMode	Audio output device changed
onCameraFacingChanged	CameraFacing	Camera switched between front and back

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

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() {}
})

Java

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

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

Java

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