Events - CometChat Docs

Handle call session events to build responsive UIs. The SDK provides event listeners to monitor session status, participant activities, media changes, button clicks, and layout changes.

Adding Event Listeners

Use the addEventListener() method to register event listeners. The method returns an unsubscribe function that you should call to remove the listener when no longer needed.

const unsubscribe = CometChatCalls.addEventListener("eventName", (data) => {
  // Handle the event
});

// Later, to remove the listener:
unsubscribe();

Listeners are global: they are not tied to a session, work before any session exists, and stay registered across sessions until you call the function they return. The session object has the same method, session.addEventListener(eventName, listener), with the same behavior. To ask whether there is a session right now, use CometChatCalls.getActiveSession():

// null when no session is preparing, prepared or joined
const session = CometChatCalls.getActiveSession();
if (session) {
  console.log("Live session", session.sessionId, session.prepareStatus);
}

getActiveSession() returns the session as soon as it starts preparing, before anyone joins: from the moment CometChatCalls.initiateCall has created the call on the caller, and from the moment CometChatCalls.connect is called on a ringing callee. It returns null again once the session ends, its prepare fails or is cancelled, or a prepared session expires after 5 minutes. While a session is only prepared, the SDK reports onConnected, onConnectionFailed (fatal errors only), onConnectionClosed and the roster events (onParticipantConnected, onParticipantJoined, onParticipantLeft, onParticipantListChanged); that is what lets a caller see “ringing” and “answered” without joining (see Ringing).

Session Events

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

Connected

Fired when a prepared session has connected: signalling only, no camera or microphone, and other participants do not see you yet. It fires once per prepare (initiateCall on the caller, connect on the callee); the actual join is onSessionJoined.

CometChatCalls.addEventListener("onConnected", () => {
  console.log("Session prepared: the join will be near-instant");
});

Session Joined

Fired when you successfully connect to the session.

CometChatCalls.addEventListener("onSessionJoined", () => {
  console.log("Successfully joined the session");
});

Session Left

Fired when you leave the session.

CometChatCalls.addEventListener("onSessionLeft", () => {
  console.log("Left the session");
});

Session Timed Out

Fired when the session ends due to inactivity timeout. It is not used on a prepared session: one that nobody joins within 5 minutes reports onConnectionClosed instead.

CometChatCalls.addEventListener("onSessionTimedOut", () => {
  console.log("Session timed out");
});

Connection Lost

Fired when the network connection is interrupted.

CometChatCalls.addEventListener("onConnectionLost", () => {
  console.log("Connection lost, attempting to reconnect...");
});

Connection Restored

Fired when the connection is restored after being lost.

CometChatCalls.addEventListener("onConnectionRestored", () => {
  console.log("Connection restored");
});

Connection Closed

Fired when the connection is permanently closed. On a session that was only prepared (an outgoing call still ringing, or an incoming call this tab prepared), it means the call ended before anyone joined: declined, cancelled (in a 1:1 call), the room went away, leave() or endCall tore it down, or nobody joined within 5 minutes. The event carries no reason.

CometChatCalls.addEventListener("onConnectionClosed", () => {
  console.log("Connection closed");
});

Participant Events

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

Participant Connected

Fired when a remote participant’s device has prepared the session without joining it. On the caller’s prepared session, this is the callee’s device ringing.

CometChatCalls.addEventListener("onParticipantConnected", (participant) => {
  console.log("Participant waiting:", participant.uid);
});

Participant Joined

Fired when a participant joins the call. On the caller’s prepared session, this is the callee answering: join with session.join(container) now.

CometChatCalls.addEventListener("onParticipantJoined", (participant) => {
  console.log("Participant joined:", participant.name);
});

Participant Left

Fired when a participant leaves the call.

CometChatCalls.addEventListener("onParticipantLeft", (participant) => {
  console.log("Participant left:", participant.name);
});

Participant List Changed

Fired when the participant list is updated.

CometChatCalls.addEventListener("onParticipantListChanged", (participants) => {
  console.log("Participants:", participants.length);
});

Participant Audio Muted

Fired when a participant mutes their microphone.

CometChatCalls.addEventListener("onParticipantAudioMuted", (participant) => {
  console.log("Participant muted:", participant.name);
});

Participant Audio Unmuted

Fired when a participant unmutes their microphone.

CometChatCalls.addEventListener("onParticipantAudioUnmuted", (participant) => {
  console.log("Participant unmuted:", participant.name);
});

Participant Video Paused

Fired when a participant turns off their camera.

CometChatCalls.addEventListener("onParticipantVideoPaused", (participant) => {
  console.log("Participant video paused:", participant.name);
});

Participant Video Resumed

Fired when a participant turns on their camera.

CometChatCalls.addEventListener("onParticipantVideoResumed", (participant) => {
  console.log("Participant video resumed:", participant.name);
});

Participant Hand Raised

Fired when a participant raises their hand.

CometChatCalls.addEventListener("onParticipantHandRaised", (participant) => {
  console.log("Participant raised hand:", participant.name);
});

Participant Hand Lowered

Fired when a participant lowers their hand.

CometChatCalls.addEventListener("onParticipantHandLowered", (participant) => {
  console.log("Participant lowered hand:", participant.name);
});

Fired when a participant starts screen sharing.

CometChatCalls.addEventListener("onParticipantStartedScreenShare", (participant) => {
  console.log("Participant started screen share:", participant.name);
});

Fired when a participant stops screen sharing.

CometChatCalls.addEventListener("onParticipantStoppedScreenShare", (participant) => {
  console.log("Participant stopped screen share:", participant.name);
});

Participant Started Recording

Fired when a participant starts recording.

CometChatCalls.addEventListener("onParticipantStartedRecording", (participant) => {
  console.log("Participant started recording:", participant.name);
});

Participant Stopped Recording

Fired when a participant stops recording.

CometChatCalls.addEventListener("onParticipantStoppedRecording", (participant) => {
  console.log("Participant stopped recording:", participant.name);
});

Dominant Speaker Changed

Fired when the active speaker changes.

CometChatCalls.addEventListener("onDominantSpeakerChanged", (participant) => {
  console.log("Dominant speaker:", participant.name);
});

Media Events

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

Audio Muted

Fired when your microphone is muted.

CometChatCalls.addEventListener("onAudioMuted", () => {
  console.log("Your audio is muted");
});

Audio Unmuted

Fired when your microphone is unmuted.

CometChatCalls.addEventListener("onAudioUnMuted", () => {
  console.log("Your audio is unmuted");
});

Video Paused

Fired when your camera is turned off.

CometChatCalls.addEventListener("onVideoPaused", () => {
  console.log("Your video is paused");
});

Video Resumed

Fired when your camera is turned on.

CometChatCalls.addEventListener("onVideoResumed", () => {
  console.log("Your video is resumed");
});

Recording Started

Fired when call recording starts.

CometChatCalls.addEventListener("onRecordingStarted", () => {
  console.log("Recording started");
});

Recording Stopped

Fired when call recording stops.

CometChatCalls.addEventListener("onRecordingStopped", () => {
  console.log("Recording stopped");
});

Fired when you start screen sharing.

CometChatCalls.addEventListener("onScreenShareStarted", () => {
  console.log("Screen sharing started");
});

Fired when you stop screen sharing.

CometChatCalls.addEventListener("onScreenShareStopped", () => {
  console.log("Screen sharing stopped");
});

Audio Input Device Changed

Fired when the audio input device changes.

CometChatCalls.addEventListener("onAudioInputDeviceChanged", (device) => {
  console.log("Audio input device changed:", device);
});

Audio Output Device Changed

Fired when the audio output device changes.

CometChatCalls.addEventListener("onAudioOutputDeviceChanged", (device) => {
  console.log("Audio output device changed:", device);
});

Video Input Device Changed

Fired when the video input device changes.

CometChatCalls.addEventListener("onVideoInputDeviceChanged", (device) => {
  console.log("Video input device changed:", device);
});

Audio Input Devices Changed

Fired when the list of available audio input devices changes.

CometChatCalls.addEventListener("onAudioInputDevicesChanged", (devices) => {
  console.log("Audio input devices updated:", devices);
});

Audio Output Devices Changed

Fired when the list of available audio output devices changes.

CometChatCalls.addEventListener("onAudioOutputDevicesChanged", (devices) => {
  console.log("Audio output devices updated:", devices);
});

Video Input Devices Changed

Fired when the list of available video input devices changes.

CometChatCalls.addEventListener("onVideoInputDevicesChanged", (devices) => {
  console.log("Video input devices updated:", devices);
});

Button Click Events

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

Leave Session Button Clicked

Fired when the leave button is clicked. The SDK leaves the session itself right after, so only clean up here.

CometChatCalls.addEventListener("onLeaveSessionButtonClicked", () => {
  console.log("Leave button clicked");
});

Toggle Audio Button Clicked

Fired when the mute/unmute button is clicked.

CometChatCalls.addEventListener("onToggleAudioButtonClicked", () => {
  console.log("Audio toggle button clicked");
});

Toggle Video Button Clicked

Fired when the video on/off button is clicked.

CometChatCalls.addEventListener("onToggleVideoButtonClicked", () => {
  console.log("Video toggle button clicked");
});

Raise Hand Button Clicked

Fired when the raise hand button is clicked.

CometChatCalls.addEventListener("onRaiseHandButtonClicked", () => {
  console.log("Raise hand button clicked");
});

Fired when the share/invite button is clicked.

CometChatCalls.addEventListener("onShareInviteButtonClicked", () => {
  console.log("Share invite button clicked");
});

Change Layout Button Clicked

Fired when the layout change button is clicked.

CometChatCalls.addEventListener("onChangeLayoutButtonClicked", () => {
  console.log("Change layout button clicked");
});

Participant List Button Clicked

Fired when the participant list button is clicked.

CometChatCalls.addEventListener("onParticipantListButtonClicked", () => {
  console.log("Participant list button clicked");
});

Chat Button Clicked

Fired when the in-call chat button is clicked.

CometChatCalls.addEventListener("onChatButtonClicked", () => {
  console.log("Chat button clicked");
});

Recording Toggle Button Clicked

Fired when the recording toggle button is clicked.

CometChatCalls.addEventListener("onRecordingToggleButtonClicked", () => {
  console.log("Recording toggle button clicked");
});

Fired when the screen share button is clicked.

CometChatCalls.addEventListener("onScreenShareButtonClicked", () => {
  console.log("Screen share button clicked");
});

Layout Events

Monitor layout changes including layout type switches and participant list visibility.

Call Layout Changed

Fired when the call layout changes.

CometChatCalls.addEventListener("onCallLayoutChanged", (layout) => {
  console.log("Layout changed to:", layout);
});

Participant List Visible

Fired when the participant list panel is opened.

CometChatCalls.addEventListener("onParticipantListVisible", () => {
  console.log("Participant list opened");
});

Participant List Hidden

Fired when the participant list panel is closed.

CometChatCalls.addEventListener("onParticipantListHidden", () => {
  console.log("Participant list closed");
});

Participant Object Reference

Property	Type	Description
`uid`	String	Unique identifier (CometChat user ID)
`name`	String	Display name
`avatar`	String	URL of avatar image

​Adding Event Listeners

​Session Events

​Connected

​Session Joined

​Session Left

​Session Timed Out

​Connection Lost

​Connection Restored

​Connection Closed

​Participant Events

​Participant Connected

​Participant Joined

​Participant Left

​Participant List Changed

​Participant Audio Muted

​Participant Audio Unmuted

​Participant Video Paused

​Participant Video Resumed

​Participant Hand Raised

​Participant Hand Lowered

​Participant Started Screen Share

​Participant Stopped Screen Share

​Participant Started Recording

​Participant Stopped Recording

​Dominant Speaker Changed

​Media Events

​Audio Muted

​Audio Unmuted

​Video Paused

​Video Resumed

​Recording Started

​Recording Stopped

​Screen Share Started

​Screen Share Stopped

​Audio Input Device Changed

​Audio Output Device Changed

​Video Input Device Changed

​Audio Input Devices Changed

​Audio Output Devices Changed

​Video Input Devices Changed

​Button Click Events

​Leave Session Button Clicked

​Toggle Audio Button Clicked

​Toggle Video Button Clicked

​Raise Hand Button Clicked

​Share Invite Button Clicked

​Change Layout Button Clicked

​Participant List Button Clicked

​Chat Button Clicked

​Recording Toggle Button Clicked

​Screen Share Button Clicked

​Layout Events

​Call Layout Changed

​Participant List Visible

​Participant List Hidden

​Participant Object Reference