Cometchat JS V5 SDK

Ground truth: @cometchat/calls-sdk-javascript@5 + catalog web-calls-v5.json (the closed symbol list — every CometChatCalls.* below exists in it). Official docs: /calls/javascript/** = v5 · Docs MCP. Fetch exact SessionSettings fields, event names, and action-method signatures from the docs (references/docs-map.md) — never memory. APPEND to the user's app — additive wiring only (RULES.md). This is the HEADLESS path (no UI Kit); for the prebuilt drop-in call UI use cometchat-react-v7-calls instead.

Companion skills (read first)

• Standalone/headless entry — this skill owns its own package (the Calls SDK) and has no -core sibling; it is self-contained for meet-style calling.
• For 1:1 RINGING only it also drives the Chat SDK (@cometchat/chat-sdk-javascript@4) for call signaling — signatures fetched from docs via references/docs-map.md (§ "1:1 RINGING"). It does NOT depend on the React UI Kit.
• Prefer the UI Kit instead? If the app also wants chat and a prebuilt call UI, use cometchat-react-v7-core + cometchat-react-v7-calls — not this skill.

Use this skill when

"add calling from scratch / without the UI Kit", "standalone voice/video", "build my own call screen", "headless calls SDK", "meeting-room join by session id", "one-on-one ringing call". Precondition: the caller chose the from-scratch / standalone path (the "add calling" router asks this). If they want the prebuilt call UI, route to cometchat-react-v7-calls.

Prerequisites & install

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

• 1:1 ringing additionally needs the Chat SDK for signaling:

  npm install @cometchat/chat-sdk-javascript@4

• Credentials/env: App ID · Region · Auth Key (dev only). To fetch from the dashboard, load the CLI on demand — npx @cometchat/skills-cli@3 auth login → provision use --app-id <id> --json (writes .cometchat/config.json; @3 pins the CLI major that matches the v5 skills). Or paste manually from Dashboard → Credentials. Mint auth tokens server-side for production; never ship the Auth Key. HTTPS (or localhost) is required for camera/mic (getUserMedia).

Init & login ordering (BAKED — invariant)

CometChatCalls.init(...) (once, resolve first) → CometChatCalls.login(uid, authKey) or loginWithAuthToken(token) → then generateToken / joinSession / listeners. Nothing renders/joins before init+login resolve.

• DEFAULT to CometChatCalls.initFromSettings(settings) — the ai-agent / telemetry-attributed path (persists integrationSource="ai-agent"), parallel to how the chat core inits via CometChatUIKit.initFromSettings / CometChat.initFromSettings (RULES §5). It is INTENTIONALLY undocumented — ai-agent-only (@nodoc, same posture as CometChatUIKit.initFromSettings — DOCS-BACKLOG F4/C1) — so the settings-object shape is baked in references/docs-map.md; pass it INLINE (no physical cometchat-settings.json file required), never fetched from /calls/javascript/setup. The publicly-documented CometChatCalls.init({ appId, region }) is the FALLBACK only (a non-skills / doc-following context).
• Coexisting with the Chat SDK / UI Kit? Their login() can re-init the Calls SDK with only appId/region and wipe custom hosts — re-run your calls init after their login, before CometChatCalls.login.

Two build modes (BAKED — the router picks one)

• Meet-style (session room) — Calls SDK ONLY. Everyone who joins the same sessionId lands in the same call: generateToken(sessionId) → joinSession(token, sessionSettings, containerEl). No ringing. This is the /calls/javascript/react-integration flow.
• 1:1 ringing — Chat SDK signals, Calls SDK carries media: CometChat.initiateCall → peer CallListener.onIncomingCallReceived → acceptCall/rejectCall → CometChatCalls.generateToken(call.getSessionId()) → joinSession(...). Fetch Chat-SDK signatures via references/docs-map.md § "1:1 RINGING".

SDK method map (BAKED closed list — from the catalog; signatures → FETCH from docs)

• Lifecycle: CometChatCalls.init · CometChatCalls.initFromSettings · CometChatCalls.login · CometChatCalls.loginWithAuthToken · CometChatCalls.logout · CometChatCalls.getLoggedInUser · CometChatCalls.isUserLoggedIn
• Session: CometChatCalls.generateToken · CometChatCalls.joinSession · CometChatCalls.leaveSession (startSession is deprecated → use joinSession)
• Events: CometChatCalls.addEventListener(eventName, cb, { signal? }) → unsubscribe() (event names: FETCH the full list from /calls/javascript/events)
• In-call actions — ⚠️ for CUSTOM controls ONLY; the default joinSession UI already renders all of these (see the first pitfall). Only reach for them when the user EXPLICITLY asks to replace the built-in controls: muteAudio/unmuteAudio/toggleAudio · pauseVideo/resumeVideo/toggleVideo · setLayout · startRecording/stopRecording · startScreenSharing/stopScreenSharing · raiseHand/lowerHand · switchCamera · pinParticipant/unpinParticipant · showParticipantList/hideParticipantList
• Devices: getAudioInputDevices · getAudioOutputDevices · getVideoInputDevices · getCurrent*Device
• Call logs: CometChatCalls.CallLogRequestBuilder → fetchNext() (paginated; shape → docs)
• Constants: CometChatCalls.constants.LAYOUT (TILE/SIDEBAR/SPOTLIGHT) · .TYPE (VOICE/VIDEO) · .CAMERA_FACING

This map is a curated highlight, NOT the full surface — the AUTHORITATIVE closed list is the web-calls-v5.json catalog (83 symbols; it also carries toggleHand/toggleParticipantList/endSessionForAll/muteParticipant/pauseParticipantVideo/setChatButtonUnreadCount/switchToVideoCall, device setters (setAudioInputDevice…), the virtual-background methods, startStreaming/stopStreaming (RTMP live-streaming — with streamUrl/streamKey/hideStreamingButton in SessionSettings; neither the SKILL map above nor the /calls/javascript/actions doc foregrounds it, but it is real), startTranscription/stopTranscription (v5.0.5 — see /calls/javascript/transcription), and TranscriptRequestBuilder, among others). A symbol is real iff it's in the catalog — confirm THERE (not just this map), then fetch its exact signature/params from the docs page in references/docs-map.md.

Listener lifecycle (BAKED)

addEventListener RETURNS an unsubscribe function — collect them and call every one on teardown (React: in the effect cleanup), and CometChatCalls.leaveSession() on unmount. Register listeners BEFORE joinSession. Never leak. You can also pass an AbortSignal via the { signal } option for bulk teardown.

Least-code recipe (meet-style, framework-agnostic)

// STRICT-TS-CLEAN: type the settings with the EXPORTED SessionSettings, narrow region.
import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
import type { SessionSettings } from "@cometchat/calls-sdk-javascript"; // exported; SessionType/Layout are NOT

1. await CometChatCalls.initFromSettings({ appId, region: region as "us"|"eu"|"in", credentials: { authKey: AUTH_KEY }, callsSDK: {}, chatSDK: {}, uiKit: {} }) // ai-agent telemetry default (integrationSource="ai-agent"); init({appId,region}) is the public-doc fallback
2. await CometChatCalls.login(uid, AUTH_KEY)               // or loginWithAuthToken(token)
3. const { token } = await CometChatCalls.generateToken(sessionId)
4. const unsub = CometChatCalls.addEventListener("onSessionLeft", () => cleanup())
5. const callSettings: SessionSettings = { sessionType: "VIDEO", layout: "TILE" } // annotate → literals narrow
   await CometChatCalls.joinSession(token, callSettings, containerEl)
6. // NO control buttons needed — joinSession's UI ALREADY renders mute/video/screen-share/raise-hand/leave.
7. // teardown → unsub(); CometChatCalls.leaveSession()

The containerEl MUST have real dimensions — the SDK renders its call surface into it. Fetch the full SessionSettings field list from /calls/javascript/session-settings. (In plain JS drop the annotations; the doc pages show that JS form.)

Framework notes (same SDK, per-framework glue)

The recipe above is framework-agnostic; the only per-framework part is WHERE you register listeners / mount the container / tear down. Verified live on React and Angular.

• React: provider or component — init via CometChatCalls.initFromSettings(...) (the telemetry-attributed default — integrationSource="ai-agent"; init({appId,region}) is the public-doc fallback), then register listeners + joinSession in a useEffect; teardown in the effect cleanup (call every unsubscribe + leaveSession). Recipe: /calls/javascript/react-integration.
• Angular: a DI service wrapping CometChatCalls (init via CometChatCalls.initFromSettings(...) — the telemetry-attributed default (integrationSource="ai-agent"; init({appId,region}) is the public-doc fallback) → login, generateToken, typed joinSession, leaveSession; expose readiness via an RxJS BehaviorSubject) + a component with a sized @ViewChild('callContainer') ElementRef container; register listeners BEFORE joinSession; teardown in ngOnDestroy (unsubscribe all + leaveSession). Recipe: /calls/javascript/angular-integration — but ⚠️ THREE things to override:
  • (a) its example wires external Mute/Video/Leave buttons — IGNORE them (pitfall #1: joinSession's UI already has the controls);
  • (b) it targets legacy @NgModule/app.module.ts — a modern ng new is standalone (bootstrapApplication + app.config.ts, class App), so use the standalone variant;
  • (c) ⚠️ NgZone / change detection (the silent dead-state). CometChat SDK callbacks — event listeners AND the login/generateToken/joinSession promise resolutions — fire OUTSIDE Angular's zone, so any component state you set inside them won't trigger change detection (symptom: readiness/call buttons silently never enable, even though the SDK succeeded). Fix: drive the template off your BehaviorSubject via the async pipe, AND/OR wrap state writes in this.zone.run(() => …) (inject NgZone) or call ChangeDetectorRef.detectChanges(). Not optional — the app looks broken without it.