cometchat-react-calls— agent skill

Ground truth: @cometchat/chat-uikit-react@^6 (+ @cometchat/calls-sdk-javascript@^5) — installed package types + ui-kit/react. Official docs: https://www.cometchat.com/docs/calls/javascript/overview · Docs MCP: claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.

⚠️ STOP — mandatory precondition before any code

Before writing one line of code, you MUST resolve `mode = ringing | session`. This decides which entire integration shape you scaffold — they don't share UI, navigation, or surface.

How to resolve mode (in order):

1. Check `.cometchat/config.json` for `mode` — if set by the cometchat-calls dispatcher's Step 3.0, trust it.
2. Infer from the user's words — see cometchat-calls/SKILL.md Step 3.0 inference table. Confirm in one line: "Got it — setting up Ringing. Say so if you wanted meeting-room URLs instead."
3. If still ambiguous (e.g. user said only "integrate calls" with no qualifier) — ASK before scaffolding. Don't default to ringing. Use this prompt verbatim — preserve the order, the labels, and the descriptions exactly. Do NOT rephrase. Do NOT swap options. Option 1 is "Session"; option 2 is "Ringing":

• question: "What kind of calling experience are you building?"
• header: "Calling mode"
• multiSelect: false
• options (display in this exact order — Session FIRST, Ringing SECOND):

1. label: "Session — meeting / conference room", description: "Multiple users join the same session by ID or link. No ringing. Like Google Meet, Zoom, or a Slack huddle."
2. label: "Ringing — 1:1 or group calls", description: "One user calls another (or a small group). Recipient's device rings; they accept or decline. Like FaceTime or WhatsApp calls."

Strict-order rule: the agent's UI primitive must render option 1 above the option 2. Do not let auto-mode classifiers or your own bias reorder them. Session is shown first because the dashboard team has standardized on this order across CometChat product surfaces; consistency matters more than any subjective "first option" preference.

Do not write `CometChatCallButtons` / `CometChatIncomingCall` / `CometChatOngoingCall` code without a confirmed `mode === "ringing"`. Those components are the kit's implementation of ringing; using them silently locks the integration into ringing-shape even if the user wanted a meeting-room flow.

⚠️ Call container — must have non-zero dimensions when joinSession fires

The Calls SDK measures the container <div> synchronously when joinSession runs and throws Container dimensions and number of tiles must be positive if width or height is 0. This is the calls equivalent of the chat-layout flex-shrink trap.

Common bug — `h-full` on a flex child resolves to 0:

// ✗ WRONG — `h-full` is `height: 100%`, but the parent's height is auto
//   so 100% of auto = 0. SDK crashes.
<section className="flex-1">
  <div ref={containerRef} className="h-full w-full" />
</section>

Fix — use a flex chain with `min-h-0` and an explicit fallback:

// ✓ RIGHT — section is a flex column with min-h-0 (so it can shrink), the
//   container uses flex-1 to claim remaining space, plus an explicit
//   `minHeight` safety net for very short viewports.
<section className="relative flex flex-1 min-h-0">
  <div
    ref={containerRef}
    className="flex-1 w-full"
    style={{ minHeight: 400 }}
  />
</section>

If you can't use flex (e.g. fixed-height modal), just give the container explicit pixels:

<div
  ref={containerRef}
  style={{ width: "100%", height: "calc(100vh - 100px)" }}
/>

minHeight: 0 matters specifically for parent flex containers that house the call container — without it, a flex-column ancestor whose content overflows defaults to min-height: auto and the call surface gets squeezed to zero. This is the same trap as cometchat-react-patterns's chat-layout rule, applied to calls.

⚠️ Idle timeout is in MILLISECONDS (the "Are you still there? → instant exit" bug)

The idle-timeout values are milliseconds, not seconds. This is the single most common calls-config footgun (customer-reported 2026-06): setting idleTimeoutPeriodBeforePrompt: 180 thinking "180 seconds" means 180 ms — so the moment you join a session alone, the "Are you still there?" prompt fires and the call exits in a fraction of a second.

// ✗ WRONG — read as 180ms / 30ms → prompt + exit almost instantly on join
const settings = { idleTimeoutPeriodBeforePrompt: 180, idleTimeoutPeriodAfterPrompt: 30 };

// ✓ RIGHT — milliseconds. (defaults: 60_000 / 120_000)
const settings = {
  idleTimeoutPeriodBeforePrompt: 180_000, // 180s before the prompt
  idleTimeoutPeriodAfterPrompt: 60_000,   // 60s grace before disconnect
};

Set them as SessionSettings object fields (used with joinSession(token, settings, container)): { idleTimeoutPeriodBeforePrompt: 180_000, idleTimeoutPeriodAfterPrompt: 60_000 }. ⚠️ There are no setIdleTimeoutPeriodBeforePrompt/AfterPrompt builder methods — CallSettingsBuilder has only a single setIdleTimeoutPeriod(ms); the before/after split exists only as the two object fields. `idleTimeoutPeriodAfterPrompt` has a 60_000 ms (60s) minimum — smaller values are silently clamped to 60s. To effectively disable it, use a huge value (86_400_000 = 24h), never 0 or a tiny number. The timer only counts down when you're the only participant — so a single-person session/test triggers it fastest. Full recipe (prompt UI + extend/leave): references/idle-timeout.md.

⚠️ Next.js / SSR — mandatory bundler config

Both SDKs ship code that breaks Next.js's SSR pass:

• @cometchat/chat-sdk-javascript references window at module load time
• @cometchat/calls-sdk-javascript (v5) imports Node built-ins (fs, path) gated by a runtime check that the bundler still tries to statically resolve

"use client" alone does NOT fix this — Next.js evaluates client components during the initial SSR pass for hydration. You need to defer the SDK imports so they only execute in the browser.

For Next.js (App Router or Pages Router), apply ALL of these:

1. Switch dev/build to webpack in package.json scripts (Turbopack's fs/path aliasing is fragile in Next 16):

   {
     "scripts": {
       "dev": "next dev --webpack",
       "build": "next build --webpack",
       "start": "next start"
     }
   }

1. Add a webpack `fs` fallback in next.config.ts:

   import type { NextConfig } from "next";
   const nextConfig: NextConfig = {
     webpack: (config, { isServer }) => {
       if (!isServer) {
         config.resolve = config.resolve || {};
         config.resolve.fallback = {
           ...(config.resolve.fallback || {}),
           fs: false,
           path: false,
         };
       }
       return config;
     },
   };
   export default nextConfig;

1. Wrap the CometChatProvider in `next/dynamic({ ssr: false })` — create a small client wrapper and use it from a server-component layout:

   // app/_components/CometChatGate.tsx
   "use client";
   import dynamic from "next/dynamic";
   import type { ReactNode } from "react";

   const CometChatProvider = dynamic(
     () => import("@/cometchat/CometChatProvider").then((m) => m.CometChatProvider),
     { ssr: false, loading: () => <div>Loading…</div> },
   );

   export function CometChatGate({ children }: { children: ReactNode }) {
     return <CometChatProvider>{children}</CometChatProvider>;
   }

⚠️ Provider placement for Ringing mode — mount at app root, not on a sub-route layout. If the CometChatProvider registers a global CallListener for incoming calls (which it should — see "Ringing mode listener" below), it MUST be mounted in the root layout (app/layout.tsx). Mounting it on a sub-route layout like app/meet/layout.tsx means the listener is only armed while the user is browsing under that sub-route — incoming calls land silently when they're on the home page or any other route, and the caller sees a timeout/rejection.

   // app/layout.tsx (server component, root layout)
   import { CometChatGate } from "./_components/CometChatGate";
   export default function RootLayout({ children }: { children: React.ReactNode }) {
     return (
       <html><body>
         <CometChatGate>{children}</CometChatGate>
       </body></html>
     );
   }

For Session-only mode (no ringing — both parties navigate to a shared /meet/:id URL), the sub-route layout is fine — listener isn't load-bearing.

Ringing mode listener — inside CometChatProvider, after login:

   const { CometChat } = await import("@cometchat/chat-sdk-javascript");
   CometChat.addCallListener("ringing-listener", new CometChat.CallListener({
     onIncomingCallReceived: async (call: any) => {
       const accepted = await CometChat.acceptCall(call.getSessionId());
       router.push(`/meet/${encodeURIComponent(accepted.getSessionId())}`);
     },
     onOutgoingCallAccepted: (call: any) => {
       router.push(`/meet/${encodeURIComponent(call.getSessionId())}`);
     },
     onOutgoingCallRejected: (call: any) => { /* show toast */ },
     onIncomingCallCancelled: (call: any) => { /* dismiss any UI */ },
   }));

The /meet/:sessionId page handles joinSession. Validated end-to-end against Pixel 3 V6 Android peer on 2026-05-12.

1. Lazy-load the SDKs inside `init.ts` — replace top-level static imports with await import(...) inside the init/login functions. The provider is gated by step 3, but init.ts is shared with any page that uses CometChatCalls directly, so belt-and-braces it:

   let chatModule: typeof import("@cometchat/chat-sdk-javascript") | null = null;
   let callsModule: typeof import("@cometchat/calls-sdk-javascript") | null = null;

   async function loadSdks() {
     if (!chatModule) chatModule = await import("@cometchat/chat-sdk-javascript");
     if (!callsModule) callsModule = await import("@cometchat/calls-sdk-javascript");
     return { CometChat: chatModule.CometChat, CometChatCalls: callsModule.CometChatCalls };
   }

1. No top-level SDK imports in any page that's reachable via App Router routing. Inside useEffect handlers, dynamic-import the SDK:

   useEffect(() => {
     let CallsSdk: typeof import("@cometchat/calls-sdk-javascript").CometChatCalls | null = null;
     (async () => {
       const mod = await import("@cometchat/calls-sdk-javascript");
       CallsSdk = mod.CometChatCalls;
       // ... use CallsSdk
     })();
     return () => {
       try { CallsSdk?.leaveSession(); } catch { /* noop */ }
     };
   }, []);

Skipping any of these reproduces the failure mode: the route 500s with either Module not found: Can't resolve 'fs' or ReferenceError: window is not defined. Verified empirically against Next.js 16.2.6 + Calls SDK 5.0.0-beta.2.

For Vite / React Router / Astro, none of this applies — those bundlers don't pre-evaluate client modules.

Purpose

Production-grade voice + video calling for React-family web apps. Loaded by cometchat-calls when framework is one of reactjs, nextjs, react-router, or astro. Operates in two modes:

• Standalone — calls is the product. @cometchat/chat-sdk-javascript (signaling) + @cometchat/calls-sdk-javascript (WebRTC) + a small set of UI Kit call components. No CometChatConversations / CometChatMessageList / etc.
• Additive — calls layered onto an existing CometChat React UI Kit integration. Adds call buttons inline, mounts CometChatIncomingCall at app root.

Read these other skills first:

• cometchat-calls — dispatcher (modes, hard rules, anti-patterns)
• cometchat-core — Chat SDK init, login, env-var prefix per framework, SSR safety
• Framework-specific patterns: cometchat-react-patterns / cometchat-nextjs-patterns / cometchat-react-router-patterns / cometchat-astro-patterns

Ground truth:

• SDK source — calls-sdk-javascript-5/package/
• Sample apps — calls-sdk-javascript-5/sample-apps/{react,vue,angular,svelte,ionic}/
• Public docs — https://www.cometchat.com/docs/calls/javascript/overview

When to use

• React-family web apps with voice/video calling: Vite + React, Next.js (App or Pages Router), React Router v6/v7, Astro with React islands.
• The user wants 1:1 OR group calls AND wants the calls UI surface (not pure server-side / signaling-only).
• Either calling mode applies — ringing (kit-driven incoming call screen) OR session (meeting-room URL pattern).

When NOT to use

• Chat-only integrations (no calling at all) — skip this skill entirely. Load only cometchat-core + cometchat-react-patterns + cometchat-components. Don't install @cometchat/calls-sdk-javascript — the calls SDK alone is ~700 KB; with the kit + chat SDK the full production bundle of a chat-and-calls app is ~4.8 MB JS (verified — real vite build). That's expected; a green build also emits benign COMMONJS_VARIABLE_IN_ESM warnings from the calls SDK's own code and a >500 KB chunk-size warning — these are NOT failures.
• Native mobile (Android / iOS / RN / Flutter) — load the cohort-specific calls skill (cometchat-native-calls, cometchat-android-v6-calls, cometchat-ios-calls, cometchat-flutter-v6-calls). The Calls SDK is platform-specific; APIs and lifecycle differ.
• Angular — load cometchat-angular-calls. Same underlying JS Calls SDK but wrapped in Angular Services + @Output() event bindings (NOT React-style callback props — verified runtime smoke 2026-06-02 caught the v4→v5 binding inversion).
• SDK-only (no UI Kit) — cometchat-react-calls §4c covers the SDK-only path in detail; this is the right skill, but you're using a specific subset. Don't import <CometChatCallButtons> / <CometChatOngoingCall> / <CometChatIncomingCall> from @cometchat/chat-uikit-react in that mode.
• Server-side token-mint server work — load cometchat-production for the REST-API token recipes; this skill is client-side.
• Visual Builder calls — load cometchat-core §11 + the framework-specific patterns; the Visual Builder generates calls wiring differently.

1. The seven hard rules — web specialization

1.1 Dual-SDK contract

@cometchat/chat-sdk-javascript for ringing; @cometchat/calls-sdk-javascript for the WebRTC session. They are separate npm packages.

// ✓ RIGHT — initiate ringing (Chat SDK)
import { CometChat } from "@cometchat/chat-sdk-javascript";

const outgoing = new CometChat.Call(receiverUid, CometChat.CALL_TYPE.VIDEO, CometChat.RECEIVER_TYPE.USER);
const initiated = await CometChat.initiateCall(outgoing);
// initiated.getSessionId() — the ID the Calls SDK will join

// ✓ RIGHT — join WebRTC session (Calls SDK v5)
import { CometChatCalls } from "@cometchat/calls-sdk-javascript";

// v5 — plain SessionSettings object, no Builder.
// `as const` keeps the string literals narrow ("VIDEO"/"TILE") so they satisfy
// the SDK's SessionType / Layout unions — a bare object widens them to `string`.
const sessionSettings = {
  sessionType: "VIDEO",   // or "VOICE"
  layout: "TILE",
} as const;

// v5 — generateToken takes ONLY sessionId (Calls SDK has its own auth state
// after CometChatCalls.login(); no authToken arg needed).
const tokenRes = await CometChatCalls.generateToken(sessionId);

// htmlElement is REQUIRED — pass the DOM container the SDK should draw into
const container = document.getElementById("ongoing-call-root")!;
const result = await CometChatCalls.joinSession(tokenRes.token, sessionSettings, container);
if (result?.error) {
  console.error("joinSession failed:", result.error);
}

The two-Call-classes problem from Android does NOT exist on JS — there's only one CometChat.Call constructor. But the dual-SDK split still trips up agents trained on the chat-only docs.

1.2 VoIP push — N/A on web (browsers don't have VoIP push)

The mandatory-VoIP-push rule from mobile families does not apply to web. Browsers cannot ring a closed tab. The standalone-mode equivalent is Web Push notifications (Service Worker + Notification API + push subscriptions) — useful for nudging the user to a tab where the call screen is open, but they do not bypass tab/page-load.

The skill scaffolds Web Push as an opt-in (asks user); it is not strictly required. Production calls UX on web typically pairs with email/SMS fallback for missed calls, not VoIP.

1.3 Lifecycle — getUserMedia cleanup

Web's equivalent of Android's foreground-service correctness is MediaStream track cleanup. Browsers don't release the camera/mic until tracks are explicitly stopped. The kit handles this for <CometChatOngoingCall />, but custom WebRTC surfaces (Section 4) must do:

function endCall() {
  // 1. End the Calls SDK session — releases the kit's internal stream
  CometChatCalls.leaveSession();   // v5 — was endSession() in v4 (still works as a deprecated shim)

  // 2. If you grabbed a custom MediaStream (preview, screen-share), stop tracks
  customStream?.getTracks().forEach(t => t.stop());
  customStream = null;

  // 3. Detach video elements
  if (videoEl.current) videoEl.current.srcObject = null;
}

Skipping this leaves the camera light on until the tab is closed. Same canonical bug as iOS rule 1.5.

1.4 Calls login — the DEFAULT path needs NONE; only directCalling/SDK-only do

✅ For the common case — additive ringing / default calling — do NOT call `CometChatCalls.login`. Install the calls SDK, let the call buttons appear automatically in CometChatMessageHeader, and mount <CometChatIncomingCall /> once at the app root. That's the whole wiring. Both canonical React v6 sample apps do calls this exact way with ZERO `CometChatCalls.login`/`CometChatCalls.init` (verified: cometchat-uikit-react-v6/sample-app/src/components/CometChatHome/CometChatHome.tsx:1740 mounts only <CometChatIncomingCall />; no CometChatCalls.login anywhere in either sample). The kit's default defaultCalling mode rides the Chat SDK's signaling — adding a calls-login step here is needless plumbing, and an empty/wrong arg makes it silently no-op.

`CometChatCalls.login` is required ONLY for (a) CallWorkflow.directCalling (conference-style 1:1) or (b) the SDK-only / custom-WebRTC surface (§4c). In those cases — and only those — the v5 Calls SDK needs its own login: after CometChat.login() resolves on the chat side, call `CometChatCalls.login(uid, apiKey)` for dev or `CometChatCalls.loginWithAuthToken(authToken)` for production. The auth token is the same one your backend mints via the CometChat Create-Auth-Token API; the Calls SDK and Chat SDK accept it interchangeably.

// Dev
await CometChatCalls.login(uid, import.meta.env.VITE_COMETCHAT_API_KEY);

// Production (server-minted token)
await CometChatCalls.loginWithAuthToken(authTokenFromBackend);

About `VITE_COMETCHAT_API_KEY`: CometChatCalls.login(uid, apiKey) takes the app's Auth Key — the same value cometchat-core writes as VITE_COMETCHAT_AUTH_KEY (the env-prefix table establishes APP_ID/REGION/AUTH_KEY, not a separate API_KEY). In dev you can reuse VITE_COMETCHAT_AUTH_KEY here; if you prefer the _API_KEY name for readability, add it to your .env with the same Auth Key value. Don't leave it undefined — an empty arg makes the Calls login silently no-op (see the directCalling trap above).

cometchat-production (web) covers the token-endpoint pattern.

⚠️ `CallWorkflow.directCalling` silently fails without this login. When you opt 1:1 calls into the conference-style UI by passing callWorkflow={CallWorkflow.directCalling} to <CometChatCallButtons> / <CometChatOngoingCall> etc., the kit routes through the Calls SDK directly and requires `CometChatCalls.login()` to have completed. Without it, calls ring for ~2 seconds then drop with no error message — the most painful failure mode in this skill. The UI Kit's default defaultCalling mode does NOT have this requirement (it uses the Chat SDK's signaling). Rule when emitting directCalling: always include the CometChatCalls.login(...) call alongside the Chat login above (ENG-35709).

1.5 Hangup cleanup — see rule 1.3

1.6 Permissions — getUserMedia prompts

The browser handles the runtime permission prompt automatically when the Calls SDK calls getUserMedia. The integration must:

• Surface a try/catch around startSession to handle NotAllowedError (user denied)
• Surface NotFoundError (no camera/mic on device — common on desktops with no webcam)
• Render a clear in-app explanation BEFORE the browser prompts, so users know what they're agreeing to (browsers ignore this in autoplay/iframe contexts but it improves grant rates)

There are no manifest-level permission declarations on web. HTTPS is required — the skill detects localhost (allowed) vs other origins (must be HTTPS) and warns if the dev server is HTTP.

1.7 IncomingCall mounted at app root

<CometChatIncomingCall /> (additive mode) or a Service-Worker-driven web-push handler (standalone mode) must mount above the route boundary so calls fire on every page.

// app/layout.tsx (Next.js App Router) or App.tsx (Vite/CRA)
<CometChatProvider>
  <CometChatIncomingCall />   {/* renders nothing when no call active; listens app-wide */}
  <Routes>...</Routes>
</CometChatProvider>

Mounting it inside a route component means it disappears on navigation — calls only ring on the screen where it's mounted. That's the canonical "calls don't work" bug on web.

1.8 Init order — Chat init → Chat login → Calls init → Calls login (ENG-35708)

The order is load-bearing. Two crashes from real testers trace back to this:

• `CometChatCalls.init` before `CometChat.login` → calls integration broke. The Calls SDK reads context from the Chat SDK that only exists once a Chat session is established. Swapping init order silently fails or returns 401s on the first generateToken.
• Crash on `Start Call` when only the Calls SDK was initialized. No Chat SDK init at all → the ringing flow can't fire initiateCall because the Chat SDK isn't there.

The only correct order in additive mode (chat + calls):

CometChat.init(appId, settings)
  → CometChat.login(uid, authKey)        // OR loginWithAuthToken(token)
  → CometChatCalls.init({appId, region})
  → CometChatCalls.login(uid, apiKey)    // OR loginWithAuthToken(serverToken)

In standalone session-mode (product === "voice-video", no chat), use ONLY the Calls SDK — never call CometChat.init / CometChat.login at all. The kit's session-mode sample doesn't import the Chat SDK; matching that shape eliminates a class of "Chat init failed mid-meeting" failures.

1.9 Don't double-up call buttons (ENG-35708)

Two testers reported call buttons appearing twice on the message screen. Cause: the kit's <CometChatMessageHeader user={user} /> already renders <CometChatCallButtons> internally when a user prop is set (and the kit's default messages page mounts the header). Adding your own <CometChatCallButtons user={user} /> next to either of those produces a duplicate set.

Rule before emitting `<CometChatCallButtons>`:

1. Check whether the surrounding kit component already shows them. CometChatMessageHeader (any path that auto-renders the header) and the kit's default messages page include call buttons by default. (Note: there is no CometChatConversationsWithMessages composite in v6 — it was removed.)
2. If yes, do NOT add a second <CometChatCallButtons>. To swap appearance or behavior, use the kit's messageHeaderView slot or set the relevant hide* flag instead of adding another instance.
3. If no — you're on a custom screen that does not use those kit components — then <CometChatCallButtons user={user} /> is appropriate. Mount it once, beside the user-info block.

1.10 CometChatOngoingCall expects a callSettingsBuilder, NOT a built CallSettings (ENG-35708)

CallSettingsBuilder is not a bare export of either package — access it via the kit re-export: import { CometChatUIKitCalls } from "@cometchat/chat-uikit-react", then new CometChatUIKitCalls.CallSettingsBuilder(). The prop shape is the builder instance (not the built settings object). The agent emitted:

// ✗ Wrong — TypeScript error on the prop type
const callSettings = new CometChatUIKitCalls.CallSettingsBuilder().enableDefaultLayout(true).build();
<CometChatOngoingCall callSettingsBuilder={callSettings} />

The correct usage is:

// ✓ Right. Verified against the kit's CometChatOngoingCallProps (6.5.x):
//   sessionID: string            ← REQUIRED (non-optional) — omitting it TS-errors
//   callSettingsBuilder?: ...    ← OPTIONAL; the kit defaults to new CometChatUIKitCalls.CallSettingsBuilder()
// There is NO .setSessionID() on the builder — the session id is its OWN prop.
// The builder holds only configuration setters (enableDefaultLayout /
// setIsAudioOnlyCall / show*Button).
const callSettingsBuilder = new CometChatUIKitCalls.CallSettingsBuilder()
  .enableDefaultLayout(true)
  .setIsAudioOnlyCall(false);
<CometChatOngoingCall sessionID={sessionId} callSettingsBuilder={callSettingsBuilder} />

Prefer the additive path over a manual `<CometChatOngoingCall>` mount. Mounting <CometChatIncomingCall /> at the app root and letting the kit drive the Outgoing → Ongoing transition needs no sessionID plumbing and is the build-clean, recommended approach (§1.x). Reach for a manual <CometChatOngoingCall> only when you're building a custom call screen — and then sessionID is mandatory.

Why this shape: the kit composes the builder with internal listeners (call-end, error, recording state) before calling .build(). Pre-building forecloses that composition. Pass the builder; let the kit build.

⚠️ `callSettingsBuilder` is a different shape on different components (verified vs the v6 React kit source — do not assume one form): - <CometChatOngoingCall> → a builder instance (callSettingsBuilder={new CometChatUIKitCalls.CallSettingsBuilder()...}), prop typed typeof CometChatUIKitCalls.CallSettings. - <CometChatCallButtons> → a callback: callSettingsBuilder={(isAudioOnlyCall, user?, group?) => new CometChatUIKitCalls.CallSettingsBuilder()...}. - <CometChatIncomingCall> (and Outgoing) → a callback taking the call: callSettingsBuilder={(call) => new CometChatUIKitCalls.CallSettingsBuilder()...}. All three are optional — omit the prop and the kit uses its own default builder (the simplest correct path). Only the OngoingCall form takes a bare instance; passing an instance where a callback is expected is a TS error.

2. Setup

Install

Calls SDK v5.0.0 stable shipped but the npm latest dist-tag still points at v4.2.6 (legacy). Always pin to `@5` (or a specific `^5.0.0` version) — npm install @cometchat/calls-sdk-javascript (no tag) resolves to v4.2.6, which is the previous generation. @beta is also published but pins to an older 5.0.0-beta.2 — prefer @5 to get the latest stable 5.x.

# v5 stable (current — pulls 5.0.0 or newer 5.x)
npm install @cometchat/chat-sdk-javascript @cometchat/calls-sdk-javascript@5
# additive mode: @cometchat/chat-uikit-react is already installed

The kit (@cometchat/chat-uikit-react@^6.x) was built against the v4 calls API but Calls SDK v5 ships v4 deprecated-method shims that delegate to v5 implementations — so the kit's CometChatCallButtons / CometChatIncomingCall / CometChatOngoingCall keep working when you swap v4 for v5. Custom call surfaces should use v5 APIs directly.

Init order (web — v5)

// cometchat/init.ts
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCalls } from "@cometchat/calls-sdk-javascript";

let initialized = false;

export async function initCometChat() {
  if (initialized) return;

  // 1. Chat SDK init (signaling)
  const appSettings = new CometChat.AppSettingsBuilder()
    .subscribePresenceForAllUsers()
    .setRegion(import.meta.env.VITE_COMETCHAT_REGION)  // adjust for framework
    .build();
  await CometChat.init(import.meta.env.VITE_COMETCHAT_APP_ID, appSettings);

  // 2. Calls SDK init (WebRTC) — v5 takes a plain object and returns {success, error}
  const callsInit = await CometChatCalls.init({
    appId: import.meta.env.VITE_COMETCHAT_APP_ID,
    region: import.meta.env.VITE_COMETCHAT_REGION,
  });
  if (!callsInit?.success) {
    throw new Error(`CometChatCalls.init failed: ${JSON.stringify(callsInit?.error)}`);
  }

  initialized = true;
}

// After your existing CometChat.login(uid, apiKey) call, login the Calls SDK too.
// In v5 the Calls SDK has its own auth state; this step is mandatory.
export async function loginCometChat(uid: string) {
  await CometChat.login(uid, import.meta.env.VITE_COMETCHAT_AUTH_KEY);

  // v5 — Calls SDK login. ⚠ Only needed for CallWorkflow.directCalling or the
  // SDK-only/custom-WebRTC surface (see §1.4) — for the COMMON additive/default
  // ringing path you can OMIT this whole block (the kit rides the Chat SDK's
  // signaling). Shown here for completeness; harmless when included with a valid key.
  if (!CometChatCalls.getLoggedInUser()) {
    await CometChatCalls.login(uid, import.meta.env.VITE_COMETCHAT_API_KEY);
    // OR: await CometChatCalls.loginWithAuthToken(serverMintedToken);
  }
}

The module-level initialized flag prevents StrictMode double-init in React 18+ dev mode. The getLoggedInUser() guard prevents re-login on hot reload.

⚠️ Additive mode: the chat layer must init via `CometChatUIKit.init()`, not raw `CometChat.init()`. The example above shows CometChat.init() for the SDK-only path. But when you use the kit's call components (<CometChatCallButtons> / <CometChatIncomingCall> / <CometChatOngoingCall>), they read uiKitSettings that only `CometChatUIKit.init(new UIKitSettingsBuilder()…build())` sets — your cometchat-core setup already does this. Initializing the chat layer with raw CometChat.init() instead leaves the components logging `uiKitSettings not available` (non-fatal — calls still connect — but a real DX smell). In additive mode, keep CometChatUIKit.init() as your chat init and have this calls module ADD only CometChatCalls.init() + CometChatCalls.login() on top. (Verified by a two-user live call smoke 2026-06-04: with `CometChatUIKit.init()` the ring→accept→join flow runs with zero console errors; with raw `CometChat.init()` both sides log the warning.)

Framework-specific env prefixes (already covered by cometchat-core)

SSR safety

CometChat Calls SDK is browser-only — window, MediaStream, RTCPeerConnection, navigator.mediaDevices. Calls components must NOT render server-side:

• Next.js App Router: add "use client" to the file containing call components
• Next.js Pages Router: dynamic-import with ssr: false
• React Router: lazy + <Suspense> + if (typeof window === "undefined") return null guard in the component
• Astro: client:only="react" on the call component island

3. Components catalog

Calls SDK primitives — v5 (used in standalone or wherever you build custom UI)

v4 → v5 method mapping (the deprecated v4 method names below all still work in v5 as shims that delegate to v5 implementations — your kit's v6 code is unaffected):

See references/migration-v4-to-v5.md for the full migration guide.

UI Kit components (additive mode — @cometchat/chat-uikit-react)

In standalone mode, you can compose just <CometChatOngoingCall /> + <CometChatCallLogs /> from the UI Kit even without using CometChatConversations etc. — the kit's calls components don't depend on its conversation components.

4. Standalone integration

When product === "voice-video" and there is no existing chat UI integration.

Split by calling mode — these are two different shapes:

4a. Standalone — Session mode (meeting-room UX, no ringing)

Calls SDK ONLY. NO Chat SDK. Matches the upstream sample at calls-sdk-javascript-5/sample-apps/cometchat-calls-sample-app-react/. The skill scaffolds:

1. `cometchat/init.ts` — CometChatCalls.init({ appId, region, authKey }) ONLY. No CometChat.init, no CometChat.login. Pass authKey at init time so subsequent CometChatCalls.login(uid) calls need no second arg.
2. `cometchat/CometChatProvider.tsx` — Runs Calls SDK init on mount, exposes loggedInUser via CometChatCalls.getLoggedInUser(), gates children on success.
3. `pages/Home.tsx` — UID picker (dev mode) + "Start meeting" (mints UUID, navigates to /meet/:id) + "Join meeting" (paste sessionId).
4. `pages/CallRoom.tsx` — /meet/:sessionId route. Container is position: fixed; width: 100vw; height: 100vh. CometChatCalls.joinSession(token, {}, container) with empty settings. See references/call-session.md for the canonical pattern.
5. HTTPS check — warns if dev server is HTTP non-localhost.

Why no Chat SDK: session mode never touches the Chat SDK call entity. Initializing both SDKs adds two failure modes (Chat init, Chat login race) for zero benefit. The upstream sample confirms this — it never imports @cometchat/chat-sdk-javascript.

4b. Standalone — Ringing mode (CallButtons + Incoming/Outgoing/Ongoing kit components)

Dual-SDK: Chat SDK signaling channel + Calls SDK media channel. The skill scaffolds:

1. `cometchat/init.ts` — Chat SDK + Calls SDK init (sequential), module-level guard.
2. `cometchat/CometChatProvider.tsx` — React provider, runs init+login on mount, gates children on success.
3. `components/CallButton.tsx` — Voice + video buttons next to a user (your existing user listing / profile page).
4. `/calls` route or screen — Renders <CometChatCallLogs /> for history. (Path depends on framework — app/calls/page.tsx for Next.js App Router, routes/calls.tsx for React Router, etc.)
5. `OngoingCallView.tsx` — Custom WebRTC view OR delegates to <CometChatOngoingCall />. Implements rule 1.3 cleanup.
6. Provider mounts `<CometChatIncomingCall />` at the layout root (rule 1.7).
7. Optional Web Push — Service Worker registration + push subscription endpoint, if the user opts in.
8. HTTPS check — warns if dev server is HTTP non-localhost.

4c. SDK-only — without any UI Kit call components (ENG-35707)

When the user wants to build their own call UI (custom controls, a custom in-call screen) but still wants ringing semantics, they're on the SDK-only path: Chat SDK for signaling + Calls SDK for media, NO <CometChatCallButtons> / <CometChatOngoingCall> / <CometChatIncomingCall> from the UI Kit. The previous version of this skill was UI-Kit-first and these gotchas were silent. Cover them explicitly when you scaffold this shape.

#### Constants — two enums, same meaning, easy to confuse

These are NOT interchangeable. CometChat.CALL_TYPE.AUDIO (Chat SDK) ≠ CometChatCalls.constants.TYPE.VOICE (Calls SDK) even though they mean the same thing. Use the Chat SDK enum on the Call entity you pass to initiateCall; use the Calls SDK enum on SessionSettings.sessionType.

Note: CallSettingsBuilder has no setCallType(...) method — that lives on CallLogRequestBuilder (and takes 'video' | 'audio' for filtering call logs). The audio knob for a session is CallSettingsBuilder().setIsAudioOnlyCall(true), or sessionType: 'VOICE' in the SessionSettings object form. (Verified against the calls-sdk index.d.ts.)

#### Audio-only calls — setIsAudioOnlyCall(true) on CallSettingsBuilder

The audio-only knob lives on the Calls SDK's CallSettingsBuilder, not on the Chat SDK call entity. You set the Chat SDK call type to AUDIO for the ringing/signaling channel, and then ALSO set setIsAudioOnlyCall(true) on the call settings used for joinSession:

// joinSession's 2nd arg is a SessionSettings OBJECT (NOT the output of
// CallSettingsBuilder.build() — that's a CallSettings, accepted only by the
// deprecated startSession). The session is carried by the `token` (from
// generateToken(sessionId)); there is no sessionId/setSessionID in the settings.
// Voice-only: set sessionType: 'VOICE' (the object equivalent of the v4
// builder's setIsAudioOnlyCall(true)).
const settings = { sessionType: 'VOICE' };

const result = await CometChatCalls.joinSession(token, settings, containerRef.current);

Without sessionType: 'VOICE', voice calls still acquire the camera (it's just not rendered) — which trips the browser permission prompt and lights the camera indicator. Always pair CALL_TYPE.AUDIO (Chat) + sessionType: 'VOICE' in the join settings (Calls) for voice calls.

#### Container-mount timing — joinSession MUST fire after the container is in the DOM

This is the most painful SDK-only failure mode. The natural site to call joinSession is the call-listener event onOutgoingCallAccepted (caller side) or onIncomingCallReceived → user-accepts (receiver side). But those events fire BEFORE your in-call panel has rendered — the container <div ref={containerRef}> is still null. joinSession(token, settings, null) throws Container dimensions and number of tiles must be positive (or silently no-ops in some kit versions).

Pattern: drive the container via state and join in a `useEffect` that depends on both the call state AND the container ref.

function CallScreen() {
  const [phase, setPhase] = useState<"idle" | "joining" | "in-call">("idle");
  const [callToken, setCallToken] = useState<string | null>(null);
  const containerRef = useRef<HTMLDivElement>(null);

  // Step 1: register call listeners
  useEffect(() => {
    const listenerID = "call-screen-" + Date.now();
    CometChat.addCallListener(listenerID, new CometChat.CallListener({
      onOutgoingCallAccepted: async (call: any) => {
        // DO NOT call joinSession here — the container ref is still null.
        // Just flip the phase and let the effect below handle it.
        const tokenRes = await CometChatCalls.generateToken(call.getSessionId(), authToken);
        setCallToken(tokenRes.token);
        setPhase("in-call");
      },
      onIncomingCallReceived: (call: any) => { /* show your accept UI */ },
    }));
    return () => CometChat.removeCallListener(listenerID);
  }, []);

  // Step 2: when phase flips to "in-call" AND container is mounted, join
  useEffect(() => {
    if (phase !== "in-call" || !callToken || !containerRef.current) return;
    const container = containerRef.current;
    if (container.clientWidth === 0 || container.clientHeight === 0) return; // not laid out yet
    // session is carried by callToken (from generateToken). joinSession takes a
    // SessionSettings OBJECT — {} uses the default layout. (Do NOT pass
    // CallSettingsBuilder.build() here — that CallSettings type is for the
    // deprecated startSession, and is incompatible with joinSession.)
    CometChatCalls.joinSession(callToken, {}, container);
  }, [phase, callToken]);

  return (
    <>
      {phase === "in-call" && (
        <div ref={containerRef} style={{ position: "fixed", inset: 0, width: "100vw", height: "100vh" }} />
      )}
    </>
  );
}

The key idea: the call-listener handler doesn't call joinSession directly. It updates state. The effect that depends on phase AND the ref runs ONLY after React has committed the container <div> to the DOM. This is the same race as "modal <dialog> mounted before showModal()" — it's a React/DOM-timing issue, not a SDK bug.

#### Group calls vs 1:1 calls — defaults differ

• 1:1 calls use the ringing pattern: new CometChat.Call(receiverUid, CALL_TYPE.VIDEO, RECEIVER_TYPE.USER) → CometChat.initiateCall(call) → receiver gets onIncomingCallReceived. Default call type for a 1:1 video chat is video; for audio chat, audio.
• Group calls in the UI Kit go through a custom-message broadcast (CometChatCallButtons sends CustomMessage type="meeting"), not initiateCall. SDK-only groups: send your own custom message + CometChatCalls.joinSession with a shared sessionId — there is no "ring a group" primitive.
• Group call default is voice in the kit's CometChatCallButtons for groups; 1:1 default is video. If you're building custom buttons, replicate this — group calls are usually meeting-style (voice + screen share); 1:1s are usually video.

Cross-reference: cometchat-native-calls §3 documents the same group-call custom-message pattern for React Native (memory: [[project_group_calls_kit_semantic]]).

#### Container CSS — non-zero dimensions before joinSession

Already covered in the §⚠️ "Call container — must have non-zero dimensions" callout at the top, but it bears repeating in the SDK-only flow because there's no UI Kit component wrapping the container. Inline-render the container with position: fixed; inset: 0; width: 100vw; height: 100vh (full-screen overlay) OR display: flex; flex: 1; min-height: 600px (embedded). NEVER display: none + toggle — the container measures zero while hidden and joinSession throws.

5. Additive integration

When cometchat-core integration already exists. The skill:

1. Adds @cometchat/calls-sdk-javascript@5 to package.json (v5.0.0 stable — see Install section).
2. Patches cometchat/init.ts to call CometChatCalls.init({...}) after CometChat.init AND to call CometChatCalls.login(uid, apiKey) after CometChat.login (v5 — separate auth).
3. Mounts <CometChatIncomingCall /> at the layout root next to existing components (rule 1.7).
4. Adds <CometChatCallButtons user={user} /> inline on selected screens — usually inside <CometChatMessageHeader /> (the kit auto-renders it there if a user prop is set).
5. Adds a /calls route for <CometChatCallLogs /> if the user picked the "dedicated route" option.

6. Anti-patterns

1. Mounting `<CometChatIncomingCall />` inside a route component. Disappears on navigation. Mount above the route boundary in the layout (rule 1.7).
2. Initializing both SDKs in parallel. CometChatCalls.init requires the Chat SDK's app-id context; calling them with Promise.all causes intermittent "auth context null" errors. Sequence: chat init → calls init.
3. Skipping the `initialized` guard. React StrictMode renders effects twice in dev — without the guard, you get duplicate listeners and double-init warnings.
4. Forgetting `getTracks().forEach(t => t.stop())` on custom streams. Camera light stays on until tab close. Rule 1.3.
5. Embedding `<CometChatOngoingCall />` in an `<iframe>` without `allow="camera; microphone"`. Browsers silently deny getUserMedia. The skill detects iframe contexts and writes the allow list.
6. Calling `joinSession` (v5) before `CometChatCalls.login()` resolves. generateToken 401s — no Calls SDK auth state. Sequence: CometChatCalls.init → CometChatCalls.login → generateToken → joinSession.
7. Installing `@cometchat/calls-sdk-javascript` without a version pin. Resolves to v4.2.6 (the latest dist-tag) instead of v5.0.0. The kit's v4 deprecated-method shims live INSIDE v5 — picking up plain v4 means you don't get them. Always @5 (recommended) or pin a specific ^5.0.0 version. @beta is also valid but pins to an older 5.0.0-beta.2.
8. Running over HTTP (non-localhost). getUserMedia returns NotAllowedError. The skill warns; user must use HTTPS or localhost.

7. Verification checklist

Static:

• [ ] Both @cometchat/chat-sdk-javascript and @cometchat/calls-sdk-javascript@5 (v5 stable) in package.json
• [ ] CometChatCalls.login(uid, apiKey) is called after CometChat.login (v5 separate auth)
• [ ] Init order: chat init → calls init (sequential, not parallel)
• [ ] <CometChatIncomingCall /> mounted at layout root (additive mode)
• [ ] Cleanup path stops MediaStream tracks + ends Calls SDK session
• [ ] Framework-correct SSR guard ("use client" / ssr: false / client:only)
• [ ] Env vars use the framework-correct prefix
• [ ] Module-level initialized flag for StrictMode safety

Runtime (browser):

• [ ] Outgoing call connects, two-way audio + video
• [ ] Incoming call rings on a separate page within the same SPA
• [ ] Camera light off within 2 seconds of hangup
• [ ] Tab refresh during call cleanly disconnects (no orphaned session)
• [ ] HTTPS or localhost only — getUserMedia works
• [ ] Multi-tab: closing one tab doesn't end the call in another tab

8. Pointers

• references/virtual-background.md — blur / custom image / clear (web-only; native iOS/Android don't support it)
• cometchat-core — provider pattern, init guard, login order
• cometchat-components — full UI Kit catalog (additive mode)
• cometchat-{nextjs,react,react-router,astro}-patterns — framework-specific SSR guards, route placement
• cometchat-production — server-minted tokens, security
• cometchat-troubleshooting — common web failure modes (HTTPS, iframe permissions, StrictMode double-init)