Call Session - CometChat Docs

AI Integration Quick Reference

let sessionId = "SESSION_ID";
let authToken = "AUTH_TOKEN";
let htmlElement = document.getElementById("call-screen");
let callListener = {
  onCallEnded: () => console.log("Call ended"),
  onUserJoined: (user) => console.log("User joined:", user),
  onUserLeft: (user) => console.log("User left:", user),
};

// Generate call token
const callToken = await CometChatCalls.generateToken(sessionId, authToken);

// Build call settings
const callSettings = new CometChatCalls.CallSettingsBuilder()
  .enableDefaultLayout(true)
  .setIsAudioOnlyCall(false)
  .setCallListener(callListener)
  .build();

// Start call session
CometChatCalls.startSession(callToken.token, callSettings, htmlElement);

// End call session
CometChatCalls.endSession();

A call session is the active media connection between participants — camera, microphone, screen sharing, and the call UI. Whether you arrive here from the Ringing flow, your own custom UI, or Standalone Calling, this page covers how to manage the session itself. Before you begin, make sure you’ve completed the Calls SDK Setup.

Generate Call Token

A call token is required for secure access to a call session. Each token is unique to a specific session and user combination, ensuring that only authorized users can join the call. You can generate the token just before starting the call, or generate and store it ahead of time based on your use case.

In the Ringing flow, the session ID comes from the Call object after the call is accepted.
For direct sessions, generate your own unique session ID.

TypeScript
JavaScript

const loggedInUser = await CometChat.getLoggedinUser();
const authToken = loggedInUser.getAuthToken();
const sessionId: string = "SESSION_ID"; // Random or from Call object in ringing flow

CometChatCalls.generateToken(sessionId, authToken).then(
  (callToken: any) => {
    console.log("Call token generated:", callToken.token);
    // Use callToken to start the session
  },
  (error: CometChat.CometChatException) => {
    console.log("Token generation failed:", error);
  }
);

const loggedInUser = await CometChat.getLoggedinUser();
const authToken = loggedInUser.getAuthToken();
const sessionId = "SESSION_ID"; // Random or from Call object in ringing flow

CometChatCalls.generateToken(sessionId, authToken).then(
  (callToken) => {
    console.log("Call token generated:", callToken.token);
    // Use callToken to start the session
  },
  (error) => {
    console.log("Token generation failed:", error);
  }
);

Parameter	Description
`sessionId`	The unique random session ID. In case you are using the ringing flow, the session ID is available in the `Call` object.
`authToken`	The user auth token is the logged-in user auth token which you can get by calling `CometChat.getLoggedinUser().getAuthToken()`

The Promise resolves with an object containing a token property (string) that you pass to startSession().

Start Call Session

Use the startSession() method to join a call session. This method requires:

A call token (generated in the previous step)
A CallSettings object that configures the call UI and behavior
An HTML element where the call UI will be rendered

TypeScript
JavaScript

const callListener = new CometChatCalls.OngoingCallListener({
  onUserJoined: (user: any) => {
    console.log("User joined:", user);
  },
  onUserLeft: (user: any) => {
    console.log("User left:", user);
  },
  onUserListUpdated: (userList: any[]) => {
    console.log("User list updated:", userList);
  },
  onCallEnded: () => {
    console.log("Call ended");
  },
  onCallEndButtonPressed: () => {
    console.log("End call button pressed");
    // Handle end call - see End Call Session section
  },
  onError: (error: any) => {
    console.log("Call error:", error);
  },
  onMediaDeviceListUpdated: (deviceList: any[]) => {
    console.log("Device list updated:", deviceList);
  },
  onUserMuted: (event: any) => {
    console.log("User muted:", event);
  },
  onScreenShareStarted: () => {
    console.log("Screen sharing started");
  },
  onScreenShareStopped: () => {
    console.log("Screen sharing stopped");
  },
  onCallSwitchedToVideo: (event: any) => {
    console.log("Call switched to video:", event);
  },
  onSessionTimeout: () => {
    console.log("Session timed out");
  }
});

const callSettings = new CometChatCalls.CallSettingsBuilder()
  .enableDefaultLayout(true)
  .setIsAudioOnlyCall(false)
  .setCallListener(callListener)
  .build();

const htmlElement = document.getElementById("call-container") as HTMLElement;
CometChatCalls.startSession(callToken, callSettings, htmlElement);

const callListener = new CometChatCalls.OngoingCallListener({
  onUserJoined: (user) => {
    console.log("User joined:", user);
  },
  onUserLeft: (user) => {
    console.log("User left:", user);
  },
  onUserListUpdated: (userList) => {
    console.log("User list updated:", userList);
  },
  onCallEnded: () => {
    console.log("Call ended");
  },
  onCallEndButtonPressed: () => {
    console.log("End call button pressed");
    // Handle end call - see End Call Session section
  },
  onError: (error) => {
    console.log("Call error:", error);
  },
  onMediaDeviceListUpdated: (deviceList) => {
    console.log("Device list updated:", deviceList);
  },
  onUserMuted: (event) => {
    console.log("User muted:", event);
  },
  onScreenShareStarted: () => {
    console.log("Screen sharing started");
  },
  onScreenShareStopped: () => {
    console.log("Screen sharing stopped");
  },
  onCallSwitchedToVideo: (event) => {
    console.log("Call switched to video:", event);
  },
  onSessionTimeout: () => {
    console.log("Session timed out");
  }
});

const callSettings = new CometChatCalls.CallSettingsBuilder()
  .enableDefaultLayout(true)
  .setIsAudioOnlyCall(false)
  .setCallListener(callListener)
  .build();

const htmlElement = document.getElementById("call-container");
CometChatCalls.startSession(callToken, callSettings, htmlElement);

Parameter	Description
`callToken`	The token received from `generateToken()` onSuccess
`callSettings`	Object of `CallSettings` class configured via `CallSettingsBuilder`
`htmlElement`	DOM element where the call UI will be rendered

Call Settings

Configure the call experience using the following CallSettingsBuilder methods:

Method	Description
`enableDefaultLayout(boolean)`	Enables or disables the default call UI layout with built-in controls. `true` shows the default layout. `false` hides the button layout. Default: `true`
`setIsAudioOnlyCall(boolean)`	Sets whether the call is audio-only or audio-video. `true` for audio-only, `false` for audio-video. Default: `false`
`setCallListener(OngoingCallListener)`	Sets the listener to receive call events. See Call Listeners.
`setMode(string)`	Sets the call UI layout mode. Available: `CometChat.CALL_MODE.DEFAULT`, `CometChat.CALL_MODE.SPOTLIGHT`. Default: `DEFAULT`
`startWithAudioMuted(boolean)`	Starts the call with the microphone muted. Default: `false`
`startWithVideoMuted(boolean)`	Starts the call with the camera turned off. Default: `false`
`showEndCallButton(boolean)`	Shows or hides the end call button in the default layout. Default: `true`
`showMuteAudioButton(boolean)`	Shows or hides the mute audio button. Default: `true`
`showPauseVideoButton(boolean)`	Shows or hides the pause video button. Default: `true`
`showScreenShareButton(boolean)`	Shows or hides the screen share button. Default: `true`
`showModeButton(boolean)`	Shows or hides the mode toggle button (switch between DEFAULT and SPOTLIGHT). Default: `true`
`showSwitchToVideoCallButton(boolean)`	Shows or hides the button to upgrade an audio call to video. Default: `true`
`setMainVideoContainerSetting(MainVideoContainerSetting)`	Customizes the main video container. See Video View Customization.
`setIdleTimeoutPeriod(number)`	Sets idle timeout in seconds. Warning appears 60 seconds before auto-termination. Default: `180` seconds. v4.1.0+

End Call Session

How you end a call depends on whether you’re using the Ringing flow or a direct session.

Ringing Flow

When using the Ringing flow, you must coordinate between the CometChat Chat SDK and the Calls SDK to properly terminate the call and notify all participants.

The Ringing flow requires calling methods from both the Chat SDK (CometChat.endCall()) and the Calls SDK (CometChatCalls.endSession()) to ensure proper call termination and participant notification.

User who initiates the end call: When the user clicks the end call button in the UI, the onCallEndButtonPressed() callback is triggered. You must call CometChat.endCall() inside this callback to properly terminate the call and notify other participants. On success, call CometChat.clearActiveCall() and CometChatCalls.endSession() to release resources.

TypeScript
JavaScript

onCallEndButtonPressed: () => {
  CometChat.endCall(sessionId).then(
    (call: CometChat.Call) => {
      console.log("Call ended successfully");
      CometChat.clearActiveCall();
      CometChatCalls.endSession();
      // Close the calling screen
    },
    (error: CometChat.CometChatException) => {
      console.log("End call failed:", error);
    }
  );
}

onCallEndButtonPressed: () => {
  CometChat.endCall(sessionId).then(
    (call) => {
      console.log("Call ended successfully");
      CometChat.clearActiveCall();
      CometChatCalls.endSession();
      // Close the calling screen
    },
    (error) => {
      console.log("End call failed:", error);
    }
  );
}

Remote participant (receives the onCallEnded() callback): Call CometChat.clearActiveCall() to clear the local call state, then call CometChatCalls.endSession() to release media resources.

TypeScript
JavaScript

onCallEnded: () => {
  CometChat.clearActiveCall();
  CometChatCalls.endSession();
  // Close the calling screen
}

onCallEnded: () => {
  CometChat.clearActiveCall();
  CometChatCalls.endSession();
  // Close the calling screen
}

Session Only Flow

When using the Session Only flow (direct call without ringing), you only need to call the Calls SDK method to end the session. There’s no need to notify the Chat SDK since no call signaling was involved.

TypeScript
JavaScript

onCallEndButtonPressed: () => {
  CometChatCalls.endSession();
  // Close the calling screen
}

onCallEndButtonPressed: () => {
  CometChatCalls.endSession();
  // Close the calling screen
}

Call Listeners

The OngoingCallListener provides real-time callbacks for call session events, including participant changes, call state updates, and error conditions. You can register listeners in two ways:

Via CallSettingsBuilder: Use .setCallListener(listener) when building call settings
Via addCallEventListener: Use CometChatCalls.addCallEventListener(listenerId, listener) to add multiple listeners

Each listener requires a unique listenerId string. This ID is used to:

Prevent duplicate registrations — Re-registering with the same ID replaces the existing listener
Enable targeted removal — Remove specific listeners without affecting others

TypeScript
JavaScript

const listenerId: string = "UNIQUE_LISTENER_ID";

CometChatCalls.addCallEventListener(listenerId, {
  onUserJoined: (user: any) => {
    console.log("User joined:", user);
  },
  onUserLeft: (user: any) => {
    console.log("User left:", user);
  },
  onUserListUpdated: (userList: any[]) => {
    console.log("User list updated:", userList);
  },
  onCallEnded: () => {
    console.log("Call ended");
  },
  onCallEndButtonPressed: () => {
    console.log("End call button pressed");
  },
  onError: (error: any) => {
    console.log("Call error:", error);
  },
  onMediaDeviceListUpdated: (deviceList: any[]) => {
    console.log("Device list updated:", deviceList);
  },
  onUserMuted: (event: any) => {
    console.log("User muted:", event);
  },
  onScreenShareStarted: () => {
    console.log("Screen sharing started");
  },
  onScreenShareStopped: () => {
    console.log("Screen sharing stopped");
  },
  onCallSwitchedToVideo: (event: any) => {
    console.log("Call switched to video:", event);
  },
  onSessionTimeout: () => {
    console.log("Session timed out");
  }
});

// Remove listener when done
CometChatCalls.removeCallEventListener(listenerId);

const listenerId = "UNIQUE_LISTENER_ID";

CometChatCalls.addCallEventListener(listenerId, {
  onUserJoined: (user) => {
    console.log("User joined:", user);
  },
  onUserLeft: (user) => {
    console.log("User left:", user);
  },
  onUserListUpdated: (userList) => {
    console.log("User list updated:", userList);
  },
  onCallEnded: () => {
    console.log("Call ended");
  },
  onCallEndButtonPressed: () => {
    console.log("End call button pressed");
  },
  onError: (error) => {
    console.log("Call error:", error);
  },
  onMediaDeviceListUpdated: (deviceList) => {
    console.log("Device list updated:", deviceList);
  },
  onUserMuted: (event) => {
    console.log("User muted:", event);
  },
  onScreenShareStarted: () => {
    console.log("Screen sharing started");
  },
  onScreenShareStopped: () => {
    console.log("Screen sharing stopped");
  },
  onCallSwitchedToVideo: (event) => {
    console.log("Call switched to video:", event);
  },
  onSessionTimeout: () => {
    console.log("Session timed out");
  }
});

// Remove listener when done
CometChatCalls.removeCallEventListener(listenerId);

Always remove call event listeners when they’re no longer needed (e.g., on component unmount or when the call screen is closed). Failing to remove listeners can cause memory leaks and duplicate event handling.

CometChatCalls.removeCallEventListener("UNIQUE_LISTENER_ID");

Events

For the full list of callbacks, their descriptions, and parameter shapes, see the OngoingCallListener reference. The ringing flow methods (initiateCall(), acceptCall(), rejectCall(), endCall()) return Call objects.

In-Call Methods

These methods are available for performing custom actions during an active call session. Use them to build custom UI controls or implement specific behaviors based on your use case.

These methods can only be called when a call session is active.

Switch Camera

Toggles between the front and rear camera during a video call. Only supported on mobile browsers.

TypeScript
JavaScript

CometChatCalls.switchCamera();

CometChatCalls.switchCamera();

This method is only supported on mobile browsers. It has no effect on desktop browsers. Available since v4.2.0

Mute Audio

Controls the local audio stream transmission. When muted, other participants cannot hear the local user.

true — Mutes the microphone, stops transmitting audio
false — Unmutes the microphone, resumes audio transmission

TypeScript
JavaScript

CometChatCalls.muteAudio(true);

CometChatCalls.muteAudio(true);

Pause Video

Controls the local video stream transmission. When paused, other participants see a frozen frame or placeholder instead of live video.

true — Pauses the camera, stops transmitting video
false — Resumes the camera, continues video transmission

TypeScript
JavaScript

CometChatCalls.pauseVideo(true);

CometChatCalls.pauseVideo(true);

Starts sharing your screen or a specific application window with other participants.

TypeScript
JavaScript

CometChatCalls.startScreenShare();

CometChatCalls.startScreenShare();

Stops the current screen sharing session.

TypeScript
JavaScript

CometChatCalls.stopScreenShare();

CometChatCalls.stopScreenShare();

Set Mode

Changes the call UI layout mode dynamically during the call. Available modes:

CometChat.CALL_MODE.DEFAULT — Grid layout showing all participants
CometChat.CALL_MODE.SPOTLIGHT — Focus on the active speaker

TypeScript
JavaScript

CometChatCalls.setMode(CometChat.CALL_MODE.SPOTLIGHT);

CometChatCalls.setMode(CometChat.CALL_MODE.SPOTLIGHT);

Get Audio Input Devices

Returns a list of available audio input devices (microphones) as MediaDeviceInfo[].

TypeScript
JavaScript

const audioInputDevices = CometChatCalls.getAudioInputDevices();
console.log("Available microphones:", audioInputDevices);

const audioInputDevices = CometChatCalls.getAudioInputDevices();
console.log("Available microphones:", audioInputDevices);

Get Audio Output Devices

Returns a list of available audio output devices (speakers/headphones) as MediaDeviceInfo[].

TypeScript
JavaScript

const audioOutputDevices = CometChatCalls.getAudioOutputDevices();
console.log("Available speakers:", audioOutputDevices);

const audioOutputDevices = CometChatCalls.getAudioOutputDevices();
console.log("Available speakers:", audioOutputDevices);

Get Video Input Devices

Returns a list of available video input devices (cameras) as MediaDeviceInfo[].

TypeScript
JavaScript

const videoInputDevices = CometChatCalls.getVideoInputDevices();
console.log("Available cameras:", videoInputDevices);

const videoInputDevices = CometChatCalls.getVideoInputDevices();
console.log("Available cameras:", videoInputDevices);

Set Audio Input Device

Sets the active audio input device (microphone) by device ID.

TypeScript
JavaScript

CometChatCalls.setAudioInputDevice(deviceId);

CometChatCalls.setAudioInputDevice(deviceId);

Set Audio Output Device

Sets the active audio output device (speaker/headphones) by device ID.

TypeScript
JavaScript

CometChatCalls.setAudioOutputDevice(deviceId);

CometChatCalls.setAudioOutputDevice(deviceId);

Set Video Input Device

Sets the active video input device (camera) by device ID.

TypeScript
JavaScript

CometChatCalls.setVideoInputDevice(deviceId);

CometChatCalls.setVideoInputDevice(deviceId);

Switch To Video Call

Upgrades an ongoing audio call to a video call. This enables the camera and starts transmitting video to other participants. The remote participant receives the onCallSwitchedToVideo() callback.

TypeScript
JavaScript

CometChatCalls.switchToVideoCall();

CometChatCalls.switchToVideoCall();

End Call

Terminates the current call session and releases all media resources (camera, microphone, network connections). After calling this method, the call view should be closed.

JavaScript / TypeScript

CometChatCalls.endSession();

Utility Methods

Get Active Call

Returns the current active Call object, or undefined if no call is in progress.

TypeScript
JavaScript

const activeCall: CometChat.Call | undefined = CometChat.getActiveCall();
if (activeCall) {
  console.log("Active call session:", activeCall.getSessionId());
}

const activeCall = CometChat.getActiveCall();
if (activeCall) {
  console.log("Active call session:", activeCall.getSessionId());
}

Clear Active Call

Clears the locally stored active call state. Call this after ending a call session.

TypeScript
JavaScript

CometChat.clearActiveCall();

CometChat.clearActiveCall();

Returns the number of participants currently in a call session.

TypeScript
JavaScript

let sessionId: string = "SESSION_ID";
let type: string = "direct"; // "direct" or "default"

CometChat.getCallParticipantCount(sessionId, type).then(
  (count: number) => {
    console.log("Participant count:", count);
  },
  (error: CometChat.CometChatException) => {
    console.log("Error:", error);
  }
);

let sessionId = "SESSION_ID";
let type = "direct"; // "direct" or "default"

CometChat.getCallParticipantCount(sessionId, type).then(
  (count) => {
    console.log("Participant count:", count);
  },
  (error) => {
    console.log("Error:", error);
  }
);

Parameter	Type	Description
`sessionId`	`string`	The call session ID
`type`	`string`	Call type: `"direct"` or `"default"`

Next Steps

Default Calling (Ringing)

Implement calls with incoming/outgoing ringing UI

Recording

Record call sessions for playback

Video View Customisation

Customize the video layout and main video container

Call Logs

Retrieve and display call history

​Generate Call Token

​Start Call Session

​Call Settings

​End Call Session

​Ringing Flow

​Session Only Flow

​Call Listeners

​Events

​In-Call Methods

​Switch Camera

​Mute Audio

​Pause Video

​Start Screen Share

​Stop Screen Share

​Set Mode

​Get Audio Input Devices

​Get Audio Output Devices

​Get Video Input Devices

​Set Audio Input Device

​Set Audio Output Device

​Set Video Input Device

​Switch To Video Call

​End Call

​Utility Methods

​Get Active Call

​Clear Active Call

​Next Steps

Default Calling (Ringing)

Recording

Video View Customisation

Call Logs

Generate Call Token

Start Call Session

Call Settings

End Call Session

Ringing Flow

Session Only Flow

Call Listeners

Events

In-Call Methods

Switch Camera

Mute Audio

Pause Video

Start Screen Share

Stop Screen Share

Set Mode

Get Audio Input Devices

Get Audio Output Devices

Get Video Input Devices

Set Audio Input Device

Set Audio Output Device

Set Video Input Device

Switch To Video Call

End Call

Utility Methods

Get Active Call

Clear Active Call

Next Steps