SessionSettingsBuilder

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

The SessionSettingsBuilder is a powerful configuration tool that 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, this builder gives you complete control over the call experience.

Proper session configuration is crucial for creating a seamless user experience tailored to your application’s specific needs.

These are pre-session configurations that must be set before joining a call. Once configured, pass the SessionSettings object to the joinSession() method. Settings cannot be changed after the session has started, though many features can be controlled dynamically during the call using call actions.

Swift

let sessionSettings = CometChatCalls.sessionSettingsBuilder
    .setTitle("Team Meeting")
    .setDisplayName("John Doe")
    .setType(.video)
    .setLayout(.tile)
    .startAudioMuted(false)
    .startVideoPaused(false)
    .build()

Objective-C

SessionSettings *sessionSettings = [[[[[[[CometChatCalls sessionSettingsBuilder]
    setTitle:@"Team Meeting"]
    setDisplayName:@"John Doe"]
    setType:CallTypeVideo]
    setLayout:LayoutTypeTile]
    startAudioMuted:NO]
    startVideoPaused:NO]
    build];

Session Settings

Title

Method: setTitle(_ title: String)

Sets the title that appears in the call header. This helps participants identify the purpose or name of the call session. The title is displayed prominently at the top of the call interface.

Swift

.setTitle("Team Meeting")

Objective-C

[builder setTitle:@"Team Meeting"]

Parameter	Type	Default
title	String	nil

Display Name

Method: setDisplayName(_ name: String)

Sets the display name that will be shown to other participants in the call. This name appears on your video tile and in the participant list, helping others identify you during the session.

Swift

.setDisplayName("John Doe")

Objective-C

[builder setDisplayName:@"John Doe"]

Parameter	Type	Default
name	String	nil

Session Type

Method: setType(_ type: CallType)

Defines the type of call session. Choose .video for video calls with camera enabled, or .audio for audio-only calls. This setting determines whether video streaming is enabled by default.

Swift

.setType(.video)

Objective-C

[builder setType:CallTypeVideo]

Parameter	Type	Default
type	CallType	.video

CallType Values

Value	Description
.video	Video call with camera enabled
.audio	Audio-only call

Layout Mode

Method: setLayout(_ layoutType: LayoutType)

Sets the initial layout mode for displaying participants. .tile shows all participants in a grid, .spotlight focuses on the active speaker with others in a sidebar, and .sidebar displays the main speaker with participants in a side panel.

Swift

.setLayout(.tile)

Objective-C

[builder setLayout:LayoutTypeTile]

Parameter	Type	Default
layoutType	LayoutType	.tile

LayoutType Values

Value	Description
.tile	Grid layout showing all participants equally
.spotlight	Focus on active speaker with others in sidebar
.sidebar	Main speaker with participants in a sidebar

Idle Timeout Period

Method: setIdleTimeoutPeriod(_ timeoutSeconds: Int)

Configures the timeout duration in seconds before automatically ending the session when you’re the only participant. This prevents sessions from running indefinitely when others have left.

Swift

.setIdleTimeoutPeriod(300)

Objective-C

[builder setIdleTimeoutPeriod:300]

Parameter	Type	Default
timeoutSeconds	Int	300

Start Audio Muted

Method: startAudioMuted(_ muted: Bool)

Determines whether the microphone is muted when joining the session. Set to true to join with audio muted, requiring users to manually unmute. Useful for large meetings to prevent background noise.

Swift

.startAudioMuted(true)

Objective-C

[builder startAudioMuted:YES]

Parameter	Type	Default
muted	Bool	false

Start Video Paused

Method: startVideoPaused(_ muted: Bool)

Controls whether the camera is turned off when joining the session. Set to true to join with video disabled, allowing users to enable it when ready. Helpful for privacy or bandwidth considerations.

Swift

.startVideoPaused(true)

Objective-C

[builder startVideoPaused:YES]

Parameter	Type	Default
muted	Bool	false

Audio Mode

Method: setAudioMode(_ audioMode: AudioModeType)

Sets the initial audio output device for the call. Options include .speaker for loudspeaker, .earpiece for phone earpiece, .bluetooth for connected Bluetooth devices, or .headphones for wired headphones.

Swift

.setAudioMode(.speaker)

Objective-C

[builder setAudioMode:AudioModeTypeSpeaker]

Parameter	Type	Default
audioMode	AudioModeType	.speaker

AudioModeType Values

Value	Description
.speaker	Device loudspeaker
.earpiece	Phone earpiece
.bluetooth	Connected Bluetooth device
.headphones	Wired headphones

Initial Camera Facing

Method: setInitialCameraFacing(_ initialCameraFacing: CameraFacing)

Specifies which camera to use when starting the session. Choose .FRONT for the front-facing camera (selfie mode) or .BACK for the rear camera. Users can switch cameras during the call.

Swift

.setInitialCameraFacing(.FRONT)

Objective-C

[builder setInitialCameraFacing:CameraFacingFRONT]

Parameter	Type	Default
initialCameraFacing	CameraFacing	.FRONT

CameraFacing Values

Value	Description
.FRONT	Front-facing camera
.BACK	Rear camera

Auto Start Recording

Method: enableAutoStartRecording(_ enabled: Bool)

Automatically starts recording the session as soon as it begins. When enabled, recording starts without manual intervention, ensuring the entire session is captured from the start.

Swift

.enableAutoStartRecording(true)

Objective-C

[builder enableAutoStartRecording:YES]

Parameter	Type	Default
enabled	Bool	false

Hide Control Panel

Method: hideControlPanel(_ hidden: Bool)

Hides the bottom control bar that contains call action buttons. Set to true to remove the control panel entirely, useful for custom UI implementations or view-only modes.

Swift

.hideControlPanel(true)

Objective-C

[builder hideControlPanel:YES]

Parameter	Type	Default
hidden	Bool	false

Hide Header Panel

Method: hideHeaderPanel(_ hidden: Bool)

Hides the top header bar that displays the call title and session information. Set to true to maximize the video viewing area or implement a custom header.

Swift

.hideHeaderPanel(true)

Objective-C

[builder hideHeaderPanel:YES]

Parameter	Type	Default
hidden	Bool	false

Hide Session Timer

Method: hideSessionTimer(_ hidden: Bool)

Hides the session duration timer that shows how long the call has been active. Set to true to remove the timer display from the interface.

Swift

.hideSessionTimer(true)

Objective-C

[builder hideSessionTimer:YES]

Parameter	Type	Default
hidden	Bool	false

Hide Leave Session Button

Method: hideLeaveSessionButton(_ hidden: Bool)

Hides the button that allows users to leave or end the call. Set to true to remove this button, requiring an alternative method to exit the session.

Swift

.hideLeaveSessionButton(true)

Objective-C

[builder hideLeaveSessionButton:YES]

Parameter	Type	Default
hidden	Bool	false

Hide Toggle Audio Button

Method: hideToggleAudioButton(_ hidden: Bool)

Hides the microphone mute/unmute button from the control panel. Set to true to remove audio controls, useful when audio control should be managed programmatically.

Swift

.hideToggleAudioButton(true)

Objective-C

[builder hideToggleAudioButton:YES]

Parameter	Type	Default
hidden	Bool	false

Hide Toggle Video Button

Method: hideToggleVideoButton(_ hidden: Bool)

Hides the camera on/off button from the control panel. Set to true to remove video controls, useful for audio-only calls or custom video control implementations.

Swift

.hideToggleVideoButton(true)

Objective-C

[builder hideToggleVideoButton:YES]

Parameter	Type	Default
hidden	Bool	false

Hide Switch Camera Button

Method: hideSwitchCameraButton(_ enabled: Bool)

Hides the button that allows switching between front and rear cameras. Set to true to remove this control, useful for devices with single cameras or fixed camera requirements.

Swift

.hideSwitchCameraButton(true)

Objective-C

[builder hideSwitchCameraButton:YES]

Parameter	Type	Default
enabled	Bool	false

Hide Recording Button

Method: hideRecordingButton(_ enabled: Bool)

Hides the recording start/stop button from the control panel. Set to false to show the recording button, allowing users to manually control session recording.

Swift

.hideRecordingButton(false)

Objective-C

[builder hideRecordingButton:NO]

Parameter	Type	Default
enabled	Bool	true

Hide Audio Mode Button

Method: hideAudioModeButton(_ enabled: Bool)

Hides the button that toggles between speaker, earpiece, and other audio output modes. Set to true to remove audio mode controls from the interface.

Swift

.hideAudioModeButton(true)

Objective-C

[builder hideAudioModeButton:YES]

Parameter	Type	Default
enabled	Bool	false

Hide Raise Hand Button

Method: hideRaiseHandButton(_ enabled: Bool)

Hides the raise hand button that participants use to signal they want to speak. Set to true to remove this feature from the interface.

Swift

.hideRaiseHandButton(true)

Objective-C

[builder hideRaiseHandButton:YES]

Parameter	Type	Default
enabled	Bool	false

Hide Share Invite Button

Method: hideShareInviteButton(_ enabled: Bool)

Hides the button that allows sharing session invite links with others. Set to false to show the invite button, enabling easy participant invitation.

Swift

.hideShareInviteButton(false)

Objective-C

[builder hideShareInviteButton:NO]

Parameter	Type	Default
enabled	Bool	true

Hide Participant List Button

Method: hideParticipantListButton(_ hidden: Bool)

Hides the button that opens the participant list view. Set to true to remove access to the participant list, useful for simplified interfaces.

Swift

.hideParticipantListButton(true)

Objective-C

[builder hideParticipantListButton:YES]

Parameter	Type	Default
hidden	Bool	false

Hide Change Layout Button

Method: hideChangeLayoutButton(_ hidden: Bool)

Hides the button that allows switching between different layout modes (tile, spotlight, sidebar). Set to true to lock the layout to the initial setting.

Swift

.hideChangeLayoutButton(true)

Objective-C

[builder hideChangeLayoutButton:YES]

Parameter	Type	Default
hidden	Bool	false

Hide Chat Button

Method: hideChatButton(_ hidden: Bool)

Hides the button that opens the in-call chat interface. Set to false to show the chat button, enabling text communication during calls.

Swift

.hideChatButton(false)

Objective-C

[builder hideChatButton:NO]

Parameter	Type	Default
hidden	Bool	true

Enum Values

Enum	Value	Description
CallType	.video	Video call with camera enabled
	.audio	Audio-only call
LayoutType	.tile	Grid layout showing all participants equally
	.spotlight	Focus on active speaker with others in sidebar
	.sidebar	Main speaker with participants in a sidebar
AudioModeType	.speaker	Device loudspeaker
	.earpiece	Phone earpiece
	.bluetooth	Connected Bluetooth device
	.headphones	Wired headphones
CameraFacing	.FRONT	Front-facing camera
	.BACK	Rear camera