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 entire bottom control bar
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 output (route) button
hideRecordingButton	boolean	true	Hide the recording button
hideChangeLayoutButton	boolean	false	Hide the layout-switcher button
hideParticipantListButton	boolean	false	Hide the button that opens the participant list
hideChatButton	boolean	true	Hide the in-call chat button
hideRaiseHandButton	boolean	false	Hide the raise-hand button
hideShareInviteButton	boolean	true	Hide the share / invite 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	60000	Milliseconds you may remain alone in the call before the idle prompt appears
idleTimeoutPeriodAfterPrompt	number	180000	Milliseconds the prompt stays on screen waiting for a response 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,
};

Header & Status Indicators

Property	Type	Default	Description
title	string	''	Title text shown in the call’s header panel (for example, the room name)
hideHeaderPanel	boolean	false	Hide the top header bar (title, session timer, etc.)
hideSessionTimer	boolean	false	Hide the elapsed-time timer
hideNetworkIndicator	boolean	true	Hide the per-participant network-quality indicator
hideRecordingStatusIndicator	boolean	false	Hide the “recording in progress” badge (recording itself is unaffected)

const sessionSettings = {
  title: 'Team Standup',
  hideSessionTimer: false,
  hideNetworkIndicator: false,
};

Identity & Behavior

Property	Type	Default	Description
displayName	string	''	Display name shown for the local user. Falls back to the logged-in user’s name when empty
initialCameraFacing	string	-	Which camera to use at call start: 'FRONT' or 'REAR'. The user can still switch afterwards
enableNotifications	boolean	true	Show the in-call toast notifications surfaced by the SDK (e.g. “X joined the call”). Set false to suppress them
enableParticipantContextMenu	boolean	true	Enable the per-participant long-press context menu (pin, etc.). Unavailable in 'SPOTLIGHT' and picture-in-picture layouts

const sessionSettings = {
  displayName: 'Alex',
  initialCameraFacing: 'FRONT',
  enableNotifications: 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