[jitvarpatil]

Summary

The iOS counterpart of the Android ringing docs (#561). iOS calling no longer signals through the Chat SDK. Calls SDK 5.1 creates, joins and ends calls. Push Notifications SDK 2.0 rings the device in every app state through PushKit and CallKit. On iOS every call uses CallKit, so there is no custom incoming-call screen to build.

Consumer wording is "ringing" and "legacy ringing"; the pages never say v1 or v2.

Calls SDK (calls/ios/)

• ringing.mdx (rewritten), Calls SDK only:
  • initiateCall, prepared-session events ("Ringing…" / answered) and addIncomingCallListener with its reason table.
  • Answering through the Push SDK's presentCall, decline, cancel, the ring timeout, ending with leave(), call waiting, group calls and logout.
  • The caller reads the outcome of a decline from Call Logs, because iOS doesn't push it to the caller reliably.
• migrating-from-legacy-ringing.mdx (new, in the Migration Guide navigation group): before/after, seven steps, a method mapping table and a checklist.
• setup: 5.1, the push products ringing needs, Info.plist and capability notes, and iOS 15.1 (the source floor).
• events: getActiveSession (it can return nil), onConnected / onParticipantConnected, prepared-session semantics, and the Incoming Call and Login listener sections.
• actions and custom-control-panel: leave() and isSessionActive().
• overview, migration-guide-v5 (5.0 → 5.1) and troubleshooting: updated to match.

Push Notifications SDK

• calls/ios/voip-calling.mdx is rewritten as Push Ringing; the slug is unchanged, so no redirect is needed. It covers:
  • the products, capabilities and Info.plist, and initialising in didFinishLaunching on every launch;
  • every configuration option with its default, presentCall / callDidEnd, and ring readiness and diagnostics;
  • how a ring ends, call waiting, the killed app, logout (wait for unregisterTokens first), CallKit branding and troubleshooting.
• notifications/ios-push-notifications-sdk.mdx is rewritten for 2.0. The APNs and FCM pages get a short pointer note.

Chat SDK

• sdk/ios/calling-overview and sdk/ios/all-real-time-delegates-listeners note that the Chat SDK calling APIs are superseded.

How it was checked

• Against the source: every API, default and behaviour was checked against calls-core prepare-session-flow (5.1.0-beta.2), push-notifications-sdk-ios release/2.0 (2.0.0-beta.2) and the Connect iOS app.
• Samples: the Push SDK's Swift samples were typechecked against the real sources.
• Independent review: a second, independent check against the source followed, and its findings are fixed.
• Structure: links, anchors and navigation resolve.

Before merging

• Versions are placeholders for the public releases: CometChatCallsSDK 5.1.0 and Push Notifications SDK 2.0.0. Do not merge before they are published.
• The Push SDK 2.0 install doesn't work yet (fix in the SDK before release):
  • The public cometchat/push-notifications-sdk-ios has only tag 1.0.0.
  • All four 2.0 podspecs set source to github.com/cometchat/push-notifications-ios, which doesn't exist.
  • Package.swift depends on the private cometchat-team/calls-core.
• One provider ID for both tokens. 2.0 registers the APNs and VoIP tokens under a single provider ID (a .p8 APNs provider). Confirm with the backend that this works (plan ios-voip-push-sdk §7.15/§7.20). The older APNs page still describes separate Device and VoIP providers.
• Dashboard setting. The migration page's "ringing migration" setting needs its real name and location; the TODO(RC) stays until then.
• Objective-C tabs. The Calls SDK ships no Swift→Objective-C header (SWIFT_INSTALL_OBJC_HEADER = NO, already the case in 5.0.4), so the Objective-C tabs on the iOS Calls pages, old and new, can't be used as written. Either ship the header, or drop the Objective-C tabs site-wide.
• UI Kit pages aren't in this PR. The iOS UI Kit's ringing is on two unmerged branches (feat/ringing-v2, ENG-39915). Its pages come in a follow-up.
• Overlaps with docs(ENG-39303): iOS Calls SDK v5 corrections #534 (iOS Calls SDK v5 corrections) on ringing, voip-calling, events, setup and others. Whichever merges second resolves the conflicts.
• Rendered pass with mint dev.

SDK issues found while writing (not docs)

• defaultRingTimeoutMs is saved but never used; the ringer always uses 45 s. Left out of the docs.
• notificationContentModifier has no effect, because the modified copy is thrown away. Listed as "no effect" in the upgrade table.
• CometChatPushNotificationsCalls.answer(sessionId:) says it acts "exactly as CallKit's Answer" but bypasses CallKit, so the CallKit call isn't updated and no audio session is set up. The docs call it test-only.

Related: ENG-39907.

🤖 Generated with Claude Code

[mintlify]

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

Project	Status	Preview	Updated
cometchat	🟢 Ready	View Preview	Oct 27, 2026, 6:41 PM

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