cometchat-flutter-v6-calls
Add voice & video calling to a Flutter app with the CometChat v6 UI Kit — turn calling on in settings, wire the native config and the root navigatorKey (the kit presents incoming/outgoing call screens itself), and add call-log surfaces. Triggers: 'add voice and video calls in flutter', 'add calling to my flutter chat', 'enable video call flutter', 'add call buttons flutter', 'show call logs flutter'.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- cometchat-flutter-v6-calls
- license
- MIT
- metadata
- { "tags": "cometchat flutter calls voice video calling webrtc v6", "author": "CometChat", "version": "1.0.0" }
- description
- Add voice & video calling to a Flutter app with the CometChat v6 UI Kit — turn calling on in settings, wire the native config and the root navigatorKey (the kit presents incoming/outgoing call screens itself), and add call-log surfaces. Triggers: 'add voice and video calls in flutter', 'add calling to my flutter chat', 'enable video call flutter', 'add call buttons flutter', 'show call logs flutter'.
- compatibility
- Flutter >=3.38.9; cometchat_chat_uikit ^6.2.0 (6.2.x; catalog compiler-verified vs 6.1.0, source-checked vs 6.2.0); cometchat_calls_sdk ^5.0.8 (5.0.9 latest — separate package)
02 资源文件 1
- 参考文档references/huddle.md6.9 KB
03 SKILL.md 正文
Ground truth: the call UI ships INSIDE
cometchat_chat_uikit, but in a second barrel, and the WebRTC engine is a separate package (cometchat_calls_sdk). Every symbol below is catalog-verified against 6.1.0. Exhaustive props: FETCH the twin via../cometchat-flutter-v6-core/references/docs-map.md(call-features·incoming-call·outgoing-call·call-logs·call-buttons). APPEND to the user's app — additive wiring only.
Companion skills (read first)
cometchat-flutter-v6-core— install, credentials, the settings asset,init→login→render. This skill ASSUMES it (calling rides the SAME init).cometchat-flutter-v6-components— the widget catalog.cometchat-flutter-v6-placement— where call surfaces sit in the app shell (incoming calls need only the rootnavigatorKey— no widget).
Use this skill when
"add voice & video calls", "enable video call", "add call buttons", "show call logs". Precondition: chat already works (core done).
Prerequisites & install
cometchat_chat_uikit already depends on cometchat_calls_sdk (^5.0.8, in the kit's own dependencies: — verified in the 6.2.0 pubspec; 6.1.x asked for ^5.0.4), so the WebRTC engine is pulled in transitively; you do not need to add it. Add an explicit direct dependency only if you import cometchat_calls_sdk symbols directly (then pin it to keep resolution predictable):
flutter pub add cometchat_calls_sdk # optional — only if you import the package directly
Then the native config the docs require — all four steps, or calling silently never rings:
cometchat_calls_sdk(transitive via the kit; pin^5.0.8inpubspec.yamlonly if you added it directly: the 6.2.0 kit does not compile against older).- Android
android/app/build.gradle.kts:minSdk = 26. - iOS
ios/Podfile:platform :ios, '15.1', thenpod install. - Permissions — camera + microphone (
AndroidManifest.xml;NSCameraUsageDescription/NSMicrophoneUsageDescriptioninInfo.plist). Without them the call surface opens black.
⚠️ The docs' floors are too low and these are compiler-verified instead.
cometchat_calls_sdkpinsminSdkVersion 26in itsandroid/build.gradleandplatform :ios, '15.1'in its podspec (5.0.7 through 5.0.9; it was 13.0 through 5.0.6). Gradle and CocoaPods take the MAXIMUM across the dependency graph, so a lower app-level value is a build error, not a warning. Docs say 24 / 13.0 — DOCS-BACKLOG D7. Platform floors do move: re-verify against the installed package, not the page.
THE BARREL TRAP (read before writing a line)
Every call widget resolves only from the calls barrel, and that barrel does not re-export the chat widgets. A calls screen imports both:
import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart'; // chat widgets + SDK types
import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart'; // ALL call widgets
Importing only the chat barrel and then emitting CometChatIncomingCall fails to compile with "Undefined name" — the single most common calls mistake.
Enable calling (BAKED — the #1 gotcha: TWO things must be true)
Calling is off until (a) the Calls SDK is installed and (b) calling is enabled in settings. Core inits via initFromSettings, which reads cometchat-settings.json — so flip it in the file:
{
"appId": "APP_ID",
"region": "REGION",
"credentials": { "authKey": "AUTH_KEY" },
"uiKit": { "subscribePresenceForAllUsers": true, "enableCalling": true },
"chatSDK": { "autoEstablishSocketConnection": true }
}
uiKit.enableCallingis the only way to enable calling on theinitFromSettingspath —UIKitSettingsdefaults it to false. (If the project uses the classic builder instead, the equivalent is..enableCalls = trueplus..callingConfiguration = CallingConfiguration().)
Wire it (BAKED)
1. A navigator key at the app root so the kit can present call screens from anywhere:
import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart';
import 'package:flutter/material.dart';
Widget app(Widget home) => MaterialApp(
navigatorKey: CallNavigationContext.navigatorKey, // REQUIRED for call routing
home: home,
);
2. That's it for incoming calls — the kit does the rest. Do NOT add your own root CallListener or present CometChatIncomingCall yourself. When uiKit.enableCalling is true, the kit's CallEventService registers its own CometChat.addCallListener(...) on login and shows the incoming-call overlay automatically via IncomingCallOverlay (verified in cometchat_chat_uikit 6.1.x and 6.2.0). Adding a second listener + a manual overlay produces a DOUBLE incoming-call screen. All you owe it is the navigatorKey from step 1 (that is how the overlay finds a context to present — without it the kit logs "Incoming call overlay cannot be shown").
To customize the incoming/outgoing/call-button surfaces, pass a CallingConfiguration — not a hand-rolled listener. On the classic builder path: ..callingConfiguration = CallingConfiguration(incomingCallConfiguration: ..., outgoingCallConfiguration: ..., callButtonsConfiguration: ...). CallingConfiguration (with incomingCallConfiguration / outgoingCallConfiguration / callButtonsConfiguration) is the kit's supported entry point; fetch its fields via the twin (call-features).
3. Extra surfaces you place yourself — call logs, and the incoming/outgoing widgets only when you build a fully custom flow — from the CALLS barrel:
import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart';
import 'package:flutter/material.dart';
Widget logs() => const CometChatCallLogs();
// Only when replacing the built-in overlay with a fully custom flow — otherwise the kit
// already presents these for you:
Widget incoming(Call call, User user) => CometChatIncomingCall(call: call, user: user);
Widget outgoing(Call call, User user) => CometChatOutgoingCall(call: call, user: user);
Call buttons are already in
CometChatMessageHeader— do NOT hand-roll them. They appear once calling is enabled; hide withhideVoiceCallButton/hideVideoCallButton.CometChatCallButtonsis for placing them somewhere else (e.g. a profile screen).
Huddle / docked call — Flutter how-to (BAKED — verified vs cometchat_chat_uikit 6.2.0 + cometchat_calls_sdk 5.0.9)
Slack-style huddle (start from the channel header, Join opens your dock, leave cleans up): references/huddle.md. Pattern: cometchat-onboarding/references/clone-mode.md → Huddle / drop-in room pattern.
Common pitfalls (BAKED — the ones that actually bite)
- Enabled in only one place — SDK installed but
enableCallingfalse (or vice-versa) ⇒ every call affordance stays hidden, with no error. - Missing camera/mic permissions ⇒ the call surface opens black. Test on a real device; simulators have no camera.
- Adding your own root
CallListener+CometChatIncomingCall⇒ a DOUBLE incoming-call screen. The kit'sCallEventServicealready listens and shows the overlay when calling is enabled — don't duplicate it; customize viaCallingConfiguration. - No
navigatorKey(CallNavigationContext.navigatorKeyon yourMaterialApp) ⇒ the kit's overlay has no context to present from and logs "Incoming call overlay cannot be shown". - A call surface with no bounded height ⇒ zero-dimension video (
../cometchat-flutter-v6-core/references/layout.md). - A docked or mini call opened full screen — the group call button and the meeting bubble's Join both open
CallScreenOverlay(a full-screen overlay). For a dock, replace both and join the session into your own box (references/huddle.md). - Group calls do not ring the way 1:1 does — group calling is join-based. Verify the behaviour you promise against
call-features. - Details screens are host-composed — there is no
CometChatCallLogDetailswidget; build it fromguide-call-log-details.
Verify it works
On TWO real devices (not simulators): calling enabled in the settings file and the Calls SDK installed → the header shows call buttons → placing a call rings the other device → accept shows the ongoing surface with real video → decline/end returns both sides cleanly → the call appears in CometChatCallLogs. A black surface means permissions; no ring means the enable pair or a missing navigatorKey; two incoming screens means a hand-added listener/CometChatIncomingCall.
Build the feature; do not write tests unless asked (
RULES.md) — the above is an advisory human pass.
Close (after it builds): end with the shared 3-option selectable menu and WAIT — (1) add another feature · (2) customize theming · (3) test it manually (same contract as core, RULES.md §19).
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.