Session Settings

Configure CometChat Calls SDK v5 session settings on JavaScript for call behavior, UI options, participant controls, and features.

The session settings object allows you to customize every aspect of your call session before participants join. From controlling the initial audio/video state to customizing the UI layout and hiding specific controls, these settings give you complete control over the call experience.

These are pre-session configurations that must be set before joining a call. Once configured, pass the settings object to the joinSession() method, or, for a ringing call, to initiateCall() (as sessionSettings) or connect(). A session prepared by initiateCall() or connect() keeps the settings it was prepared with: session.join(container) takes none. Settings cannot be changed after the session has started, though many features can be controlled dynamically during the call using call actions.

const callSettings = {
  sessionType: "VIDEO",
  layout: "TILE",
  startAudioMuted: false,
  startVideoPaused: false,
  hideControlPanel: false,
  hideLeaveSessionButton: false,
  hideToggleAudioButton: false,
  hideToggleVideoButton: false,
};

​

Session Settings

​

Session Type

Property: sessionType

Defines the type of call session. Choose VIDEO for video calls with camera enabled, or VOICE for audio-only calls.

sessionType: "VIDEO"

Value	Description
VIDEO	Video call with camera enabled
VOICE	Audio-only call

Default: VIDEO

​

Peer Call

Property: isPeerCall

Marks the session as a one-to-one call. In a peer call, when one participant leaves, the session ends for both instead of continuing with one person in it. The SDK also watches the other participant’s connection and reports onRemoteConnectionLost when no media statistics arrive from them for 10 seconds, and onRemoteConnectionRestored when they resume. Set it for every 1:1 ringing call; leave it off for group calls and meetings.

isPeerCall: true

Default: false

​

Layout Mode

Property: layout

Sets the initial layout mode for displaying participants.

layout: "TILE"

Value	Description
TILE	Grid layout showing all participants equally
SIDEBAR	Main speaker with participants in a sidebar
SPOTLIGHT	Focus on active speaker with others in sidebar

Default: TILE

​

Start Audio Muted

Property: startAudioMuted

Determines whether the microphone is muted when joining the session.

startAudioMuted: true

Default: false

​

Start Video Paused

Property: startVideoPaused

Controls whether the camera is turned off when joining the session.

startVideoPaused: true

Default: false

​

Auto Start Recording

Property: autoStartRecording

Automatically starts recording the session as soon as it begins.

autoStartRecording: true

Default: false

​

Auto Start Transcription

Available since v5.0.5

Property: autoStartTranscription

Automatically starts transcribing the session as soon as it begins. See Transcription for details.

autoStartTranscription: true

Default: false

​

Caption Language

Available since v5.0.5

Property: captionLanguage

Sets the language used for transcription and closed captions. See Transcription for the full list of supported codes.

captionLanguage: "en-US"

Default: en-US

​

Idle Timeout Period Before Prompt

Property: idleTimeoutPeriodBeforePrompt

Time in milliseconds before showing the idle timeout prompt when you’re the only participant.

idleTimeoutPeriodBeforePrompt: 60000 // 60 seconds

Default: 60000 (60 seconds)

​

Idle Timeout Period After Prompt

Property: idleTimeoutPeriodAfterPrompt

Time in milliseconds after the prompt before automatically ending the session.

idleTimeoutPeriodAfterPrompt: 180000 // 180 seconds (3 minutes)

Default: 180000 (180 seconds / 3 minutes)

​

UI Visibility Settings

​

Hide Control Panel

Property: hideControlPanel

Hides the bottom control bar that contains call action buttons.

hideControlPanel: true

Default: false

​

Hide Leave Session Button

Property: hideLeaveSessionButton

Hides the button that allows users to leave or end the call.

hideLeaveSessionButton: true

Default: false

​

Hide Toggle Audio Button

Property: hideToggleAudioButton

Hides the microphone mute/unmute button from the control panel.

hideToggleAudioButton: true

Default: false

​

Hide Toggle Video Button

Property: hideToggleVideoButton

Hides the camera on/off button from the control panel.

hideToggleVideoButton: true

Default: false

​

Hide Recording Button

Property: hideRecordingButton

Hides the recording start/stop button from the control panel.

hideRecordingButton: true

Default: true

​

Hide Transcription Button

Available since v5.0.5

Property: hideTranscriptionButton

Hides the transcription start/stop item from the control panel’s More menu.

hideTranscriptionButton: false

Default: true

​

Hide Closed Caption Button

Available since v5.0.5

Property: hideClosedCaptionButton

Hides the closed-caption (CC) button from the control panel. Even when set to false, the button only appears while transcription is running.

hideClosedCaptionButton: false

Default: true

​

Hide Screen Sharing Button

Property: hideScreenSharingButton

Hides the screen sharing button from the control panel.

hideScreenSharingButton: true

Default: false

​

Hide Change Layout Button

Property: hideChangeLayoutButton

Hides the button that allows switching between different layout modes.

hideChangeLayoutButton: true

Default: false

​

Hide Virtual Background Button

Property: hideVirtualBackgroundButton

Hides the virtual background settings button.

hideVirtualBackgroundButton: true

Default: false

​

Virtual Background

Property: virtualBackground

Configures the virtual background picker (images, user uploads, blur options) and engine. See Virtual Background for all options.

virtualBackground: {
  images: ["https://cdn.example.com/backgrounds/office.jpg"],
  allowUserImages: false,
  allowBlur: true,
}

Default: undefined (built-in images, uploads and blur enabled)

​

Hide Network Indicator

Property: hideNetworkIndicator

Hides the network quality indicator.

hideNetworkIndicator: true

Default: true

​

Complete Example

const callSettings = {
  // Session configuration
  sessionType: "VIDEO",
  layout: "TILE",
  startAudioMuted: false,
  startVideoPaused: false,
  autoStartRecording: false,
  autoStartTranscription: false,
  captionLanguage: "en-US",
  
  // Timeout settings
  idleTimeoutPeriodBeforePrompt: 60000,
  idleTimeoutPeriodAfterPrompt: 180000,
  
  // UI visibility
  hideControlPanel: false,
  hideLeaveSessionButton: false,
  hideToggleAudioButton: false,
  hideToggleVideoButton: false,
  hideRecordingButton: true,
  hideTranscriptionButton: true,
  hideClosedCaptionButton: true,
  hideScreenSharingButton: false,
  hideChangeLayoutButton: false,
  hideVirtualBackgroundButton: false,
  hideNetworkIndicator: true,
};

All Settings Reference

Property	Type	Default	Description
sessionType	String	VIDEO	Call type: VIDEO or VOICE
isPeerCall	Boolean	false	One-to-one call: the session ends for both when either participant leaves
layout	String	TILE	Layout: TILE, SIDEBAR, or SPOTLIGHT
startAudioMuted	Boolean	false	Start with microphone muted
startVideoPaused	Boolean	false	Start with camera off
autoStartRecording	Boolean	false	Auto-start recording
autoStartTranscription	Boolean	false	Auto-start transcription
captionLanguage	String	en-US	Transcription / caption language code
idleTimeoutPeriodBeforePrompt	Number	60000	Idle timeout before prompt (ms)
idleTimeoutPeriodAfterPrompt	Number	180000	Idle timeout after prompt (ms)
hideControlPanel	Boolean	false	Hide control panel
hideLeaveSessionButton	Boolean	false	Hide leave button
hideToggleAudioButton	Boolean	false	Hide audio toggle
hideToggleVideoButton	Boolean	false	Hide video toggle
hideRecordingButton	Boolean	true	Hide recording button
hideTranscriptionButton	Boolean	true	Hide transcription button
hideClosedCaptionButton	Boolean	true	Hide closed caption button
hideScreenSharingButton	Boolean	false	Hide screen share button
hideChangeLayoutButton	Boolean	false	Hide layout change button
hideVirtualBackgroundButton	Boolean	false	Hide virtual background button
virtualBackground	Object	undefined	Virtual background picker and engine configuration
hideNetworkIndicator	Boolean	true	Hide network indicator