docs(flutter): ringing on Calls SDK 5.1 + cometchat_voip, chat-only push, UI Kit calling

[DhruvKushvaha2004]

Description

Flutter docs for the new ringing flow. Calls are placed and ended with the Calls SDK 5.1, and incoming calls ring through cometchat_voip in every app state. Push notifications are now chat only. The structure follows the Android PR (#561).

Push notifications (chat only)

• New notifications/flutter-push-notifications.mdx on cometchat_push_notifications 2.0.
• New notifications/push-getting-started.mdx.
• Removed flutter-push-notifications-android / -ios, with redirects.

Calls SDK (Flutter)

• Ringing (calls/flutter/ringing): replaces the Chat SDK ringing page in place. Covers start a call, "Ringing…", answer, join, decline, cancel, ring timeout, end, a call while in a call, logout, and call status values.
• Push Ringing (calls/flutter/voip-calling): rewritten for cometchat_voip. Covers packages and platform setup, init, handing over pushes, push token, ring readiness, call modes (Auto, your own ring screen, Manual), how a ring ends, call waiting, missed calls, the killed/locked app, and troubleshooting.
• Migrating from Legacy Ringing (new): before/after code and the API mapping from the Chat SDK calling methods.
• Background Handling: covers the call after the join (Push Ringing keeps the app alive only until the answered call joins), launch(isVideo:), and a note that the UI Kit starts the service itself.
• Setup, actions (leave() replaces the deprecated leaveSession() / endCallSession()), events (prepared session, onParticipantConnected), overview, the v5 migration guide's "5.0 to 5.1" section, and troubleshooting.

Chat SDK (Flutter)

• sdk/flutter/real-time-listeners: Warning that CallListener and the Chat SDK calling methods are superseded.

UI Kit (Flutter v6)

• Calling Integration (new, under Getting Started):
  • enable calls, then init the Calls SDK and cometchat_voip;
  • the call push bridge (VoipCallPushBridge), callPushBridge and navigatorKey;
  • push hand-off, push token, ring readiness, and logout.
• Call features rewritten as an overview. Incoming Call is deprecated on Android and iOS (web only). Outgoing Call covers the Calling…/Ringing… states and its events.
• Events, Methods, Troubleshooting, Upgrading from v5 and Getting Started updated to match.

Type of Change

• Documentation correction/update
• New documentation
• Improvement to existing documentation
• Typo fix
• Other (please specify)

Checklist

• I have read the CONTRIBUTING document
• My branch name follows the naming convention
• My changes follow the documentation style guide
• I have checked for spelling and grammar errors
• All links in my changes are valid and working
• My changes are accurately described in this pull request

Additional Information

• Not ready to publish until the packages are released. The pages describe cometchat_calls_sdk 5.1, cometchat_voip 2.0 and the UI Kit's ringing branch. Hidden {/* TODO(RC) */} comments mark what to fill in at release: package versions, and the dashboard migration setting's name, path and screenshot (Migrating from Legacy Ringing → Rolling out).
• No "v1/v2" naming: the pages are "Ringing", "Push Ringing" and "Migrating from Legacy Ringing".
• The v4 Calls pages and the v4/v5 UI Kit pages are unchanged.
• Checked in a local Mintlify preview: all changed pages render, internal links and anchors resolve, and the diagrams display correctly in light and dark mode.

Screenshots (if applicable)

N/A (text and Mermaid diagrams only).

[mintlify]

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

Project	Status	Preview	Updated
cometchat	🟢 Ready	View Preview	Oct 16, 2026, 11:45 AM

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

[jitvarpatil]

🤖 Review Buddy (review-docs-pr)

Recommendation: request changes. Automated review; the final decision stays with a maintainer.

TL;DR. Structurally this is a clean reorg: 0 dangling nav refs (build is safe), both deleted Flutter push pages and /extensions/flutter-push-notifications redirect to the new page, 0 chained 404s, 0 broken in-content links in the changed pages, every cross-page anchor into the rewritten pages resolves, all images exist, and the Mintlify preview renders. I also cross-checked every API name on the new pages against cometchat_voip + cometchat_push_notifications (release/2.0), cometchat_calls_sdk 5.1 and the UI Kit ringing-v2-uikit branch — almost everything matches. What needs fixing before merge: the pages pin three package versions that don't exist on pub.dev yet (the PR says so — this is the merge gate), the UI Kit pin ^6.2.0 is wrong even after release because 6.2.0 already shipped without the bridge API, the caller-side end-reason strings the pages promise (rejected/busy/unanswered) are not what the SDK delivers, and the Ringing page says initiateCall is 1:1-only while the SDK and the Push Ringing page say otherwise.

P0 — blocker (merge gate)

• Pinned package versions are not published; merging to main publishes them live. calls/flutter/setup.mdx:31, calls/flutter/voip-calling.mdx:40-41, calls/flutter/migrating-from-legacy-ringing.mdx:68-69, ui-kit/flutter/calling-integration.mdx:42-43, notifications/flutter-push-notifications.mdx:66 pin cometchat_calls_sdk: ^5.1.0, cometchat_voip: ^2.0.0, cometchat_push_notifications: ^2.0.0. pub.dev today: cometchat_calls_sdk 5.0.9, cometchat_push_notifications 1.0.1, cometchat_voip not published (release/2.0 is at 2.0.0-beta4). Every reader's flutter pub get fails until the releases land. The PR body already says "not ready to publish" — this item just makes the hold explicit: do not merge before all three are on pub.dev, then resolve every {/* TODO(RC) */}.

P1 — fix before merge

• cometchat_chat_uikit: ^6.2.0 is the wrong pin — 6.2.0 is already on pub.dev and does not contain the ringing API. ui-kit/flutter/calling-integration.mdx:42 (and the TODO at :14 naming "cometchat_chat_uikit 6.2.0"). I pulled the published 6.2.0 tarball: no cometchat_call_push_bridge.dart, zero mentions of callPushBridge; its pubspec depends on cometchat_calls_sdk ^5.0.8. The ringing-v2-uikit branch still carries version: 6.2.0, so the page must pin whatever version that branch actually ships as (≥ 6.3.0), and the branch's pubspec needs its own bump (out of scope here, flagging for the Kit owners). ui-kit/flutter/getting-started.mdx:59,79 keep ^6.2.0 while :185 now advertises calling — after the release, bump those too.
• Caller-side end reasons are documented as rejected / busy / unanswered / cancelled, but that is not what onIncomingCallEnded delivers. calls/flutter/ringing.mdx:175 (table), :162-164 (code), calls/flutter/voip-calling.mdx:270-273, calls/flutter/migrating-from-legacy-ringing.mdx:198, :254. Evidence: on the Dart push path cometchat_voip maps the push action through CometChatCallEndReason.fromAction — rejected|busy|ended → declined, unanswered → timedOut, ongoing → answeredElsewhere — and injects reason.wireName (cometchat_voip/lib/cometchat_voip.dart:474-482); the Calls SDK hands that string straight to the listener (calls-sdk-flutter/lib/src/plugin/cometchatcalls.dart:388); the iOS native path sends declined/ended/failed/filtered; and the SDK's own doc-comment says the vocabulary differs per platform (lib/src/listener/incoming_call_listener.dart:13-18). Consequences: code comparing to "rejected"/"unanswered" never matches, and busy is indistinguishable from a decline on the caller. Fix: document the reason as a platform-dependent wire string and tell readers to normalise with CometChatCallEndReason.fromWire(reason) (it accepts both vocabularies), list the real values, and drop or caveat the caller-side busy distinction. The callee-side onCallEnded reasons (ringing.mdx:176) are correct.
• Group ringing contradicts the SDK and the sibling page. calls/flutter/ringing.mdx:90 documents options.receiverType as ReceiverType.user only and :293-295 says "initiateCall is for 1:1 calls", but InitiateCallOptions.receiverType accepts ReceiverType.group ("a user UID or a group GUID", lib/src/builder/initiate_call_options.dart:11-13, cometchatcalls.dart initiateCall doc-comment) and calls/flutter/voip-calling.mdx:275 already documents how a group ring ends. Either document group initiateCall (what rings, how it ends, no busy/unanswered sent) or make both pages agree that groups are join-by-id only and remove voip-calling.mdx:275.
• The "Rolling out" steps that keep old↔new apps interoperable are placeholders in the rendered page. calls/flutter/migrating-from-legacy-ringing.mdx:355-361 renders as "Go to the calling settings" / "Turn on the migration setting" with the real name, path and screenshot in hidden TODO(RC) comments. This is the step that stops calls breaking during the rollout window; it must be concrete before publish. Also acceptOnAnswer (:363, verified: exists, default true) appears only here — add it to the options table at calls/flutter/voip-calling.mdx:82-92.

P2 — nits

• TODO(RC) comments cite "cometchat_calls_sdk 5.1.0-team" (ringing.mdx:19, voip-calling.mdx:27, migrating-from-legacy-ringing.mdx:12, calling-integration.mdx:14), but the calls-core tag 5.1.0-team carries calls-sdk-flutter 5.0.8 with none of initiateCall / leave() / onParticipantConnected / addIncomingCallListener; the Flutter 5.1 API is on tag 5.1.0-beta.1. Point the RC re-check at the right ref (and cite release/2.0 for cometchat_voip rather than a beta number — it has already moved from beta2/beta4 to beta7 across these commits).
• calls/flutter/voip-calling.mdx:139-145 vs :192-196: the token table marks registerPushToken(token:) / handleTokenRefresh as "Android, iOS", the prose then says on iOS you pass a token only in manual mode, and the mode table says Manual is Android-only. Make the three agree (e.g. "Android — iOS: automatic" and drop the manual-on-iOS sentence).
• notifications/push-getting-started.mdx:9: the FCM list omits Flutter (Android) while :22 and :34 include it.
• notifications/flutter-push-notifications.mdx:33 "Flutter 3.3.0+ / Dart 3.10.8+" mirrors the plugin's pubspec, but Dart 3.10 implies Flutter ≥ 3.38, so the Flutter floor is misleading (the pubspec's flutter: '>=3.3.0' is the real culprit).
• Link text "Migrating from legacy ringing" (ringing.mdx:16,317, voip-calling.mdx:327) vs the page title "Migrating from Legacy Ringing".
• Pre-existing, not introduced here (FYI): 4 broken links in untouched calls/flutter pages — in-call-chat.mdx:444, share-invite.mdx:329 → /calls/flutter/button-click-listener; participant-management.mdx:142,145 → /calls/flutter/participant-actions, /calls/flutter/participant-event-listener — and two nav orphans ui-kit/flutter/llms-flutter-v6, sdk/flutter/llms-flutter-v5.

Passed / verified

• Build safe: 0 unresolved docs.json page refs. Redirects: /notifications/flutter-push-notifications-android and -ios → new page; /extensions/flutter-push-notifications retargeted; the legacy redirect from /notifications/flutter-push-notifications correctly removed so the new page isn't shadowed; 0 chained 404s; redirects 926 → 927.
• Links: 0 broken internal links in the 27 changed pages; all 7 cross-page anchors into the rewritten pages (#cancel-a-call, #answer-a-call, #your-own-ring-screen, #a-call-while-in-a-call, #step-2-initialize, #call-events, #receive-a-call) resolve; no page still links to the deleted URLs; all image refs resolve; GitHub repo link cometchat/push-notifications-sdk-flutter is public.
• API cross-check (source of truth, not the PR): cometchat_voip release/2.0 — init, CometChatVoipConfig.fromCallAppSettings(settings, providerId:) and every option in the table (defaults match, ring timeout 45 s), handlePushNotification(data, sentTime:), registerPushToken(token:), handleTokenRefresh, unregisterPushToken, checkRingReadiness + all 8 CometChatRingReadiness values, openSettings, verifyPushSetup + all 7 results, onCallRinging/onRingScreenRequested/onCallAnswered/onCallEnded, answer/accept/decline(busy:)/dismissRinging(answered:), reportOutgoingCall/reportCallConnected/reportCallEnded, getActiveCall, isInitialized, ringSurfaces.{showIncomingNotification,verify,stopRinging,keepAlive,showMissedCall}, CometChatVoipCall.{sessionId,isVideo,callType,receiverType,callerUid,callerName,callerAvatarUrl,expiresAt}, CometChatCallEnded.{call,reason}, reason.isMissed (= cancelled ∨ timedOut, matching the Missed-calls prose), reason.wireName, CometChatRingRequest.{call,answerEndsActiveCall}, the three CometChatCallModes; minSdk 26 / iOS 15.1; iOS answer→join cap is indeed 20 s (RingConstants.swift:29).
• cometchat_push_notifications 2.0 — init, all 7 config fields + defaults, requestPermission, registerPushToken({token, platform, providerId}), PushPlatform.FCM_FLUTTER_ANDROID/APNS_FLUTTER_DEVICE, handlePushNotification (returns false for call pushes), onNotificationTap response fields, setActiveConversation({id, receiverType}), CometChatPushReceiverType.user, setBadgeCount/getBadgeCount, clearNotifications({conversationId}), unregisterPushToken, cometchat_push_notifications_export.dart, NSE pod CometChatPushNotificationsNSE / CometChatNotificationServiceExtension / CometChatExtensionGroupID; minSdk 24, compileSdk 36, iOS 13.0.
• cometchat_calls_sdk 5.1 — initiateCall({receiver, options, onSuccess(InitiatedCall), onError}), InitiateCallOptions{type, receiverType, sessionSettings} (type defaults to video, as warned), InitiatedCall fields incl. isVideo, endCall({sessionId, status, onSuccess, onError}) + EndCallStatus.{rejected,cancelled,busy,unanswered}, addIncomingCallListener(id, listener) / IncomingCallListener.onIncomingCallEnded(InitiatedCall, String), getActiveSession, LoginListener, ParticipantEventListeners.onParticipantConnected, CallSession.leave() with leaveSession()/endCallSession() @Deprecated, CometChatOngoingCallService.launch({bool? isVideo})/abort(), FGS permissions declared in the plugin manifest, logout({onSuccess(String), onError}).
• UI Kit ringing-v2-uikit — CometChatCallPushBridge members exactly as the sample bridge (defaults on reportCallConnected/reportCallEnded), CometChatPushCall/CometChatPushCallEnded fields, exported from cometchat_calls_uikit.dart; UIKitSettings.enableCalls (default false) / callingConfiguration / callPushBridge; ccOutgoingCall event; @Deprecated on CometChatIncomingCall, IncomingCallOverlay, CometChatIncomingCallStyle; CallListener/CallListener2 hidden from both barrels; CometChatUIKit.logout runs call clean-up then the Calls logout; outgoing timeout 45 s (active_call_tracker.dart:180); refused-mic notice opens app settings.
• Mintlify preview: deployment green and /calls/flutter/ringing returns 200. Local Mintlify build not run here.

[raj-cometchat]

Thanks — worked through this against the local cometchat_voip (release/2.0), cometchat_calls_sdk 5.1.0-team and the UI Kit ringing-v2-uikit branch. Fixed in 7e06803.

Fixed

Caller-side end reasons. Confirmed: onIncomingCallEnded(call, reason) carries the native reason and the vocabularies differ — Android injects call statuses (RingController.kt:104,214 → rejected, busy, unanswered), iOS injects CallKit reasons (CallEndReason.swift → declined, remoteEnded, timedOut, filtered…), and the Dart push path injects the already-normalised reason.wireName (cometchat_voip.dart:474-482). The SDK's own doc-comment (incoming_call_listener.dart:13-19) says as much. So reason == "rejected" matched on one platform only. All four places now route through CometChatCallEndReason.fromWire(reason) (verified: exists, exported, reads both vocabularies), list the values that come back, and state that a busy decline folds into declined — so the caller can't distinguish it from a plain decline.

Group ringing. initiateCall's doc-comment says "a user UID or a group GUID", and InitiateCallOptions.receiverType accepts ReceiverType.group. The "initiateCall is for 1:1 calls" line was wrong and contradicted Push Ringing. Ringing now documents the group ring and how it ends — nothing is sent back to the caller, which the Android source states outright ("A group call is declined here only… nothing is sent, so the call carries on for everyone else"). setPeerCall(true) is now scoped to 1:1, since it would end a group call for everyone.

UI Kit pin. pub.dev's latest cometchat_chat_uikit is 6.2.0, and the ringing-v2-uikit branch still carries version: 6.2.0 with a v6.2.0 changelog — so ^6.2.0 resolves to a release with no bridge. Pinned ^6.3.0 as a flagged placeholder, with the prose saying calling needs newer than 6.2.0, and TODOs on both this page and Getting Started. The branch's own pubspec bump is for the Kit owners.

Nits. acceptOnAnswer added to the config options table (verified: exists, default true). FCM note now includes Flutter (Android). The misleading Flutter 3.3.0+ floor replaced with the Dart floor that actually applies. Link-text capitalisation.

One correction to the review: Manual mode is not Android-only — CometChatCallMode.manual's doc says "On iOS the app owns the PKPushRegistry and forwards pushes with handlePushNotification". So the prose was right and the mode table was wrong; I fixed the table (Android and iOS) rather than dropping the manual-on-iOS sentence.

Still open

P0 version pins — the merge gate. Still true as of today: cometchat_calls_sdk 5.0.9, cometchat_push_notifications 1.0.1, cometchat_voip not published. Nothing to change in the docs; not merging until all three are on pub.dev, then every {/* TODO(RC) */} gets resolved.

The dashboard migration setting. Its name and path aren't recorded anywhere I can reach — not the voip README, changelog, props docs or skill — so I didn't invent them. The two placeholder steps are now a visible <Warning> marking the step unfinished, so the page can't ship reading as though it were complete. Needs the menu path, the toggle name and a screenshot before publish.

Not acted on

The P2 saying the 5.1.0-team ref carries calls-sdk-flutter 5.0.8 without initiateCall / leave() / onParticipantConnected: the 5.1.0-team package I have is version: 5.1.0-team and has all of them (initiateCall in cometchat_calls.dart, leave() at call_session.dart:348, onParticipantConnected in the participant listeners). Left those refs as they are; I only dropped the stale 2.0.0-beta / beta2 numbers for release/2.0.

The four pre-existing broken links and two nav orphans are out of scope here — worth their own PR.