Migration Guide

CometChat Calling SDK v5 - Beta Release - Migration Guide for iOS

This guide covers migrating from Calls SDK v4 to v5 for iOS.

Drop-in Compatibility

Calls SDK v5 is a drop-in replacement for v4. All v4 APIs are preserved as deprecated methods that internally delegate to the new v5 implementations. You can update the dependency version and your existing code will compile and run without changes.

# CocoaPods — update your Podfile
-pod 'CometChatCallsSDK', '~> 4.0'
+pod 'CometChatCallsSDK', '~> 5.0'

// Swift Package Manager — update your package dependency version to 5.x

If you’re using CometChat UI Kits, simply updating the Calls SDK version is sufficient. The UI Kit will continue to work with v5 through the deprecated compatibility layer.

Why Migrate to v5 APIs?

While v4 APIs will continue to work, migrating to v5 APIs gives you:

• Granular event listeners — 5 focused listener protocols instead of one monolithic CallsEventsDelegate
• CallSession singleton for cleaner session control — all actions on a single object instead of scattered static methods
• Dedicated login() method — the Calls SDK now handles its own authentication instead of depending on the Chat SDK’s auth token or REST APIs
• Strongly-typed enums — AudioModeType, CallType, LayoutType, CameraFacing instead of raw strings

---

Initialization

No changes required. The init API is the same in v5.

let callAppSettings = CallAppSettings()
callAppSettings.set(appId: "APP_ID")
callAppSettings.set(region: "REGION")

CometChatCalls(callsAppSettings: callAppSettings, onSuccess: { success in
    // Initialized
}, onError: { error in
    // Handle error
})

---

Authentication

In v4, the Calls SDK had no dedicated authentication step. It relied on the Chat SDK’s auth token (CometChat.getUserAuthToken()) or a REST API to obtain an auth token, which you then passed manually to generateToken(authToken:sessionID:onSuccess:onError:).

v5 introduces its own login() method. After calling login(), the SDK caches the auth token internally, so you no longer need to pass it around to other API calls.

v4

// No dedicated Calls SDK login — relied on Chat SDK for auth token
let authToken = CometChat.getUserAuthToken()

// Had to pass authToken manually
CometChatCalls.generateToken(authToken: authToken as NSString?,
                             sessionID: sessionID as NSString?,
                             onSuccess: { token in
    // Use token to start session
}, onError: { error in })

v5

// Login to the Calls SDK once (after your Chat SDK login)
CometChatCalls.login(authToken: authToken, onSuccess: { callsUser in
    // Calls SDK is now authenticated — auth token is cached internally
}, onError: { error in })

Call CometChatCalls.login() once after your user authenticates (e.g., right after CometChat.login() succeeds). The SDK stores the auth token internally, so subsequent calls like generateToken() and joinSession() use it automatically without you having to pass it.

---

Session Settings

CallSettingsBuilder and PresentationSettingsBuilder are replaced by SessionSettingsBuilder. The builder methods have been renamed for clarity.

v4

let callSettings = CometChatCalls.callSettingsBuilder
    .setIsAudioOnly(true)
    .setDefaultLayout(true)
    .setEndCallButtonDisable(false)
    .setMuteAudioButtonDisable(false)
    .setPauseVideoButtonDisable(false)
    .setSwitchCameraButtonDisable(false)
    .setAudioModeButtonDisable(false)
    .setShowRecordingButton(true)
    .setStartAudioMuted(false)
    .setStartVideoMuted(false)
    .setDefaultAudioMode("SPEAKER")
    .setMode("DEFAULT")
    .setStartRecordingOnCallStart(false)
    .setDelegate(self)
    .build()

v5

let sessionSettings = CometChatCalls.sessionSettingsBuilder
    .setType(.audio)
    .startAudioMuted(false)
    .startVideoPaused(false)
    .setLayout(.tile)
    .setAudioMode(.speaker)
    .hideLeaveSessionButton(false)
    .hideToggleAudioButton(false)
    .hideToggleVideoButton(false)
    .hideSwitchCameraButton(false)
    .hideAudioModeButton(false)
    .hideRecordingButton(false)
    .hideControlPanel(false)
    .hideHeaderPanel(false)
    .enableAutoStartRecording(false)
    .build()

Builder Method Mapping

v4 Method	v5 Method	Notes
setIsAudioOnly(true)	setType(.audio)	Use .video for video calls
setDefaultLayout(bool)	hideControlPanel(!bool) + hideHeaderPanel(!bool)	Inverted logic
setEndCallButtonDisable(bool)	hideLeaveSessionButton(bool)	Same logic
setMuteAudioButtonDisable(bool)	hideToggleAudioButton(bool)	Same logic
setPauseVideoButtonDisable(bool)	hideToggleVideoButton(bool)	Same logic
setSwitchCameraButtonDisable(bool)	hideSwitchCameraButton(bool)	Same logic
setAudioModeButtonDisable(bool)	hideAudioModeButton(bool)	Same logic
setShowRecordingButton(bool)	hideRecordingButton(!bool)	Inverted logic
setStartAudioMuted(bool)	startAudioMuted(bool)	Same logic
setStartVideoMuted(bool)	startVideoPaused(bool)	Same logic
setDefaultAudioMode("SPEAKER")	setAudioMode(.speaker)	Enum instead of string
setMode("DEFAULT")	setLayout(.tile)	Enum instead of string
setStartRecordingOnCallStart(bool)	enableAutoStartRecording(bool)	Same logic
setAvatarMode(string)	Removed	No longer applicable
setEnableVideoTileClick(bool)	Removed	No longer applicable
setEnableDraggableVideoTile(bool)	Removed	No longer applicable
setDelegate(delegate)	Use CallSession listeners	See Events section

---

Joining a Session

startSession() is replaced by joinSession().

v4

// Step 1: Generate token with auth token
CometChatCalls.generateToken(authToken: authToken as NSString?,
                             sessionID: sessionID as NSString?,
                             onSuccess: { token in
    // Step 2: Start session with token string
    CometChatCalls.startSession(callToken: token ?? "",
                                callSetting: callSettings,
                                view: callView,
                                onSuccess: { message in
        // Session started
    }, onError: { error in })
}, onError: { error in })

v5

// Option A: Two-step with token
CometChatCalls.generateToken(sessionID: sessionID, onSuccess: { token in
    CometChatCalls.joinSession(callToken: token ?? "",
                               callSetting: sessionSettings,
                               container: callView,
                               onSuccess: { message in
        // Session joined
    }, onError: { error in })
}, onError: { error in })

// Option B: One-step with session ID (recommended)
CometChatCalls.joinSession(sessionID: sessionID,
                           callSetting: sessionSettings,
                           container: callView,
                           onSuccess: { message in
    // Token generation + join handled internally
}, onError: { error in })

Key differences:

• v5 generateToken() no longer requires the authToken parameter (uses cached token from login())
• v5 offers a convenience overload that takes sessionID directly and handles token generation internally
• Parameter name changed from view to container

---

Session Control (Actions)

In v4, session actions were static methods on CometChatCalls. In v5, they’re instance methods on CallSession.shared.

v4

CometChatCalls.endSession()
CometChatCalls.switchCamera()
CometChatCalls.audioMuted(true)
CometChatCalls.videoPaused(true)
CometChatCalls.setAudioMode(mode: "SPEAKER")
CometChatCalls.enterPIPMode()
CometChatCalls.exitPIPMode()
CometChatCalls.startRecording()
CometChatCalls.stopRecording()

v5

let callSession = CallSession.shared

callSession.leaveSession()
callSession.switchCamera()
callSession.muteAudio()       // or callSession.unmuteAudio()
callSession.pauseVideo()      // or callSession.resumeVideo()
callSession.setAudioMode("SPEAKER")
callSession.enablePictureInPictureLayout()
callSession.disablePictureInPictureLayout()
callSession.startRecording()
callSession.stopRecording()

Action Method Mapping

v4 Static Method	v5 CallSession Method
CometChatCalls.endSession()	callSession.leaveSession()
CometChatCalls.switchCamera()	callSession.switchCamera()
CometChatCalls.audioMuted(true)	callSession.muteAudio()
CometChatCalls.audioMuted(false)	callSession.unmuteAudio()
CometChatCalls.videoPaused(true)	callSession.pauseVideo()
CometChatCalls.videoPaused(false)	callSession.resumeVideo()
CometChatCalls.setAudioMode(mode:)	callSession.setAudioMode(_:)
CometChatCalls.enterPIPMode()	callSession.enablePictureInPictureLayout()
CometChatCalls.exitPIPMode()	callSession.disablePictureInPictureLayout()
CometChatCalls.startRecording()	callSession.startRecording()
CometChatCalls.stopRecording()	callSession.stopRecording()
CometChatCalls.switchToVideoCall()	Removed

---

Event Listeners

This is the biggest improvement in v5. The single CallsEventsDelegate protocol is replaced by 5 focused listener protocols.

v4: Single Monolithic Delegate

class MyViewController: UIViewController, CallsEventsDelegate {

    func setupCallEvents() {
        // Set via builder
        CometChatCalls.callSettingsBuilder.setDelegate(self).build()
    }

    func onCallEnded() { }
    func onCallEndButtonPressed() { }
    func onSessionTimeout() { }
    func onUserJoined(rtcUser: RTCUser) { }
    func onUserLeft(rtcUser: RTCUser) { }
    func onUserListChanged(rtcUsers: [RTCUser]) { }
    func onAudioModeChanged(mode: [CallAudioMode]) { }
    func onCallSwitchedToVideo(callSwitchedInfo: CallSwitchRequestInfo) { }
    func onUserMuted(rtcMutedUser: RTCMutedUser) { }
    func onRecordingToggled(recordingInfo: RTCRecordingInfo) { }
}

v5: Focused Listener Protocols

let callSession = CallSession.shared

// Session lifecycle events
class MySessionListener: SessionStatusListener {
    func onSessionJoined() { }
    func onSessionLeft() { }
    func onSessionTimedOut() { }
    func onConnectionLost() { }
    func onConnectionRestored() { }
    func onConnectionClosed() { }
}
callSession.addSessionStatusListener(mySessionListener)

// Participant events (replaces onUserJoined, onUserLeft, onUserListChanged, onUserMuted)
class MyParticipantListener: ParticipantEventListener {
    func onParticipantJoined(participant: Participant) { }
    func onParticipantLeft(participant: Participant) { }
    func onParticipantListChanged(participants: [Participant]) { }
    func onParticipantAudioMuted(participant: Participant) { }
    func onParticipantAudioUnmuted(participant: Participant) { }
    func onParticipantVideoPaused(participant: Participant) { }
    func onParticipantVideoResumed(participant: Participant) { }
    func onParticipantHandRaised(participant: Participant) { }
    func onParticipantHandLowered(participant: Participant) { }
    func onParticipantStartedRecording(participant: Participant) { }
    func onParticipantStoppedRecording(participant: Participant) { }
    func onDominantSpeakerChanged(participant: Participant) { }
}
callSession.addParticipantEventListener(myParticipantListener)

// Media state events (replaces onAudioModeChanged, onRecordingToggled)
class MyMediaListener: MediaEventsListener {
    func onAudioMuted() { }
    func onAudioUnMuted() { }
    func onVideoPaused() { }
    func onVideoResumed() { }
    func onRecordingStarted() { }
    func onRecordingStopped() { }
    func onAudioModeChanged(audioModeType: AudioModeType) { }
    func onCameraFacingChanged(cameraFacing: CameraFacing) { }
}
callSession.addMediaEventsListener(myMediaListener)

// Button click events (replaces onCallEndButtonPressed)
class MyButtonListener: ButtonClickListener {
    func onLeaveSessionButtonClicked() { }
    func onToggleAudioButtonClicked() { }
    func onToggleVideoButtonClicked() { }
    func onSwitchCameraButtonClicked() { }
    func onRaiseHandButtonClicked() { }
    func onRecordingToggleButtonClicked() { }
}
callSession.addButtonClickListener(myButtonListener)

// Layout events
class MyLayoutListener: LayoutListener {
    func onCallLayoutChanged(layoutType: LayoutType) { }
    func onPictureInPictureLayoutEnabled() { }
    func onPictureInPictureLayoutDisabled() { }
}
callSession.addLayoutListener(myLayoutListener)

v5 listeners use weak references internally, so they are automatically cleaned up when the listener object is deallocated. You can also explicitly remove listeners using removeSessionStatusListener(_:), removeParticipantEventListener(_:), etc.

Event Mapping

v4 Event	v5 Listener	v5 Event
onCallEnded()	SessionStatusListener	onSessionLeft()
onCallEndButtonPressed()	ButtonClickListener	onLeaveSessionButtonClicked()
onSessionTimeout()	SessionStatusListener	onSessionTimedOut()
onUserJoined(rtcUser:)	ParticipantEventListener	onParticipantJoined(participant:)
onUserLeft(rtcUser:)	ParticipantEventListener	onParticipantLeft(participant:)
onUserListChanged(rtcUsers:)	ParticipantEventListener	onParticipantListChanged(participants:)
onAudioModeChanged(mode:)	MediaEventsListener	onAudioModeChanged(audioModeType:)
onCallSwitchedToVideo(callSwitchedInfo:)	Removed	—
onUserMuted(rtcMutedUser:)	ParticipantEventListener	onParticipantAudioMuted(participant:)
onRecordingToggled(recordingInfo:)	MediaEventsListener	onRecordingStarted() / onRecordingStopped()

New Events in v5

These events are only available with the v5 listener APIs:

Listener	Event	Description
SessionStatusListener	onConnectionLost()	Network interrupted
SessionStatusListener	onConnectionRestored()	Network restored
SessionStatusListener	onConnectionClosed()	Connection permanently closed
ParticipantEventListener	onParticipantVideoResumed()	Participant turned camera on
ParticipantEventListener	onParticipantVideoPaused()	Participant turned camera off
ParticipantEventListener	onParticipantHandRaised()	Participant raised hand
ParticipantEventListener	onParticipantHandLowered()	Participant lowered hand
ParticipantEventListener	onParticipantStartedScreenShare()	Participant started screen share
ParticipantEventListener	onParticipantStoppedScreenShare()	Participant stopped screen share
ParticipantEventListener	onDominantSpeakerChanged()	Active speaker changed
MediaEventsListener	onCameraFacingChanged()	Camera switched front/back
ButtonClickListener	Various button events	Individual button click tracking
LayoutListener	onCallLayoutChanged()	Layout type changed
LayoutListener	onPictureInPictureLayoutEnabled/Disabled()	PiP state changed

---

Call Logs

The CallLogsRequest API is unchanged. The only difference is that auth is now handled by CometChatCalls.login() instead of passing the auth token manually.

---

Deprecated Classes Summary

These classes still exist in v5 for backward compatibility but are deprecated:

Deprecated Class	Replacement
CallSettings	SessionSettingsBuilder.SessionSettings
CallSettingsBuilder	SessionSettingsBuilder
PresentationSettings	SessionSettingsBuilder.SessionSettings
PresentationSettingsBuilder	SessionSettingsBuilder
CallsEventsDelegate	5 focused listeners on CallSession
RTCRecordingInfo	MediaEventsListener callbacks
CallSwitchRequestInfo	Removed (no replacement)