Cometchat React Native V5 SDK

Ground truth: @cometchat/calls-sdk-react-native@5 + catalog rn-calls-v5.json (the closed symbol list — every CometChatCalls.* below exists in it). Official docs: /calls/react-native/** = v5 · Docs MCP. Fetch exact sessionSettings fields, event names and action 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-native-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-react-native@4) for call signaling — signatures fetched from docs via references/docs-map.md (§ "1:1 RINGING"). It does NOT depend on the React Native UI Kit.
• Prefer the UI Kit instead? If the app also wants chat and a prebuilt call UI, use cometchat-react-native-core + cometchat-react-native-calls — not this skill.

Use this skill when

"add calling from scratch / without the UI Kit", "standalone voice/video in React Native", "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-native-calls.

Prerequisites & install

npm install @cometchat/calls-sdk-react-native@5
# 6 REQUIRED peer deps — versions are pinned by the SDK; do not float them
npm install @react-native-async-storage/async-storage@^2.1.2 react-native-background-timer@^2.4.1 \
  react-native-performance@^5.1.2 react-native-svg@^15.12.0 react-native-url-polyfill@2.0.0 \
  react-native-webrtc@124.0.7

• 1:1 ringing additionally needs the Chat SDK for signaling: npm install @cometchat/chat-sdk-react-native@4
• iOS — cd ios && pod install && cd ... Add to ios/<App>/Info.plist:

  <key>NSCameraUsageDescription</key><string>Camera access is required for video calls</string>
  <key>NSMicrophoneUsageDescription</key><string>Microphone access is required for voice and video calls</string>

  Xcode → target → Signing & Capabilities → Background Modes → Audio, AirPlay, and Picture in Picture (+ Voice over IP for ringing — references/ringing-voip.md).
• Android — add to android/app/src/main/AndroidManifest.xml as <uses-permission android:name="android.permission.X" />: INTERNET · CAMERA · RECORD_AUDIO · MODIFY_AUDIO_SETTINGS · ACCESS_NETWORK_STATE · BLUETOOTH (add android:maxSdkVersion="30") · BLUETOOTH_CONNECT. API 23+ also requires a RUNTIME request (PermissionsAndroid.requestMultiple([CAMERA, RECORD_AUDIO]) or react-native-permissions) BEFORE starting a call. A manifest entry alone is not enough. A call that must survive backgrounding needs the FOREGROUND_SERVICE* family + WAKE_LOCK + POST_NOTIFICATIONS as well — references/ringing-voip.md § Part 2b.
• New Architecture — works on old arch, New Architecture and bridgeless with no extra setup; leave newArchEnabled as the app needs it. The SDK ships as a legacy native module and runs through RN's interop layer, so behaviour is identical on both.
• 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 (@3 pins the CLI major that matches the v5 skills). Mint auth tokens server-side for production; never ship the Auth Key. Rebuild the app after installing (npx react-native run-ios / run-android) — this is a native dependency, so Metro-only reload will not pick it up.

Init & login ordering (BAKED — invariant)

CometChatCalls.initFromSettings(...) (once, check the result) → CometChatCalls.login(uid, authKey) or loginWithAuthToken(token) → then generateToken / render / listeners. Nothing renders or joins before init+login resolve.

• DEFAULT to CometChatCalls.initFromSettings(settings) — the ai-agent / telemetry-attributed path (persists integrationSource="ai-agent"), parallel to the chat core (RULES.md §5). It is INTENTIONALLY undocumented (ai-agent-only, @nodoc — DOCS-BACKLOG F4/C1), so the CometChatSettings shape is baked in references/docs-map.md; pass it INLINE (no physical cometchat-settings.json file needed). The publicly-documented CometChatCalls.init({ appId, region }) is the FALLBACK only.
• Both init entry points return a RESULT OBJECT, not a rejecting promise — { success: false, error: {...} } | { success: true, error: null }. A bare await CometChatCalls.initFromSettings(s) that ignores .success silently continues on a validation failure and the call fails later with a confusing error. Always branch on .success.
• v5 authenticates itself. v4 borrowed the Chat SDK's auth token and passed it to generateToken; v5 has its own login/loginWithAuthToken and caches the token internally, so generateToken(sessionId) takes no auth token. Passing one is the v4 pattern.
• Coexisting with the Chat SDK / UI Kit? Log into the Chat SDK first, then share the session: const u = await CometChat.getLoggedinUser(); if (u) await CometChatCalls.loginWithAuthToken(u.getAuthToken());. The token is a User method (getAuthToken()) — there is NO top-level CometChat.getUserAuthToken() on the RN Chat SDK (that name is on the Calls SDK; the migration doc's v4 tab shows it wrongly — DOCS-BACKLOG). Full note: references/docs-map.md § 1:1 RINGING.

Two build modes (BAKED — the router picks one)

• Meet-style (session room) — Calls SDK ONLY. Everyone who renders the same sessionId lands in the same call: generateToken(sessionId) → render <CometChatCalls.Component>. No ringing.
• 1:1 ringing — Chat SDK signals, Calls SDK carries media: CometChat.initiateCall → peer CallListener.onIncomingCallReceived → acceptCall/rejectCall → CometChatCalls.generateToken(call.getSessionId()) → render the Component. Fetch Chat-SDK signatures via references/docs-map.md § "1:1 RINGING".

  ⚠️ RINGING ALWAYS INCLUDES VoIP — build both halves, never ask. Signaling alone is a websocket event: it rings the callee only while their app is open, so backgrounded or killed they get nothing and the call times out (45s). Half a feature. Whenever ringing is chosen, references/ringing-voip.md is REQUIRED — emit the native VoIP setup in the SAME build and name the steps that are the user's (VoIP cert, Firebase, Xcode capabilities). Meet-style has no ringing and needs none of it.

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.getUserAuthToken · CometChatCalls.isUserLoggedIn · CometChatCalls.addLoginListener / removeLoginListener
• Session: CometChatCalls.generateToken · CometChatCalls.Component (the React component you RENDER to join — there is no joinSession on React Native) · CometChatCalls.leaveSession · CometChatCalls.endSessionForAll
• Events: CometChatCalls.addEventListener(eventName, cb, { signal? }) → unsubscribe() (event names: FETCH the full list from /calls/react-native/events)
• In-call actions — ⚠️ for CUSTOM controls ONLY; the Component 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 · switchCamera · setLayout · startRecording/stopRecording/toggleRecording · startStreaming/stopStreaming · startTranscription/stopTranscription · raiseHand/lowerHand/toggleHand · pinParticipant/unpinParticipant · muteParticipant · pauseParticipantVideo · showParticipantList/hideParticipantList/toggleParticipantList · setChatButtonUnreadCount
• Audio routing (RN-only): CometChatCalls.setAudioMode · CometChatCalls.AUDIO_MODE
• Picture-in-picture (RN-only): CometChatCalls.enablePictureInPictureLayout / disablePictureInPictureLayout
• Call logs: the history read is the Calls SDK CometChatCalls.CallLogRequestBuilder (verified against installed @cometchat/calls-sdk-react-native@5, 2026-09-10) — new CometChatCalls.CallLogRequestBuilder().setLimit(n).setAuthToken(CometChatCalls.getUserAuthToken() ?? "").build() → fetchNext(): Promise<CallLog[]> — every fetchNext() needs .setAuthToken(...) (no auto fallback; it rejects "Auth Token is required"). There is NO CometChat.CallLogRequestBuilder on the Chat SDK (@cometchat/chat-sdk-react-native, any version) — do not emit it. CometChatCalls.CallLog is the log model. For the transcript opt-in add .setHasTranscriptions(true) (filters to transcribed calls and attaches transcripts) — same token. Paginated history is the read — there is no working single-call-detail method (see deprecated note).
• Transcription: CometChatCalls.Transcription · CometChatCalls.TranscriptRequestBuilder · Transcript

Deprecated v5 compat surface — do NOT emit: CallSettingsBuilder, CallAppSettingsBuilder, OngoingCallListener, startSession, endSession, switchToVideoCall, getCallDetails (a @deprecated/unsupported void NO-OP on the v5 class — the functional Promise<CallLog[]> form is only on the v4-compat class; use CallLogRequestBuilder.fetchNext()). They still run (v5 is a drop-in for v4) but are the OLD API, and v5-only events never reach an OngoingCallListener. Use plain settings + addEventListener + leaveSession. Not on React Native at all (present on web — emitting them is a hallucination): joinSession, startScreenSharing/stopScreenSharing, virtual-background methods, audio/video device enumeration (getAudioInputDevices &c.). A symbol is real iff it's in rn-calls-v5.json — confirm THERE, then fetch its signature from references/docs-map.md.

Listener lifecycle (BAKED)

addEventListener RETURNS an unsubscribe function AND accepts { signal }. Prefer one AbortController per screen: pass signal to every listener and call controller.abort() in the effect cleanup — one teardown, no leaks. Register listeners BEFORE the Component mounts, and call CometChatCalls.leaveSession() on unmount. Never leak.

CometChatCalls is a SINGLETON with ONE active session. Mount exactly one Component. Every action (leaveSession, muteAudio, setLayout, …) takes no session id — it always targets the active session. To move to another call: leaveSession() → await onSessionLeft → generateToken(next) → re-render with the new token.