Events - CometChat Docs

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. Unlike Android, Flutter listeners are not lifecycle-aware and must be manually removed in dispose() to prevent memory leaks.

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.

CallSession? callSession = CallSession.getInstance();

Flutter listeners are not lifecycle-aware. You must manually remove all listeners in your widget’s dispose() method to prevent memory leaks. Failing to do so may cause callbacks to fire on disposed widgets.

Session Events

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

final sessionStatusListener = SessionStatusListener(
  onSessionJoined: () {
    // Successfully connected to the session
  },
  onSessionLeft: () {
    // Navigate away
  },
  onSessionTimedOut: () {
    // Session ended due to inactivity
  },
  onConnectionLost: () {
    // Network interrupted, attempting reconnection
  },
  onConnectionRestored: () {
    // Connection restored after being lost
  },
  onConnectionClosed: () {
    // Connection permanently closed
  },
);

CallSession.getInstance()?.addSessionStatusListener(sessionStatusListener);

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

Remove the listener when no longer needed:

@override
void dispose() {
  CallSession.getInstance()?.removeSessionStatusListener(sessionStatusListener);
  super.dispose();
}

Participant Events

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

final participantEventListener = ParticipantEventListener(
  onParticipantJoined: (Participant participant) {
    // A participant joined the call
  },
  onParticipantLeft: (Participant participant) {
    // A participant left the call
  },
  onParticipantListChanged: (List<Participant> participants) {
    // Participant list updated
  },
  onParticipantAudioMuted: (Participant participant) {},
  onParticipantAudioUnmuted: (Participant participant) {},
  onParticipantVideoPaused: (Participant participant) {},
  onParticipantVideoResumed: (Participant participant) {},
  onParticipantHandRaised: (Participant participant) {},
  onParticipantHandLowered: (Participant participant) {},
  onParticipantStartedScreenShare: (Participant participant) {},
  onParticipantStoppedScreenShare: (Participant participant) {},
  onParticipantStartedRecording: (Participant participant) {},
  onParticipantStoppedRecording: (Participant participant) {},
  onDominantSpeakerChanged: (Participant participant) {},
);

CallSession.getInstance()?.addParticipantEventListener(participantEventListener);

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

Remove the listener when no longer needed:

@override
void dispose() {
  CallSession.getInstance()?.removeParticipantEventListener(participantEventListener);
  super.dispose();
}

Media Events

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

final mediaEventsListener = MediaEventsListener(
  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 audioMode) {
    // Audio output device changed
  },
  onCameraFacingChanged: (CameraFacing facing) {
    // Camera switched between front and rear
  },
);

CallSession.getInstance()?.addMediaEventsListener(mediaEventsListener);

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 rear

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

CameraFacing Values

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

Remove the listener when no longer needed:

@override
void dispose() {
  CallSession.getInstance()?.removeMediaEventsListener(mediaEventsListener);
  super.dispose();
}

Button Click Events

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

final buttonClickListener = ButtonClickListener(
  onLeaveSessionButtonClicked: () {
    // Leave button tapped
  },
  onToggleAudioButtonClicked: () {
    // Mute/unmute button tapped
  },
  onToggleVideoButtonClicked: () {
    // Video on/off button tapped
  },
  onSwitchCameraButtonClicked: () {},
  onRaiseHandButtonClicked: () {},
  onShareInviteButtonClicked: () {},
  onChangeLayoutButtonClicked: () {},
  onParticipantListButtonClicked: () {},
  onChatButtonClicked: () {},
  onRecordingToggleButtonClicked: () {},
);

CallSession.getInstance()?.addButtonClickListener(buttonClickListener);

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.

Remove the listener when no longer needed:

@override
void dispose() {
  CallSession.getInstance()?.removeButtonClickListener(buttonClickListener);
  super.dispose();
}

Layout Events

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

final layoutListener = LayoutListener(
  onCallLayoutChanged: (LayoutType layoutType) {
    // Layout changed (tile, spotlight)
  },
  onParticipantListVisible: () {
    // Participant list panel opened
  },
  onParticipantListHidden: () {
    // Participant list panel closed
  },
  onPictureInPictureLayoutEnabled: () {
    // Entered PiP mode
  },
  onPictureInPictureLayoutDisabled: () {
    // Exited PiP mode
  },
);

CallSession.getInstance()?.addLayoutListener(layoutListener);

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

Remove the listener when no longer needed:

@override
void dispose() {
  CallSession.getInstance()?.removeLayoutListener(layoutListener);
  super.dispose();
}

​Get CallSession Instance

​Session Events

​Participant Events

​Media Events

​Button Click Events

​Layout Events

Get CallSession Instance

Session Events

Participant Events

Media Events

Button Click Events

Layout Events