| name | migration-v4-to-v5 |
| description | Migrate a React Native project from CometChat Calls SDK v4 to v5. Use when upgrading calls SDK version, replacing deprecated v4 APIs, migrating CallSettingsBuilder to sessionSettings, replacing OngoingCallListener with addEventListener. Triggers on "migrate calls sdk", "upgrade v4 to v5", "replace deprecated calls api", "CallSettingsBuilder to sessionSettings", "migration guide". |
| inclusion | manual |
CometChat Calls SDK — Migrate v4 to v5 (React Native)
Overview
Calls SDK v5 is a drop-in replacement for v4. All v4 APIs are preserved as deprecated methods that internally delegate to v5 implementations. You can update the package version and existing code will compile and run without changes. This skill guides migration to the new v5 APIs.
Migration Strategy
- Update the package version
- Add
CometChatCalls.login() after authentication
- Replace
CallSettingsBuilder → plain sessionSettings prop
- Replace
callSettings prop → sessionSettings prop on Component
- Replace
OngoingCallListener → addEventListener()
- Replace static action methods (same names, just verify)
- Clean up removed APIs
Step 1 — Update Package
npm install @cometchat/calls-sdk-react-native@latest
Step 2 — Add Authentication
v4 required passing authToken to generateToken(). v5 introduces CometChatCalls.login() which caches the token.
v4 (remove this pattern)
const { token } = await CometChatCalls.generateToken(sessionId, authToken);
v5 (replace with)
await CometChatCalls.login(uid, authKey);
await CometChatCalls.loginWithAuthToken(authToken);
const { token } = await CometChatCalls.generateToken(sessionId);
Step 3 — Replace Session Settings
CallSettingsBuilder → plain sessionSettings object. Note the inverted boolean logic on visibility methods.
v4 (remove this pattern)
const callSettings = new CometChatCalls.CallSettingsBuilder()
.enableDefaultLayout(true)
.setIsAudioOnlyCall(true)
.showEndCallButton(true)
.showSwitchCameraButton(true)
.showMuteAudioButton(true)
.showPauseVideoButton(true)
.showAudioModeButton(true)
.showRecordingButton(true)
.startWithAudioMuted(false)
.startWithVideoMuted(false)
.setMode('DEFAULT')
.setDefaultAudioMode('SPEAKER')
.startRecordingOnCallStart(false)
.setCallListener(new CometChatCalls.OngoingCallListener({ ... }))
.build();
v5 (replace with)
const sessionSettings = {
sessionType: 'VOICE',
layout: 'SIDEBAR',
hideControlPanel: false,
hideLeaveSessionButton: false,
hideSwitchCameraButton: false,
hideToggleAudioButton: false,
hideToggleVideoButton: false,
hideAudioModeButton: false,
hideRecordingButton: false,
startAudioMuted: false,
startVideoPaused: false,
audioMode: 'SPEAKER',
autoStartRecording: false,
};
Builder Method Mapping
| v4 Method | v5 SessionSettings Property | Notes |
|---|
setIsAudioOnlyCall(true) | sessionType: 'VOICE' | Use 'VIDEO' for video |
enableDefaultLayout(bool) | hideControlPanel: !bool | Inverted logic |
showEndCallButton(bool) | hideLeaveSessionButton: !bool | Inverted logic |
showSwitchCameraButton(bool) | hideSwitchCameraButton: !bool | Inverted logic |
showMuteAudioButton(bool) | hideToggleAudioButton: !bool | Inverted logic |
showPauseVideoButton(bool) | hideToggleVideoButton: !bool | Inverted logic |
showAudioModeButton(bool) | hideAudioModeButton: !bool | Inverted logic |
showRecordingButton(bool) | hideRecordingButton: !bool | Inverted logic |
startWithAudioMuted(bool) | startAudioMuted: bool | Same logic |
startWithVideoMuted(bool) | startVideoPaused: bool | Same logic |
setMode('DEFAULT') | layout: 'SIDEBAR' | 'DEFAULT' maps to 'SIDEBAR' |
setMode('SPOTLIGHT') | layout: 'SPOTLIGHT' | Same |
setDefaultAudioMode(mode) | audioMode: mode | Same values |
startRecordingOnCallStart(bool) | autoStartRecording: bool | Same logic |
enableDraggableVideoTile(bool) | enableSpotlightDrag: bool | Same logic |
enableVideoTileClick(bool) | enableSpotlightSwap: bool | Same logic |
setCallListener(listener) | Use addEventListener() | See Step 5 |
Step 4 — Replace Component Prop
v4 (remove this pattern)
<CometChatCalls.Component callToken={token} callSettings={callSettings} />
v5 (replace with)
<CometChatCalls.Component callToken={token} sessionSettings={sessionSettings} />
Note: callSettings prop still works (deprecated) — it internally converts to v5 format.
Step 5 — Replace Event Listeners
Replace OngoingCallListener with individual addEventListener() calls.
v4 (remove this pattern)
const callSettings = new CometChatCalls.CallSettingsBuilder()
.setCallListener(new CometChatCalls.OngoingCallListener({
onCallEnded: () => { },
onCallEndButtonPressed: () => { },
onUserJoined: (user) => { },
onUserLeft: (user) => { },
onUserListUpdated: (userList) => { },
onRecordingStarted: (event) => { },
onRecordingStopped: () => { },
onUserMuted: (event) => { },
onSessionTimeout: () => { },
}))
.build();
v5 (replace with)
const controller = new AbortController();
const opts = { signal: controller.signal };
CometChatCalls.addEventListener('onSessionLeft', () => { }, opts);
CometChatCalls.addEventListener('onLeaveSessionButtonClicked', () => { }, opts);
CometChatCalls.addEventListener('onParticipantJoined', (p) => { }, opts);
CometChatCalls.addEventListener('onParticipantLeft', (p) => { }, opts);
CometChatCalls.addEventListener('onParticipantListChanged', (list) => { }, opts);
CometChatCalls.addEventListener('onRecordingStarted', () => { }, opts);
CometChatCalls.addEventListener('onRecordingStopped', () => { }, opts);
CometChatCalls.addEventListener('onParticipantAudioMuted', (p) => { }, opts);
CometChatCalls.addEventListener('onSessionTimedOut', () => { }, opts);
controller.abort();
Event Mapping
| v4 Event | v5 Event |
|---|
onCallEnded | onSessionLeft |
onCallEndButtonPressed | onLeaveSessionButtonClicked |
onSessionTimeout | onSessionTimedOut |
onUserJoined(user) | onParticipantJoined(participant) |
onUserLeft(user) | onParticipantLeft(participant) |
onUserListUpdated(list) | onParticipantListChanged(participants) |
onRecordingStarted(event) | onRecordingStarted() |
onRecordingStopped() | onRecordingStopped() |
onUserMuted(event) | onParticipantAudioMuted(participant) |
Step 6 — Update Static Methods
Most action methods keep the same names:
| v4 Method | v5 Method | Notes |
|---|
CometChatCalls.endSession() | CometChatCalls.leaveSession() | Renamed |
CometChatCalls.switchToVideoCall() | Removed — delete usage | |
Step 7 — Clean Up Removed APIs
Delete usage of these removed/deprecated features:
switchToVideoCall() — no replacement
MainVideoContainerSetting — no replacement
AvatarMode — no replacement
ShowSwitchToVideoCallButton — no replacement
Gotchas
- v5 is a drop-in replacement — you can update the package and migrate incrementally; v4 APIs still work but are deprecated
- Boolean logic is inverted for visibility:
showX(true) → hideX: false
'DEFAULT' mode maps to 'SIDEBAR' layout in v5
OngoingCallListener is replaced by individual addEventListener() calls with AbortSignal for cleanup
generateToken() no longer requires authToken parameter — it's cached from login()
- The
User object in v4 events is replaced by a simpler Participant object ({ pid, name, uid, avatar })
callSettings prop still works on the Component but is deprecated — use sessionSettings