Session Settings - CometChat Docs

Configure call sessions using a plain sessionSettings object. This allows you to customize the call UI, behavior, and features.

Session Settings Object

The sessionSettings object is a plain JavaScript object whose properties configure the call session. Pass it to CometChatCalls.Component via the sessionSettings prop:

import { CometChatCalls } from '@cometchat/calls-sdk-react-native';

const sessionSettings = {
  sessionType: 'VIDEO',
  layout: 'TILE',
  hideLeaveSessionButton: false,
  hideToggleAudioButton: false,
  hideToggleVideoButton: false,
  hideSwitchCameraButton: false,
  hideAudioModeButton: false,
  startAudioMuted: false,
  startVideoPaused: false,
  audioMode: 'SPEAKER',
  hideRecordingButton: true,
  autoStartRecording: false,
  idleTimeoutPeriodBeforePrompt: 180000,
  enableSpotlightSwap: true,
  enableSpotlightDrag: true,
};

Configuration Options

Call Type

Property	Type	Default	Description
`sessionType`	string	`'VIDEO'`	Set to `'VOICE'` for audio-only calls or `'VIDEO'` for video calls

// Audio-only call
const audioCallSettings = {
  sessionType: 'VOICE',
};

// Video call (default)
const videoCallSettings = {
  sessionType: 'VIDEO',
};

Layout Mode

Property	Type	Default	Description
`layout`	string	`'TILE'`	Call layout mode

Available layouts:

Layout	Description
`'TILE'`	Grid layout with all participants visible
`'SIDEBAR'`	Focus on one participant with others in a sidebar
`'SPOTLIGHT'`	Focus on one participant with others overlaid

const sessionSettings = {
  layout: 'SPOTLIGHT',
};

UI Controls

Property	Type	Default	Description
`hideControlPanel`	boolean	`false`	Hide the default button layout
`hideLeaveSessionButton`	boolean	`false`	Hide the leave session button
`hideToggleAudioButton`	boolean	`false`	Hide the mute audio button
`hideToggleVideoButton`	boolean	`false`	Hide the pause video button
`hideSwitchCameraButton`	boolean	`false`	Hide the switch camera button
`hideAudioModeButton`	boolean	`false`	Hide the audio mode button
`hideRecordingButton`	boolean	`true`	Hide the recording button

const sessionSettings = {
  hideControlPanel: false,
  hideLeaveSessionButton: false,
  hideToggleAudioButton: false,
  hideToggleVideoButton: false,
  hideSwitchCameraButton: false,
  hideAudioModeButton: false,
  hideRecordingButton: false,
};

Initial State

Property	Type	Default	Description
`startAudioMuted`	boolean	`false`	Start call with audio muted
`startVideoPaused`	boolean	`false`	Start call with video paused
`audioMode`	string	-	Set the default audio output mode

Available audio modes:

Mode	Description
`'SPEAKER'`	Phone speaker
`'EARPIECE'`	Phone earpiece
`'BLUETOOTH'`	Bluetooth device
`'HEADPHONES'`	Wired headphones

const sessionSettings = {
  startAudioMuted: true,
  startVideoPaused: false,
  audioMode: 'SPEAKER',
};

Recording

Property	Type	Default	Description
`hideRecordingButton`	boolean	`true`	Hide the recording button
`autoStartRecording`	boolean	`false`	Auto-start recording when call begins

const sessionSettings = {
  hideRecordingButton: false,
  autoStartRecording: true,
};

Idle Timeout

Property	Type	Default	Description
`idleTimeoutPeriodBeforePrompt`	number	`180000`	Milliseconds of inactivity before the prompt appears
`idleTimeoutPeriodAfterPrompt`	number	`120000`	Milliseconds the user has to respond before the session ends

const sessionSettings = {
  idleTimeoutPeriodBeforePrompt: 300000, // 5 minutes
  idleTimeoutPeriodAfterPrompt: 120000,  // 2 minutes
};

Video Tile Interaction

Property	Type	Default	Description
`enableSpotlightSwap`	boolean	`true`	Enable clicking video tiles to swap in Spotlight mode
`enableSpotlightDrag`	boolean	`true`	Enable dragging video tiles in Spotlight mode

const sessionSettings = {
  enableSpotlightSwap: true,
  enableSpotlightDrag: true,
};

Event Subscription

Subscribe to call events with CometChatCalls.addEventListener. Pass an AbortSignal to each listener and call controller.abort() once to remove them all on cleanup:

const controller = new AbortController();

CometChatCalls.addEventListener('onParticipantJoined', (participant) => {
  console.log('Participant joined:', participant);
}, { signal: controller.signal });

CometChatCalls.addEventListener('onParticipantLeft', (participant) => {
  console.log('Participant left:', participant);
}, { signal: controller.signal });

CometChatCalls.addEventListener('onParticipantListChanged', (participants) => {
  console.log('Participant list changed:', participants);
}, { signal: controller.signal });

CometChatCalls.addEventListener('onSessionLeft', () => {
  console.log('Session left');
}, { signal: controller.signal });

CometChatCalls.addEventListener('onLeaveSessionButtonClicked', () => {
  console.log('Leave session button clicked');
}, { signal: controller.signal });

CometChatCalls.addEventListener('onAudioModeChanged', (mode) => {
  console.log('Audio mode changed:', mode);
}, { signal: controller.signal });

CometChatCalls.addEventListener('onRecordingStarted', () => {
  console.log('Recording started');
}, { signal: controller.signal });

CometChatCalls.addEventListener('onRecordingStopped', () => {
  console.log('Recording stopped');
}, { signal: controller.signal });

CometChatCalls.addEventListener('onParticipantAudioMuted', (participant) => {
  console.log('Participant muted:', participant);
}, { signal: controller.signal });

CometChatCalls.addEventListener('onSessionTimedOut', () => {
  console.log('Session timed out');
}, { signal: controller.signal });

// Later, on cleanup
controller.abort();

Complete Example

import React, { useEffect, useMemo } from 'react';
import { CometChatCalls } from '@cometchat/calls-sdk-react-native';

function useCallEvents() {
  useEffect(() => {
    const controller = new AbortController();
    const { signal } = controller;

    CometChatCalls.addEventListener('onParticipantJoined', (participant) => {
      console.log('Participant joined:', participant.name);
    }, { signal });
    
    CometChatCalls.addEventListener('onParticipantLeft', (participant) => {
      console.log('Participant left:', participant.name);
    }, { signal });
    
    CometChatCalls.addEventListener('onSessionLeft', () => {
      console.log('Session left');
      // Navigate back or update UI
    }, { signal });

    return () => controller.abort();
  }, []);
}

function createSessionSettings(isAudioOnly: boolean = false) {
  return {
    sessionType: isAudioOnly ? 'VOICE' : 'VIDEO',
    layout: 'TILE',
    hideControlPanel: false,
    hideLeaveSessionButton: false,
    hideToggleAudioButton: false,
    hideToggleVideoButton: isAudioOnly,
    hideSwitchCameraButton: isAudioOnly,
    hideAudioModeButton: false,
    startAudioMuted: false,
    startVideoPaused: false,
    audioMode: 'SPEAKER',
    hideRecordingButton: false,
    idleTimeoutPeriodBeforePrompt: 180000,
  };
}

// Create video session settings
const videoSessionSettings = createSessionSettings(false);

// Create audio session settings
const audioSessionSettings = createSessionSettings(true);

Join Session - Start a call with these settings
Events - Detailed event documentation
Actions - Control the call programmatically

​Session Settings Object

​Configuration Options

​Call Type

​Layout Mode

​UI Controls

​Initial State

​Recording

​Idle Timeout

​Video Tile Interaction

​Event Subscription

​Complete Example

​Related Documentation