Session Settings

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

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);

Related Documentation

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