docs(react-native): ringing through the Calls SDK and Push Notifications SDK

[suraj-chauhan-cometchat]

Summary

The React Native counterpart to #561. React Native calling no longer signals through the Chat SDK. The Calls SDK 5.1 creates, joins and ends calls; the Push Notifications SDK 2.0 rings the device in every app state (foreground, background, killed); the UI Kit hosts the screens.

Consumer-facing wording is "ringing" and "legacy ringing"; the pages never say v1 or v2. Page for page this mirrors #561 — same structure, same headings, same tables — with React Native's own APIs rather than translated Kotlin.

Where React Native genuinely differs from Android

These are deliberate, not drift. Behaviour is the same; the methods are not.

Android	React Native
One CometChatPushNotifications.init; the calls module is installed by reflection	Two packages, and two init shapes: a calls-only app passes its config to CometChatVoipNotifications.init(config); a chat app inits the core first and calls CometChatVoipNotifications.init() with no config. Passing a config in a chat app re-runs the core init and drops every chat option — documented as a warning on every page that shows it
setAnswerActivity(...), call in the intent	No answer activity. The answered call arrives as onCallAccepted, buffered natively and replayed to the first subscriber
CometChatCalls.addIncomingCallListener	The Calls SDK has no such listener on RN. Incoming-call events come from the Push SDK: onCallRinging / onCallAccepted / onCallEnded / onRingEnded
joinSession(sessionId, settings, container, listener)	connect(sessionId) then mount <CometChatCalls.Component callToken={…} />
Callback listeners	Result<T, E> from initiateCall / endCall, and session.addEventListener(event, fn) returning an unsubscribe
setEnableCalling(true) in UIKitSettings	Installing the Calls SDK package is the switch; there is no setEnableCalling on RN
App must delegate from its own FirebaseMessagingService	The package ships its own service, so delegation is optional — documented as "you normally skip this step"
—	registerBackgroundCallTask() at module scope in index.js, or a decline on a killed app is never delivered
—	iOS half: CallKit and PushKit, the voip background mode, and the NSMicrophoneUsageDescription crash that looks exactly like a ring timeout

Calls SDK (calls/react-native/)

• ringing.mdx rewritten: Calls SDK-only flow with a sequence diagram, initiateCall, prepared-session events ("Ringing…" / answered), the Push SDK's incoming-call events with the reason table, answering, declining, cancelling, ring timeout, ending with session.leave(), call waiting, group calls, logout, status values.
• voip-calling.mdx rewritten as Push Ringing (slug kept, no redirect): dependencies, the two init shapes, the background task, optional FCM delegation, permissions and ensureRingReady / getDiagnostics / verifyPushSetup, how a ring ends, call during a call, missed calls, killed-app behaviour, staging hosts, tokens, own incoming-call screen, theming, MANUAL mode, reporting your own outgoing call, troubleshooting.
• migrating-from-legacy-ringing.mdx (new, in the Migration Guide nav group): before/after diagrams, seven migration steps, a method mapping table, caller and callee screens before/after, checklist. Covers removing react-native-callkeep and react-native-voip-push-notification.
• events: prepared-session semantics, onParticipantConnected, the Push SDK's incoming-call events, the Calls SDK login listener. setup: 5.1 floor, push packages, initialise-once warning. migration-guide-v5: a 5.0 → 5.1 section. troubleshooting: a Ringing section.

UI Kit (ui-kit/react-native/)

• calling-integration.mdx rewritten: five steps (dependencies, init in order, the one event subscription, permissions, logout), what the kit does from there, the "Ringing… only on the push path" note, ring theming, upgrade pointer.
• incoming-call.mdx deprecated, kept for apps that draw the in-app ring screen themselves, with a table of what to use instead.

Notifications

• notifications/react-native-push-notifications-android.mdx and -ios.mdx: both taught ringing with CometChat.addCallListener + CometChatIncomingCall. That section is replaced with the VoIP package wiring and a pointer to the calling pages; ringInForeground, the background-task import and the troubleshooting rows that referenced the removed component are corrected.

Before merging

• Versions are placeholders for the public releases: @cometchat/calls-sdk-react-native 5.1.0, @cometchat/push-notifications-react-native / -voip-react-native 2.0.0. Do not merge before they are published — both push packages are currently 2.0.0-alpha.1.
• Confirm the UI Kit version that first requires Calls SDK 5.1, for the Quick Reference floors.
• Group ringing on React Native is not settled. The pages describe the Android behaviour (ring, decline is local, nothing sent, the call carries on). Confirm with the calls team before publishing.
• calls/react-native/setup.mdx pinned 5.0.5 and now pins 5.1.0; check that the six peer dependency versions it pins are still right for 5.1.
• Rendered pass with mint dev (links verified by file existence only).

Related: #561 (Android).

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cometchat	🟢 Ready	View Preview	Oct 16, 2026, 12:42 PM

💡 Tip: Enable Automations to automatically generate PRs for you.