> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> CometChat Calling SDK v5 - Events for Android

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.

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    val callSession = CallSession.getInstance()
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    CallSession callSession = CallSession.getInstance();
    ```
  </Tab>
</Tabs>

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

***

## Session Events

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

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    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()
        }
    })
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    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();
        }
    });
    ```
  </Tab>
</Tabs>

| 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.

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    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) {}
    })
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    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...
    });
    ```
  </Tab>
</Tabs>

| 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.

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    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
        }
    })
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    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...
    });
    ```
  </Tab>
</Tabs>

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

<AccordionGroup>
  <Accordion title="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           |
  </Accordion>

  <Accordion title="CameraFacing Values">
    | Value                | Description                            |
    | -------------------- | -------------------------------------- |
    | `CameraFacing.FRONT` | Front-facing (selfie) camera is active |
    | `CameraFacing.BACK`  | Rear-facing (main) camera is active    |
  </Accordion>
</AccordionGroup>

***

## Button Click Events

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

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    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() {}
    })
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    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...
    });
    ```
  </Tab>
</Tabs>

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

<Note>
  Button click events fire before the SDK's default action executes. Use these to add custom logic alongside default behavior.
</Note>

***

## Layout Events

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

<Tabs>
  <Tab title="Kotlin">
    ```kotlin theme={null}
    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
        }
    })
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    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
        }
    });
    ```
  </Tab>
</Tabs>

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

<Accordion title="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  |
</Accordion>