Call Session - CometChat Docs

Quick Reference for AI Agents & Developers

Generate token: CometChat.generateToken(sessionID:onSuccess:onError:)
Start call: CometChatCalls.startSession(callToken:callSettings:onSuccess:onError:)
End call: CometChatCalls.endSession()
Call settings: CometChatCalls.callSettingsBuilder.setDefaultLayout(true).build()
Related: Ringing · Call Logs · Calling Overview

Overview

This section demonstrates how to start a call session in an iOS application. Previously known as Direct Calling. Before you begin, we strongly recommend you read the calling setup guide.

If you want to implement a complete calling experience with ringing functionality (incoming/outgoing call UI), follow the Ringing guide first. Once the call is accepted, return here to start the call session.

Generate Call Token

A call token is required for secure access to a call session. Each token is unique to a specific session and user combination, ensuring that only authorized users can join the call. You can generate the token just before starting the call, or generate and store it ahead of time based on your use case. Use the generateToken() method to create a call token:

Swift

var callToken: GenerateToken?

let sessionId = "UNIQUE_SESSION_ID" // Random or from Call object in ringing flow
let authToken = CometChat.getUserAuthToken() // Logged in user auth token

CometChatCalls.generateToken(authToken: authToken as NSString, sessionID: sessionId) { token in
    self.callToken = token
} onError: { error in
    print("Token generation failed: \(String(describing: error?.errorDescription))")
}

Parameter	Description
`sessionId`	The unique session ID. In ringing flow, this is available in the `Call` object. For standalone calls, generate a random unique string.
`authToken`	The logged-in user’s auth token from `CometChat.getUserAuthToken()`.

Sample Payloads - Generate Call Token

Request
Success Response
Error Response

Method: CometChatCalls.generateToken(authToken:sessionID:onSuccess:onError:)Parameters:

Property	Type	Description
authToken	`NSString`	User’s auth token from CometChat
sessionID	`NSString`	Unique session identifier

GenerateToken Object:

Property	Type	Description
token	`String`	JWT token for call session

Object Type: CometChatException

Property	Type	Description
errorCode	`String`	`"ERR_TOKEN_GENERATION_FAILED"`
errorDescription	`String`	Error message

Start Call Session

Use the startSession() method to join a call session. This method requires a call token (generated in the previous step) and a CallSettings object that configures the call UI and behavior. The CallSettings class configures the call UI and behavior. Use callSettingsBuilder to create a CallSettings instance with the following required parameters:

Parameter	Description
`view`	A `UIView` where the calling UI will be rendered
`callToken`	The `GenerateToken` object received from `generateToken()` onSuccess

Swift

guard let callToken = self.callToken else { return }

let callSettings = CometChatCalls.callSettingsBuilder
    .setDefaultLayout(true)
    .setIsAudioOnly(false)
    .setDelegate(self)
    .build()

CometChatCalls.startSession(callToken: callToken, callSetting: callSettings, view: callView) { success in
    print("Call session started successfully")
} onError: { error in
    print("Start session failed: \(String(describing: error?.errorDescription))")
}

Sample Payloads - Start Call Session

Request
Success Response
Error Response

Method: CometChatCalls.startSession(callToken:callSetting:view:onSuccess:onError:)Parameters:

Property	Type	Description
callToken	`GenerateToken`	Token from generateToken
callSetting	`CallSettings`	Settings from callSettingsBuilder
view	`UIView`	View to render call UI

Response:

Property	Type	Value
success	`String`	Success message

Object Type: CometChatException

Property	Type	Description
errorCode	`String`	Error identifier
errorDescription	`String`	Error message

Call Settings Options

callSettingsBuilder Methods:

Method	Type	Description
setDefaultLayout(_:)	`Bool`	Use default UI layout
setIsAudioOnly(_:)	`Bool`	Audio-only mode (no video)
setDelegate(_:)	`Any`	Delegate for call events
setMode(_:)	`Mode`	Call mode (.default, .single, .spotlight)
setStartAudioMuted(_:)	`Bool`	Start with mic muted
setStartVideoMuted(_:)	`Bool`	Start with camera off

Call Settings

Configure the call experience using the following callSettingsBuilder methods:

Sample Payloads - Call Settings

Layout & Mode Settings:

Method	Type	Default	Description
`setDefaultLayout(_:)`	`Bool`	`true`	Enable default call UI
`setIsAudioOnly(_:)`	`Bool`	`false`	Audio-only or audio-video
`setIsSingleMode(_:)`	`Bool`	`false`	Single participant mode
`setMode(_:)`	`Mode`	`.default`	`.default`, `.single`, `.spotlight`
`setAvatarMode(_:)`	`AvatarMode`	`.circle`	`.circle`, `.square`, `.fullscreen`

Button Visibility Settings:

Method	Type	Default	Description
`setEndCallButtonDisable(_:)`	`Bool`	`false`	Hide end call button
`setShowRecordingButton(_:)`	`Bool`	`false`	Show recording button
`setSwitchCameraButtonDisable(_:)`	`Bool`	`false`	Hide switch camera button
`setMuteAudioButtonDisable(_:)`	`Bool`	`false`	Hide mute audio button
`setPauseVideoButtonDisable(_:)`	`Bool`	`false`	Hide pause video button
`setAudioModeButtonDisable(_:)`	`Bool`	`false`	Hide audio mode button
`setShowSwitchToVideoCall(_:)`	`Bool`	`false`	Show switch to video button

Initial State Settings:

Method	Type	Default	Description
`setStartAudioMuted(_:)`	`Bool`	`false`	Start with mic muted
`setStartVideoMuted(_:)`	`Bool`	`false`	Start with camera off
`setDefaultAudioMode(_:)`	`AudioMode`	`SPEAKER`	`SPEAKER`, `EARPIECE`, `BLUETOOTH`

Video Tile Settings:

Method	Type	Default	Description
`setEnableVideoTileClick(_:)`	`Bool`	`true`	Enable click on video tiles
`setEnableDraggableVideoTile(_:)`	`Bool`	`true`	Enable drag in Spotlight mode

Other Settings:

Method	Type	Default	Description
`setIdleTimeoutPeriod(_:)`	`Int`	`180`	Idle timeout in seconds
`setDelegate(_:)`	`Any`	`nil`	CallsEventsDelegate

Method	Description
`setDefaultLayout(Bool)`	Enables or disables the default call UI layout with built-in controls. `true` shows the default layout. Default: `true`
`setIsAudioOnly(Bool)`	Sets whether the call is audio-only or audio-video. `true` for audio-only. Default: `false`
`setIsSingleMode(Bool)`	Enables single participant mode.
`setShowSwitchToVideoCall(Bool)`	Shows or hides the switch to video call button.
`setEnableVideoTileClick(Bool)`	Enables or disables click interactions on video tiles. Default: `true`
`setEnableDraggableVideoTile(Bool)`	Enables or disables drag functionality for video tiles in Spotlight mode. Default: `true`
`setEndCallButtonDisable(Bool)`	Shows or hides the end call button. Default: `false` (shown)
`setShowRecordingButton(Bool)`	Shows or hides the recording button. Default: `false`
`setSwitchCameraButtonDisable(Bool)`	Shows or hides the switch camera button. Default: `false` (shown)
`setMuteAudioButtonDisable(Bool)`	Shows or hides the mute audio button. Default: `false` (shown)
`setPauseVideoButtonDisable(Bool)`	Shows or hides the pause video button. Default: `false` (shown)
`setAudioModeButtonDisable(Bool)`	Shows or hides the audio mode selection button. Default: `false` (shown)
`setStartAudioMuted(Bool)`	Starts the call with the microphone muted. Default: `false`
`setStartVideoMuted(Bool)`	Starts the call with the camera turned off. Default: `false`
`setMode(DisplayModes)`	Sets the call UI layout mode. Available: `.default`, `.single`, `.spotlight`. Default: `.default`
`setAvatarMode(AvatarMode)`	Sets avatar display mode. Available: `.circle`, `.square`, `.fullscreen`. Default: `.circle`
`setDefaultAudioMode(AudioMode)`	Sets the initial audio output device. Available: `SPEAKER`, `EARPIECE`, `BLUETOOTH`, `HEADPHONES`
`setIdleTimeoutPeriod(Int)`	Sets idle timeout in seconds. Warning appears 60 seconds before auto-termination. Default: `180`. v4.1.1+
`setDelegate(self)`	Sets the delegate to receive call events.

Call Listeners

The CallsEventsDelegate protocol provides real-time callbacks for call session events, including participant changes, call state updates, and error conditions. To receive call events, conform to CallsEventsDelegate and set the delegate in callSettingsBuilder using setDelegate(self).

Swift

extension ViewController: CallsEventsDelegate {
    
    func onCallEnded() {
        // Call ended, close the calling screen
    }
    
    func onSessionTimeout() {
        // Session timed out due to inactivity
    }
    
    func onCallEndButtonPressed() {
        // User pressed end call button
    }
    
    func onUserJoined(rtcUser: RTCUser) {
        // A participant joined the call
    }
    
    func onUserLeft(rtcUser: RTCUser) {
        // A participant left the call
    }
    
    func onUserListChanged(rtcUsers: [RTCUser]) {
        // Participant list updated
    }
    
    func onAudioModeChanged(mode: [AudioMode]) {
        // Available audio devices changed
    }
    
    func onCallSwitchedToVideo(callSwitchedInfo: CallSwitchRequestInfo) {
        // Call upgraded from audio to video
    }
    
    func onUserMuted(rtcMutedUser: RTCMutedUser) {
        // A participant's mute state changed
    }
    
    func onRecordingToggled(recordingInfo: RTCRecordingInfo) {
        // Recording started or stopped
    }
}

Events

Event	Description
`onCallEnded()`	Invoked when the call session terminates for a 1:1 call. Both participants receive this callback.
`onSessionTimeout()`	Invoked when the call is auto-terminated due to inactivity (default: 180 seconds). v4.1.1+
`onCallEndButtonPressed()`	Invoked when the local user taps the end call button. For ringing flow, call `CometChat.endCall()`. For standalone, call `CometChatCalls.endSession()`.
`onUserJoined(rtcUser: RTCUser)`	Invoked when a remote participant joins.
`onUserLeft(rtcUser: RTCUser)`	Invoked when a remote participant leaves.
`onUserListChanged(rtcUsers: [RTCUser])`	Invoked whenever the participant list changes.
`onAudioModeChanged(mode: [AudioMode])`	Invoked when available audio devices change.
`onCallSwitchedToVideo(callSwitchedInfo: CallSwitchRequestInfo)`	Invoked when an audio call is upgraded to video.
`onUserMuted(rtcMutedUser: RTCMutedUser)`	Invoked when a participant’s mute state changes.
`onRecordingToggled(recordingInfo: RTCRecordingInfo)`	Invoked when call recording starts or stops.

Sample Payloads - CallsEventsDelegate

Method: onCallEnded()Triggered: When call session terminates (1:1 call)Payload: NoneAction: Clean up and close calling screen

Method: onSessionTimeout()Triggered: When call auto-terminates due to inactivityPayload: NoneDefault timeout: 180 seconds (configurable via setIdleTimeoutPeriod)

Method: onCallEndButtonPressed()Triggered: When local user taps end call buttonPayload: NoneAction: End call (different for Ringing vs Session Only flow)

Method: onUserJoined(rtcUser: RTCUser)Triggered: When a remote participant joins the callRTCUser Object:

Property	Type	Description
uid	`String?`	User’s unique identifier
name	`String?`	User’s display name
avatar	`String?`	User’s avatar URL

Method: onUserLeft(rtcUser: RTCUser)Triggered: When a remote participant leaves the callRTCUser Object:

Property	Type	Description
uid	`String?`	User’s unique identifier
name	`String?`	User’s display name
avatar	`String?`	User’s avatar URL

Method: onUserListChanged(rtcUsers: [RTCUser])Triggered: Whenever the participant list changesPayload: Array of all current participantsRTCUser Object:

Property	Type	Description
uid	`String?`	User’s unique identifier
name	`String?`	User’s display name
avatar	`String?`	User’s avatar URL

Method: onAudioModeChanged(mode: [AudioMode])Triggered: When available audio devices changePayload: Array of available AudioMode optionsAudioMode Values:

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

Method: onCallSwitchedToVideo(callSwitchedInfo: CallSwitchRequestInfo)Triggered: When an audio call is upgraded to videoCallSwitchRequestInfo Object:

Property	Type	Description
requestedBy	`RTCUser?`	User who requested the switch

Method: onUserMuted(rtcMutedUser: RTCMutedUser)Triggered: When a participant’s mute state changesRTCMutedUser Object:

Property	Type	Description
uid	`String?`	User’s unique identifier
name	`String?`	User’s display name
audioMuted	`Bool?`	Is audio muted
videoMuted	`Bool?`	Is video muted

Method: onRecordingToggled(recordingInfo: RTCRecordingInfo)Triggered: When call recording starts or stopsRTCRecordingInfo Object:

Property	Type	Description
isRecording	`Bool?`	Is recording active
startedBy	`RTCUser?`	User who started recording

End Call Session

Ending a call session properly is essential to release media resources (camera, microphone, network connections) and update call state across all participants.

Sample Payloads - End Call

Ringing Flow
Session Only Flow
endCall Response

When using the Ringing flow, coordinate between Chat SDK and Calls SDK.User who initiates end call (presses end button):

Step	Method	SDK	Purpose
1	`CometChat.endCall(sessionID:)`	Chat SDK	Notify server call ended
2	`CometChat.clearActiveCall()`	Chat SDK	Clear active call state
3	`CometChatCalls.endSession()`	Calls SDK	Release media resources

Remote participant (receives onCallEnded callback):

Step	Method	SDK	Purpose
1	`CometChat.clearActiveCall()`	Chat SDK	Clear active call state
2	`CometChatCalls.endSession()`	Calls SDK	Release media resources

When using Session Only flow (without ringing), only call the Calls SDK method.

Step	Method	SDK	Purpose
1	`CometChatCalls.endSession()`	Calls SDK	Release media resources

Method: CometChat.endCall(sessionID:onSuccess:onError:)Request Parameters:

Property	Type	Description
sessionID	`String`	Session ID of active call

Success Response - Call Object:

Property	Type	Description
sessionID	`String?`	Session ID of ended call
callStatus	`CallStatus`	`.ended`
endedAt	`Double?`	Timestamp when call ended
totalDurationInMinutes	`Double`	Total call duration

Cleanup Methods

Method	Description
`CometChat.clearActiveCall()`	Clears the active call from CometChat
`CometChatCalls.endSession()`	Ends the call session in CallsSDK

Ringing Flow

When using the Ringing flow, you must coordinate between the CometChat Chat SDK and the Calls SDK to properly terminate the call.

The Ringing flow requires calling methods from both the Chat SDK (CometChat.endCall()) and the Calls SDK (CometChatCalls.endSession()) to ensure proper call termination.

User who initiates the end call: When the user presses the end call button, the onCallEndButtonPressed() callback is triggered. Inside this callback, call CometChat.endCall(). On success, call CometChat.clearActiveCall() and CometChatCalls.endSession().

Swift

func onCallEndButtonPressed() {
    CometChat.endCall(sessionID: sessionId) { call in
        CometChat.clearActiveCall()
        CometChatCalls.endSession()
        // Close the calling screen
    } onError: { error in
        print("End call failed: \(String(describing: error?.errorDescription))")
    }
}

Remote participant (receives onCallEnded() callback):

Swift

func onCallEnded() {
    CometChat.clearActiveCall()
    CometChatCalls.endSession()
    // Close the calling screen
}

Session Only Flow

When using the Session Only flow (without ringing), you only need to call the Calls SDK method to end the session.

Swift

func onCallEndButtonPressed() {
    CometChatCalls.endSession()
    // Close the calling screen
}

Methods

These methods are available for performing custom actions during an active call session. Use them to build custom UI controls or implement specific behaviors based on your use case.

These methods can only be called when a call session is active.

Switch Camera

Toggles between the front and rear camera during a video call.

Swift
Objective-C

CometChatCalls.switchCamera()

[CometChatCalls switchCamera];

Mute Audio

Controls the local audio stream transmission.

Swift
Objective-C

// Mute audio
CometChatCalls.audioMuted(true)

// Unmute audio
CometChatCalls.audioMuted(false)

// Mute audio
[CometChatCalls audioMuted:YES];

// Unmute audio
[CometChatCalls audioMuted:NO];

Pause Video

Controls the local video stream transmission.

Swift
Objective-C

// Pause video
CometChatCalls.videoPaused(true)

// Resume video
CometChatCalls.videoPaused(false)

// Pause video
[CometChatCalls videoPaused:YES];

// Resume video
[CometChatCalls videoPaused:NO];

Set Audio Mode

Routes the audio output to a specific device.

Swift
Objective-C

CometChatCalls.setAudioMode(mode: "SPEAKER")

[CometChatCalls setAudioModeWithMode:@"SPEAKER"];

Enter PIP Mode

Enters Picture-in-Picture mode.

Swift
Objective-C

CometChatCalls.enterPIPMode()

[CometChatCalls enterPIPMode];

Exit PIP Mode

Exits Picture-in-Picture mode.

Swift
Objective-C

CometChatCalls.exitPIPMode()

[CometChatCalls exitPIPMode];

Switch To Video Call

Upgrades an ongoing audio call to a video call.

Swift
Objective-C

CometChatCalls.switchToVideoCall()

[CometChatCalls switchToVideoCall];

Start Recording

Starts recording the call session.

Swift
Objective-C

CometChatCalls.startRecording()

[CometChatCalls startRecording];

Stop Recording

Stops an ongoing call recording.

Swift
Objective-C

CometChatCalls.stopRecording()

[CometChatCalls stopRecording];

End Call

Terminates the current call session and releases all media resources.

Swift
Objective-C

CometChatCalls.endSession()

[CometChatCalls endSession];

In-Call Methods Reference

Method	Parameters	Description
`switchCamera()`	None	Toggle front/rear camera
`audioMuted(_:)`	`Bool`	Mute/unmute microphone
`videoPaused(_:)`	`Bool`	Pause/resume camera
`setAudioMode(mode:)`	`String`	Set audio output device
`enterPIPMode()`	None	Enter Picture-in-Picture
`exitPIPMode()`	None	Exit Picture-in-Picture
`switchToVideoCall()`	None	Upgrade audio to video
`startRecording()`	None	Start call recording
`stopRecording()`	None	Stop call recording
`endSession()`	None	End call session

CallsEventsDelegate Callbacks

Callback	Payload	Description
`onCallEnded()`	None	Call session terminated
`onSessionTimeout()`	None	Call auto-terminated due to inactivity
`onCallEndButtonPressed()`	None	User tapped end call button
`onUserJoined(rtcUser:)`	`RTCUser`	Remote participant joined
`onUserLeft(rtcUser:)`	`RTCUser`	Remote participant left
`onUserListChanged(rtcUsers:)`	`[RTCUser]`	Participant list changed
`onAudioModeChanged(mode:)`	`[AudioMode]`	Available audio devices changed
`onCallSwitchedToVideo(callSwitchedInfo:)`	`CallSwitchRequestInfo`	Audio call upgraded to video
`onUserMuted(rtcMutedUser:)`	`RTCMutedUser`	Participant mute state changed
`onRecordingToggled(recordingInfo:)`	`RTCRecordingInfo`	Recording started/stopped

Callback Object Properties

RTCUser
RTCMutedUser
RTCRecordingInfo
AudioMode

Property	Type	Description
uid	`String?`	User’s unique identifier
name	`String?`	User’s display name
avatar	`String?`	User’s avatar URL

Property	Type	Description
uid	`String?`	User’s unique identifier
name	`String?`	User’s display name
audioMuted	`Bool?`	Is audio muted
videoMuted	`Bool?`	Is video muted

Property	Type	Description
isRecording	`Bool?`	Is recording active
startedBy	`RTCUser?`	User who started recording

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

​Overview

​Generate Call Token

​Start Call Session

​Call Settings

​Call Listeners

​Events

​End Call Session

​Ringing Flow

​Session Only Flow

​Methods

​Switch Camera

​Mute Audio

​Pause Video

​Set Audio Mode

​Enter PIP Mode

​Exit PIP Mode

​Switch To Video Call

​Start Recording

​Stop Recording

​End Call

​In-Call Methods Reference

​CallsEventsDelegate Callbacks

Overview

Generate Call Token

Start Call Session

Call Settings

Call Listeners

Events

End Call Session

Ringing Flow

Session Only Flow

Methods

Switch Camera

Mute Audio

Pause Video

Set Audio Mode

Enter PIP Mode

Exit PIP Mode

Switch To Video Call

Start Recording

Stop Recording

End Call

In-Call Methods Reference

CallsEventsDelegate Callbacks