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 monolithicCometChatCallsEventsListener CallSessionsingleton 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,CameraFacinginstead of raw strings
Initialization
No changes required. Theinit() 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.
- v4
- v5
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.
- v4
- v5
Builder Method Mapping
Joining a Session
startSession() is replaced by joinSession(), which returns a Widget? that you place in your Flutter widget tree.
- v4
- v5
- v5
generateToken()no longer requires theauthTokenparameter (uses cached token fromlogin()) - v5
joinSession()accepts aCallTokenobject or asessionIdstring directly - v5 offers a convenience overload that takes
sessionIddirectly and handles token generation internally
Session Control (Actions)
In v4, session actions were static methods onCometChatCalls. In v5, they’re instance methods on CallSession.
- v4
- v5
Action Method Mapping
Event Listeners
This is the biggest improvement in v5. The singleCometChatCallsEventsListener mixin is replaced by 5 focused listener classes.
v4: Single Monolithic Listener
v5: Focused Listener Classes
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.