Skip to main content
This guide covers migrating from Calls SDK v4 to v5 for Flutter.

Drop-in Compatibility

Calls SDK v5 keeps v4’s session entry points as deprecated methods that delegate to the v5 implementations: CometChatCalls.generateToken, startSession and endSession, and the single CometChatCallsEventsListener. It is not a drop-in replacement for everything: v4’s session controls on CometChatCalls (muteAudio, pauseVideo, switchCamera, setAudioMode, enterPIPMode, exitPIPMode, startRecording, stopRecording) and v4’s CallSettingsBuilder setters are gone, so code that uses them no longer compiles. Move those calls to CallSession and SessionSettingsBuilder, as shown below.
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 the deprecated v4 entry points keep working, migrating to v5 APIs gives you:
  • Granular event listeners — 5 focused listener classes (SessionStatusListeners, ParticipantEventListeners, MediaEventListeners, ButtonClickListeners, LayoutListeners) instead of one monolithic CometChatCallsEventsListener
  • CallSession singleton for cleaner session control — all actions on a single instance 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 — SessionType, LayoutType, AudioMode, CameraFacing instead of raw strings

Initialization

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

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(). 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.
Call CometChatCalls.loginWithAuthToken() 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 is replaced by SessionSettingsBuilder. The builder methods have been renamed for clarity and use strongly-typed enums.

Builder Method Mapping


Joining a Session

startSession() is replaced by joinSession(), which returns a Widget? that you place in your Flutter widget tree.
Key differences:
  • v5 generateToken() no longer requires the authToken parameter (uses cached token from login())
  • v5 joinSession() accepts a CallToken object or a sessionId string directly
  • v5 offers a convenience overload that takes sessionId directly and handles token generation internally

Session Control (Actions)

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

Action Method Mapping


Event Listeners

This is the biggest improvement in v5. The single CometChatCallsEventsListener mixin is replaced by 5 focused listener classes.

v4: Single Monolithic Listener

v5: Focused Listener Classes

Flutter listeners are not lifecycle-aware. You must manually remove all listeners in your widget’s dispose() method to prevent memory leaks.

Event Mapping

New Events in v5

These events are only available with the v5 listener APIs:

Call Logs

CallLogRequest itself is unchanged; auth is now handled by CometChatCalls.login() instead of passing the auth token manually. Note that CallLogRequestBuilder is a top-level class with public fields — it takes cascaded assignments, not setX() calls.

Deprecated Classes Summary

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

5.0 to 5.1

Build requirements

Breaking changes

Deprecated in 5.1

New in 5.1

CometChatCalls.initiateCall, endCall(sessionId:, status:), getActiveSession, getSessionState, addIncomingCallListener / IncomingCallListener, injectIncomingCall / injectIncomingCallEnded, SessionSettingsBuilder.setPeerCall, the onConnected and onParticipantConnected events, and on CallSession: leave(), isSessionJoined(), isSessionActive(), getSessionId(), getCallToken(), getPrepareStatus() and getPrepareError(). The step-by-step move from Chat SDK signalling to ringing with the Calls SDK and cometchat_voip is on Migrating from Legacy Ringing.