> ## 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. # Call Session > CometChat Calling SDK v4 - Stable Release - Call Session for JavaScript ## Overview This section demonstrates how to start a call session in a web application. Previously known as **Direct Calling**. Before you begin, we strongly recommend you read the [calling setup guide](/calls/v4/javascript/setup). If you want to implement a complete calling experience with ringing functionality (incoming/outgoing call UI), follow the [Ringing](/calls/v4/javascript/ringing) guide first. Once the call is accepted, return here to start the call session. ## 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. Use the `generateToken()` method to create a call token: ```javascript theme={null} 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); } ); ``` ```typescript theme={null} 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); } ); ``` | 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()` | ## Start Call Session Use the `startSession()` method to join a call session. This method requires: 1. A call token (generated in the previous step) 2. A `CallSettings` object that configures the call UI and behavior 3. An HTML element where the call UI will be rendered ```javascript theme={null} 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); ``` ```typescript theme={null} 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); ``` | 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](#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](/calls/v4/javascript/video-view-customisation). | | `setIdleTimeoutPeriod(number)` | Sets idle timeout in seconds. Warning appears 60 seconds before auto-termination. Default: `180` seconds. *v4.1.0+* | ## 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: 1. **Via CallSettingsBuilder:** Use `.setCallListener(listener)` when building call settings 2. **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 ```javascript theme={null} 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); ``` ```typescript theme={null} 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); ``` ### Events | Event | Description | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `onCallEnded()` | Invoked when the call session terminates for a 1:1 call. Both participants receive this callback. Only fires for calls with exactly 2 participants. | | `onSessionTimeout()` | Invoked when the call is auto-terminated due to inactivity (default: 180 seconds). Warning appears 60 seconds before. *v4.1.0+* | | `onCallEndButtonPressed()` | Invoked when the local user clicks the end call button. For ringing flow, call `CometChat.endCall()`. For standalone, call `CometChatCalls.endSession()`. | | `onUserJoined(user)` | Invoked when a remote participant joins. The `user` contains UID, name, and avatar. | | `onUserLeft(user)` | Invoked when a remote participant leaves the call session. | | `onUserListUpdated(userList)` | Invoked whenever the participant list changes (join or leave events). | | `onMediaDeviceListUpdated(deviceList)` | Invoked when available audio/video devices change (e.g., new microphone connected). | | `onUserMuted(event)` | Invoked when a participant's mute state changes. Contains `muted` and `mutedBy` properties. | | `onScreenShareStarted()` | Invoked when the local user starts sharing their screen. | | `onScreenShareStopped()` | Invoked when the local user stops sharing their screen. | | `onCallSwitchedToVideo(event)` | Invoked when an audio call is upgraded to a video call. Contains `sessionId`, `initiator`, and `responder`. | | `onError(error)` | Invoked when an error occurs during the call session. | ## End Call Session Ending a call session properly is essential to release media resources (camera, microphone, network connections) and update call state across all participants. The termination process differs based on whether you're using the Ringing flow or Session Only flow. ### Ringing Flow When using the [Ringing](/calls/v4/javascript/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. ```javascript theme={null} 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); } ); } ``` ```typescript theme={null} 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); } ); } ``` **Remote participant** (receives the `onCallEnded()` callback): Call `CometChat.clearActiveCall()` to clear the local call state, then call `CometChatCalls.endSession()` to release media resources. ```javascript theme={null} onCallEnded: () => { CometChat.clearActiveCall(); CometChatCalls.endSession(); // Close the calling screen } ``` ```typescript theme={null} 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. Call `CometChatCalls.endSession()` in the `onCallEndButtonPressed()` callback to release all media resources and disconnect from the call session. ```javascript theme={null} onCallEndButtonPressed: () => { CometChatCalls.endSession(); // Close the calling screen } ``` ```typescript theme={null} onCallEndButtonPressed: () => { CometChatCalls.endSession(); // Close the calling screen } ``` ## 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. ```javascript theme={null} CometChatCalls.switchCamera(); ``` ```typescript theme={null} 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 ```javascript theme={null} CometChatCalls.muteAudio(true); ``` ```typescript theme={null} 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 ```javascript theme={null} CometChatCalls.pauseVideo(true); ``` ```typescript theme={null} CometChatCalls.pauseVideo(true); ``` ### Start Screen Share Starts sharing your screen or a specific application window with other participants. ```javascript theme={null} CometChatCalls.startScreenShare(); ``` ```typescript theme={null} CometChatCalls.startScreenShare(); ``` ### Stop Screen Share Stops the current screen sharing session. ```javascript theme={null} CometChatCalls.stopScreenShare(); ``` ```typescript theme={null} 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 ```javascript theme={null} CometChatCalls.setMode(CometChat.CALL_MODE.SPOTLIGHT); ``` ```typescript theme={null} CometChatCalls.setMode(CometChat.CALL_MODE.SPOTLIGHT); ``` ### Get Audio Input Devices Returns a list of available audio input devices (microphones). ```javascript theme={null} const audioInputDevices = CometChatCalls.getAudioInputDevices(); console.log("Available microphones:", audioInputDevices); ``` ```typescript theme={null} const audioInputDevices = CometChatCalls.getAudioInputDevices(); console.log("Available microphones:", audioInputDevices); ``` ### Get Audio Output Devices Returns a list of available audio output devices (speakers/headphones). ```javascript theme={null} const audioOutputDevices = CometChatCalls.getAudioOutputDevices(); console.log("Available speakers:", audioOutputDevices); ``` ```typescript theme={null} const audioOutputDevices = CometChatCalls.getAudioOutputDevices(); console.log("Available speakers:", audioOutputDevices); ``` ### Get Video Input Devices Returns a list of available video input devices (cameras). ```javascript theme={null} const videoInputDevices = CometChatCalls.getVideoInputDevices(); console.log("Available cameras:", videoInputDevices); ``` ```typescript theme={null} const videoInputDevices = CometChatCalls.getVideoInputDevices(); console.log("Available cameras:", videoInputDevices); ``` ### Set Audio Input Device Sets the active audio input device (microphone) by device ID. ```javascript theme={null} CometChatCalls.setAudioInputDevice(deviceId); ``` ```typescript theme={null} CometChatCalls.setAudioInputDevice(deviceId); ``` ### Set Audio Output Device Sets the active audio output device (speaker/headphones) by device ID. ```javascript theme={null} CometChatCalls.setAudioOutputDevice(deviceId); ``` ```typescript theme={null} CometChatCalls.setAudioOutputDevice(deviceId); ``` ### Set Video Input Device Sets the active video input device (camera) by device ID. ```javascript theme={null} CometChatCalls.setVideoInputDevice(deviceId); ``` ```typescript theme={null} 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. ```javascript theme={null} CometChatCalls.switchToVideoCall(); ``` ```typescript theme={null} 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 theme={null} CometChatCalls.endSession(); ``` ```typescript theme={null} CometChatCalls.endSession(); ```