Cometchat React V7 Calls

Ground truth: calling is part of @cometchat/chat-uikit-react@7 (the call UI ships INSIDE the kit — there is no separate calls-UI package), but the WebRTC engine is a SEPARATE, NOT-bundled dependency: @cometchat/chat-uikit-react@^7 + @cometchat/chat-sdk-javascript@^4.1.9 + @cometchat/calls-sdk-javascript@^5 (major 5 — distinct from the chat SDK's v4). Every CometChat* symbol below exists in the web-v7 catalog. Exhaustive props + advanced call surfaces are FETCHED from the docs .md twins via cometchat-react-v7-core/references/docs-map.md. APPEND to the user's app — additive wiring only (RULES.md).

Companion skills (read first)

• cometchat-react-v7-core — install, credentials, init→login→render, CometChatProvider. This skill ASSUMES it (calling is enabled on the SAME init).
• cometchat-react-v7-components — the component catalog (message header the call buttons live in).
• cometchat-react-v7-features — voice-video-calls is the feature entry; this skill is its operational depth.

Use this skill when

"add voice & video calls", "add calling to my chat", "enable video call", "add call buttons", "show call logs". Precondition: chat is already integrated (core done) — calling rides on the same init/login.

Prerequisites & install

Core setup done (init + login + CometChatProvider). Calling adds ONE package:

npm install @cometchat/calls-sdk-javascript@5

The Calls SDK is major 5 (not the chat SDK's v4) and is NOT bundled by the UI Kit — if it isn't installed, every call affordance stays hidden. Do not "upgrade" @cometchat/chat-sdk-javascript to a non-existent v7; it stays ^4.1.9.

Enable calling (BAKED — the two-part contract, the #1 gotcha)

Calling is OFF until BOTH are true: the Calls SDK is installed (above) and calling is turned ON in the init settings. Since the core inits via CometChatUIKit.initFromSettings (telemetry — RULES.md §5 / AUDIT-084), enable calling IN the SAME settings object with a truthy uiKit.callsSDK:

import { CometChatUIKit } from "@cometchat/chat-uikit-react";

await CometChatUIKit.initFromSettings({
  appId: APP_ID, region: REGION,
  credentials: { authKey: AUTH_KEY },                        // dev-only; prod → server-minted auth token
  chatSDK: { presenceSubscription: { type: "ALL_USERS" } },
  uiKit: { callsSDK: {} },   // ← turns calling ON (the initFromSettings equivalent of setCallingEnabled(true))
});

How calling maps in the initFromSettings path (verified vs the compiled 7.1.x kit; DOCS-GAP). The kit computes callingEnabled = !!settings.uiKit.callsSDK, so a truthy uiKit.callsSDK is the initFromSettings equivalent of UIKitSettingsBuilder().setCallingEnabled(true) — WITHOUT it, call buttons + incoming-call render nothing. The docs don't yet document this shape (owner: docs — confirm with a live call). The classic path still works — CometChatUIKit.init(new UIKitSettingsBuilder()…setCallingEnabled(true).build()) — but it SKIPS the ai-agent telemetry attribution, so prefer initFromSettings. No separate CometChatUIKitCalls.init() is needed for the default path. (CometChatUIKitCalls is the kit's namespace for advanced call-settings builders; reach for it only on a custom surface — FETCH then.) initFromSettings routes the Calls SDK internally — do NOT call raw CometChat.init().

Wire the UI (BAKED — least-code path)

Two moves cover ringing end-to-end:

1. Mount CometChatIncomingCall ONCE at the app root (above your routes). It self-manages visibility — renders nothing when idle, rings on an inbound call — so no conditional wrapper. It attaches its own SDK listeners.

   import { CometChatIncomingCall } from "@cometchat/chat-uikit-react";
   // at the app shell, inside CometChatProvider, above the router:
   <CometChatIncomingCall />

2. Let CometChatMessageHeader surface the call buttons. When a user/group is selected, the header composes voice/video call buttons itself once calling is enabled — you usually mount NOTHING extra. Only drop a standalone CometChatCallButtons user={user} (1:1) or group={group} on a CUSTOM header that has no CometChatMessageHeader. Never mount both — a standalone CometChatCallButtons next to a CometChatMessageHeader duplicates the buttons.

Call logs (optional history surface): CometChatCallLogs on a sidebar or a /calls route (onItemClick, onCallButtonClicked, callLogRequestBuilder). It does NOT auto-refresh on a new call — remount to refresh. It shows the kit's "OOPS! …" screen when call logs aren't available — and, verified live, it renders that from its OWN INTERNAL error state WITHOUT throwing, so a host CometChatErrorBoundary/fallbackView CANNOT override it and onError may not fire. A fallbackView is NOT the fix (AUDIT-162). Enabling calling is NOT sufficient for CometChatCallLogs: call-logs availability is a SEPARATE plan/capability gate — an app can have calling ON (Voice/Video buttons render) yet CometChatCallLogs still "OOPS" because call-logs isn't in the plan. The only reliable protection is to GATE the Calls tab on real call-logs AVAILABILITY (a one-time SDK probe you own — new CometChatCalls.CallLogRequestBuilder().setLimit(1).setAuthToken(await CometChatUIKitCalls.generateToken(...)).build().fetchNext(), show the tab only on success — or your known plan), NOT merely on calling being enabled; default the tab OFF so a plain app never dead-ends. Import discipline (AUDIT-204): CallLogRequestBuilder is NOT a named export of @cometchat/calls-sdk-javascript — it is a STATIC on the CometChatCalls default-export class (verified vs calls-sdk 5.0.5 dist/index.d.ts): use import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; new CometChatCalls.CallLogRequestBuilder()… — a import { CallLogRequestBuilder } from "@cometchat/calls-sdk-javascript" FAILS (TS2614). generateToken is on CometChatUIKitCalls (from @cometchat/chat-uikit-react). (Gated Calls-tab recipe with the full probe + imports: ../cometchat-react-v7-placement/references/recipes.md Combined-app recipe.)

1:1 rings, groups JOIN (BAKED — no group-ring)

• 1:1: call buttons → the kit initiates a call → the recipient's root CometChatIncomingCall RINGS → accept → the ongoing-call surface. The kit drives outgoing → ongoing for you.
• Group: call buttons on a group send a group-call meeting message into the chat; members JOIN from that message. There is no "ring the whole group" primitive — surface the join affordance, never wait for a ring.