Migration Guide

This guide covers migrating from Calls SDK v4 to v5 for JavaScript (React, Vue, Angular, etc.).

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 package version and your existing code will compile and run without changes.

npm install @cometchat/calls-sdk-javascript@5

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 — subscribe to specific events like onParticipantJoined or onSessionLeft instead of one monolithic OngoingCallListener
Dedicated login() method — the Calls SDK now handles its own authentication instead of depending on the Chat SDK’s auth token or REST APIs
Simplified initialization — pass plain objects to init() and joinSession() instead of using builder classes
Strongly-typed enums — LayoutType, SessionType instead of raw strings

Initialization

v5 accepts a plain object instead of requiring CallAppSettingsBuilder.

const callAppSettings = new CometChatCalls.CallAppSettingsBuilder()
  .setAppId("APP_ID")
  .setRegion("REGION")
  .build();

CometChatCalls.init(callAppSettings).then(
  () => { /* initialized */ },
  (error) => { /* handle error */ }
);

const callAppSettings = {
  appId: "APP_ID",
  region: "REGION",
};

CometChatCalls.init(callAppSettings).then(
  () => { /* initialized */ },
  (error) => { /* handle error */ }
);

CallAppSettingsBuilder still works in v5 — it’s deprecated but functional.

Authentication

In v4, the Calls SDK had no dedicated authentication step. It relied on the Chat SDK’s auth token (the logged-in user’s getAuthToken()) 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.

// No dedicated Calls SDK login — relied on Chat SDK for auth token
const authToken = (await CometChat.getLoggedinUser()).getAuthToken();

// Had to pass authToken manually
CometChatCalls.generateToken(sessionId, authToken).then(
  (token) => { /* use token to start session */ },
  (error) => { }
);

// Login to the Calls SDK once (after your Chat SDK login)
CometChatCalls.loginWithAuthToken(authToken).then(
  (user) => { /* Calls SDK is now authenticated */ },
  (error) => { }
);

// generateToken no longer needs the authToken parameter
CometChatCalls.generateToken(sessionId).then(
  (token) => { /* use token */ },
  (error) => { }
);

Call CometChatCalls.loginWithAuthToken() once after your user authenticates. The SDK stores the auth token internally, so subsequent calls like generateToken() and joinSession() use it automatically.

Session Settings

CallSettingsBuilder is replaced by passing a plain SessionSettings object directly to joinSession().

const callSettings = new CometChatCalls.CallSettingsBuilder()
  .enableDefaultLayout(true)
  .setIsAudioOnlyCall(true)
  .showEndCallButton(true)
  .showMuteAudioButton(true)
  .showPauseVideoButton(true)
  .showRecordingButton(true)
  .showScreenShareButton(true)
  .showModeButton(true)
  .startWithAudioMuted(false)
  .startWithVideoMuted(false)
  .setMode("DEFAULT")
  .setCallListener(new CometChatCalls.OngoingCallListener({
    onCallEnded: () => { },
    onCallEndButtonPressed: () => { },
    onUserJoined: (user) => { },
    onUserLeft: (user) => { },
    onUserListUpdated: (userList) => { },
    onError: (error) => { },
  }))
  .build();

const sessionSettings = {
  sessionType: "VIDEO",       // or "VOICE"
  layout: "TILE",             // or "SPOTLIGHT", "SIDEBAR"
  startAudioMuted: false,
  startVideoPaused: false,
  hideLeaveSessionButton: false,
  hideToggleAudioButton: false,
  hideToggleVideoButton: false,
  hideRecordingButton: false,
  hideScreenSharingButton: false,
  hideChangeLayoutButton: false,
  hideControlPanel: false,
  autoStartRecording: false,
};

Settings Property Mapping

v4 Builder Method	v5 Property	Notes
`setIsAudioOnlyCall(true)`	`sessionType: "VOICE"`	Use `"VIDEO"` for video calls
`enableDefaultLayout(bool)`	`hideControlPanel: !bool`	Inverted logic
`showEndCallButton(bool)`	`hideLeaveSessionButton: !bool`	Inverted logic
`showMuteAudioButton(bool)`	`hideToggleAudioButton: !bool`	Inverted logic
`showPauseVideoButton(bool)`	`hideToggleVideoButton: !bool`	Inverted logic
`showRecordingButton(bool)`	`hideRecordingButton: !bool`	Inverted logic
`showScreenShareButton(bool)`	`hideScreenSharingButton: !bool`	Inverted logic
`showModeButton(bool)`	`hideChangeLayoutButton: !bool`	Inverted logic
`startWithAudioMuted(bool)`	`startAudioMuted: bool`	Same logic
`startWithVideoMuted(bool)`	`startVideoPaused: bool`	Same logic
`setMode("DEFAULT")`	`layout: "SIDEBAR"`	`"DEFAULT"` maps to `"SIDEBAR"`
`startRecordingOnCallStart(bool)`	`autoStartRecording: bool`	Same logic
`setCallListener(listener)`	Use `addEventListener()`	See Events section

Joining a Session

startSession() is replaced by joinSession().

CometChatCalls.generateToken(sessionId, authToken).then((token) => {
  CometChatCalls.startSession(token, callSettings, document.getElementById("callContainer"));
});

// Generate a call token for the session, then join with it
CometChatCalls.generateToken(sessionId).then(({ token }) => {
  CometChatCalls.joinSession(token, sessionSettings, document.getElementById("callContainer"));
});

Session Control (Actions)

Static methods remain on CometChatCalls but some have been renamed.

Boolean toggles are now paired methods. In v4, muteAudio() took a boolean: muteAudio(true) muted the mic and muteAudio(false) unmuted it. In v5 these are two separate, argument-free methods — replace muteAudio(true) with muteAudio() and muteAudio(false) with unmuteAudio(). The same split applies to pauseVideo(true) / pauseVideo(false), which become pauseVideo() and resumeVideo().

// v4
CometChatCalls.muteAudio(true);   // mute
CometChatCalls.muteAudio(false);  // unmute

// v5
CometChatCalls.muteAudio();       // mute
CometChatCalls.unmuteAudio();     // unmute

v4 Method	v5 Method
`CometChatCalls.endSession()`	`CometChatCalls.leaveSession()`
`CometChatCalls.switchCamera()`	`CometChatCalls.switchCamera()`
`CometChatCalls.muteAudio(true)`	`CometChatCalls.muteAudio()`
`CometChatCalls.muteAudio(false)`	`CometChatCalls.unmuteAudio()`
`CometChatCalls.pauseVideo(true)`	`CometChatCalls.pauseVideo()`
`CometChatCalls.pauseVideo(false)`	`CometChatCalls.resumeVideo()`
`CometChatCalls.setMode(mode)`	`CometChatCalls.setLayout(layout)`
`CometChatCalls.startScreenShare()`	`CometChatCalls.startScreenSharing()`
`CometChatCalls.stopScreenShare()`	`CometChatCalls.stopScreenSharing()`
`CometChatCalls.openVirtualBackground()`	`CometChatCalls.showVirtualBackgroundDialog()`
`CometChatCalls.closeVirtualBackground()`	`CometChatCalls.hideVirtualBackgroundDialog()`
`CometChatCalls.setBackgroundBlur(level)`	`CometChatCalls.setVirtualBackgroundBlurLevel(level)`
`CometChatCalls.setBackgroundImage(url)`	`CometChatCalls.setVirtualBackgroundImage(url)`
`CometChatCalls.startRecording()`	`CometChatCalls.startRecording()`
`CometChatCalls.stopRecording()`	`CometChatCalls.stopRecording()`
`CometChatCalls.switchToVideoCall()`	Removed
`CometChatCalls.getCallDetails()`	Removed

Event Listeners

The single OngoingCallListener is replaced by addEventListener() with specific event types.

v4: Single Listener Object

const callSettings = new CometChatCalls.CallSettingsBuilder()
  .setCallListener(new CometChatCalls.OngoingCallListener({
    onCallEnded: () => { },
    onCallEndButtonPressed: () => { },
    onUserJoined: (user) => { },
    onUserLeft: (user) => { },
    onUserListUpdated: (userList) => { },
    onUserMuted: (muteInfo) => { },
    onRecordingStarted: (recordingInfo) => { },
    onRecordingStopped: () => { },
    onError: (error) => { },
  }))
  .build();

v5: Granular Event Subscriptions

// Session events
CometChatCalls.addEventListener("onSessionJoined", () => { });
CometChatCalls.addEventListener("onSessionLeft", () => { });
CometChatCalls.addEventListener("onSessionTimedOut", () => { });
CometChatCalls.addEventListener("onConnectionLost", () => { });
CometChatCalls.addEventListener("onConnectionRestored", () => { });

// Participant events
CometChatCalls.addEventListener("onParticipantJoined", (participant) => { });
CometChatCalls.addEventListener("onParticipantLeft", (participant) => { });
CometChatCalls.addEventListener("onParticipantListChanged", (participants) => { });
CometChatCalls.addEventListener("onParticipantAudioMuted", (participant) => { });
CometChatCalls.addEventListener("onParticipantAudioUnmuted", (participant) => { });

// Media events
CometChatCalls.addEventListener("onAudioMuted", () => { });
CometChatCalls.addEventListener("onAudioUnMuted", () => { });
CometChatCalls.addEventListener("onRecordingStarted", () => { });
CometChatCalls.addEventListener("onRecordingStopped", () => { });

// Button click events
CometChatCalls.addEventListener("onLeaveSessionButtonClicked", () => { });
CometChatCalls.addEventListener("onToggleAudioButtonClicked", () => { });
CometChatCalls.addEventListener("onToggleVideoButtonClicked", () => { });

// Layout events
CometChatCalls.addEventListener("onCallLayoutChanged", (layoutType) => { });

addEventListener() returns an unsubscribe function. Call it to remove the listener. You can also pass an AbortSignal for cleanup.

New Events Require `addEventListener()`

The events introduced in v5 are only delivered through addEventListener(). The v4 registration path — setCallListener() on CallSettingsBuilder — never fires them, because OngoingCallListener only carries the legacy v4 event set. (v4’s CometChatCalls.addCallEventListener() is not in v5 at all.) Events such as onSessionJoined, onConnectionLost, onLeaveSessionButtonClicked, and onCallLayoutChanged are unreachable from a v4 listener no matter how it is registered. You don’t have to migrate everything at once. addEventListener() works alongside an existing v4 listener without breaking it — keep your current OngoingCallListener for the legacy events and add addEventListener() subscriptions for the new ones.

// Existing v4 listener keeps working
const callSettings = new CometChatCalls.CallSettingsBuilder()
  .setCallListener(new CometChatCalls.OngoingCallListener({
    onCallEnded: () => { },
    onUserJoined: (user) => { },
  }))
  .build();

// Add v5-only events alongside it
CometChatCalls.addEventListener("onConnectionLost", () => { });
CometChatCalls.addEventListener("onCallLayoutChanged", (layoutType) => { });

Event Mapping

v4 Event	v5 Event
`onCallEnded`	`onSessionLeft`
`onCallEndButtonPressed`	`onLeaveSessionButtonClicked`
`onUserJoined(user)`	`onParticipantJoined(participant)`
`onUserLeft(user)`	`onParticipantLeft(participant)`
`onUserListUpdated(userList)`	`onParticipantListChanged(participants)`
`onUserMuted(info)`	`onParticipantAudioMuted(participant)`
`onRecordingStarted` / `onRecordingStopped`	`onRecordingStarted` / `onRecordingStopped`
`onError(error)`	Errors returned via Promise rejection

Deprecated Classes Summary

Deprecated	Replacement
`CometChatCalls.CallAppSettingsBuilder`	Pass plain object to `init()`
`CometChatCalls.CallSettingsBuilder`	Pass plain `SessionSettings` object to `joinSession()`
`CometChatCalls.OngoingCallListener`	`CometChatCalls.addEventListener()`
`CometChatCalls.startSession()`	`CometChatCalls.joinSession()`
`CometChatCalls.endSession()`	`CometChatCalls.leaveSession()`

5.0 to 5.1

5.1 moves ringing onto the Calls SDK. No 5.0 method is deprecated; the Chat SDK’s calling methods are superseded:

Superseded	Replacement
Chat SDK calling: `CometChat.initiateCall`, `acceptCall`, `rejectCall`, `endCall`, `startCall`, `getActiveCall`, `clearActiveCall`, Chat SDK `CallSettings`	`CometChatCalls.initiateCall`, `connect`, `session.join(container)`, `endCall(sessionId, status)`, `session.leave()`, `getActiveSession()`

CometChat.addCallListener is not superseded on the web: an incoming call still reaches an open tab through it. New in 5.1:

CometChatCalls.initiateCall(receiver, options) with InitiateCallOptions, resolving with { data, error } where data is an InitiatedCall
CometChatCalls.endCall(sessionId, status) with EndCallStatus ("rejected", "busy", "cancelled", "unanswered")
CometChatCalls.connect(sessionId, sessionSettings), which prepares a session ahead of the join, and PrepareStatus ("none", "pending", "prepared", "cancelled", "failed")
CometChatCalls.getActiveSession(), CometChatCalls.getSessionState() and CometChatCalls.getParticipants()
The CallSession session object: sessionId, callToken, settings, prepareStatus, settled, error, join(container), leave(), endSessionForAll(), isSessionActive(), isSessionJoined(), getSessionState(), getParticipants(), addEventListener() and every session action as a method
The onConnected and onParticipantConnected events
The exported CallParticipant type

Changed in 5.1:

CallSession replaces the placeholder class 5.0 exported under that name: its getInstance() is gone, and addEventListener() now returns an unsubscribe function instead of { remove }. Get the session from initiateCall, connect or getActiveSession().
joinSession() can return more errors: SESSION_SETTINGS_REQUIRED (no settings passed), SESSION_ALREADY_PREPARED and SESSION_CANCELLED (the join was cancelled by leaveSession() before it completed). A failed token verification is now returned as error too.
For TypeScript: the error type of joinSession() (and of session.join(container)) is now the exported JoinSessionException; in 5.0 it was VerifyTokenException. JoinSessionException covers the token-verification error plus the three names above, so code that narrows on error.name may need the new cases.
leaveSession() returns a Promise that resolves when the leave has been handled.

joinSession() returns SESSION_ALREADY_PREPARED while a session is prepared: join that one with session.join(container), or cancel it with session.leave() first. A prepared session keeps the settings it was prepared with. The step-by-step move from Chat SDK signalling is on Migrating from Legacy Ringing.

Overview

Integrations

Getting Started

Call Session

Features

Advanced

Resources

Migration Guide

Drop-in Compatibility

Why Migrate to v5 APIs?

Initialization

Authentication

Session Settings

Settings Property Mapping

Joining a Session

Session Control (Actions)

Event Listeners

v4: Single Listener Object

v5: Granular Event Subscriptions

New Events Require `addEventListener()`

Event Mapping

Deprecated Classes Summary

5.0 to 5.1

​Drop-in Compatibility

​Why Migrate to v5 APIs?

​Initialization

​Authentication

​Session Settings

​Settings Property Mapping

​Joining a Session

​Session Control (Actions)

​Event Listeners

​v4: Single Listener Object

​v5: Granular Event Subscriptions

​New Events Require addEventListener()

​Event Mapping

​Deprecated Classes Summary

​5.0 to 5.1

Drop-in Compatibility

Why Migrate to v5 APIs?

Initialization

Authentication

Session Settings

Settings Property Mapping

Joining a Session

Session Control (Actions)

Event Listeners

v4: Single Listener Object

v5: Granular Event Subscriptions

New Events Require `addEventListener()`

Event Mapping

Deprecated Classes Summary

5.0 to 5.1