Cometchat iOS V5 SDK

Ground truth: CometChatCallsSDK v5 + catalog ios-calls-v5.json (the closed symbol list — every type below is in it). Official docs: /calls/ios/** = v5 · Docs MCP. Fetch exact SessionSettings fields, event names and signatures from the docs (references/docs-map.md) — never memory. ⚠️ Twelve doc pages contain symbols that DO NOT COMPILE — see "Doc corrections" below; prefer THIS skill's names over the page's. APPEND to the user's app — additive wiring only.

Companion skills (read first)

• Standalone/headless entry — owns its own package (the Calls SDK), no -core sibling, never depends on the iOS UI Kit. 1:1 ringing additionally drives the Chat SDK (CometChatSDK v4) for signaling.
• App wants chat too, or the prebuilt call UI? cometchat-ios-core + cometchat-ios-calls — not this skill.

Use this skill when

"add calling from scratch / without the UI Kit", "standalone voice/video on iOS", "build my own call screen", "headless calls SDK", "meeting-room join by session id", "one-on-one ringing".

ASK FIRST (BAKED) — two choices, and NOTHING upstream asks them

Ask whichever the request has not already settled, then WAIT. Never infer from silence — each answer means a different SDK set and a different screen.

1. Prebuilt call UI, or build your own? Prebuilt (drop-in, themeable) → STOP, route to cometchat-ios-calls. Build your own → continue here.
2. Meet-style room, or 1:1 ringing? Room — everyone joining the same session id lands in one call; Calls SDK only. Ringing — you call a specific user and their device rings; adds CometChatSDK v4 for signaling (signatures: references/docs-map.md § "1:1 RINGING"), plus CometChatPushNotifications to ring while the app is backgrounded/closed.

Only EXPLICIT wording settles a question — "from scratch"/"my own call screen" → 1, "ringing"/"call a user" → 2. "Add calling to my iOS app" settles NEITHER — ask both.

Prerequisites & install

Swift Package Manager only — never CocoaPods, even if a Podfile exists (same rule as cometchat-ios-core: CocoaPods distribution is winding down; a Podfile is a detection signal, not an instruction). In Xcode: File → Add Package Dependencies, URL:

https://github.com/cometchat/calls-sdk-ios

⚠️ The docs print github.com/cometchat/cometchat-calls-sdk-ios — that repo 404s. Use the URL above. The package vends ONE product, CometChatCallsSDK, which bundles WebRTC as a second binary target — do not add WebRTC separately.

1:1 ringing additionally needs the Chat SDK (CometChatSDK v4) for signaling — add it as a second SPM package: URL https://github.com/cometchat/chat-sdk-ios (product CometChatSDK, verified against 4.1.7). Without it the import CometChatSDK on the ringing path does not resolve. (Meet-style / room-only does NOT need it.)

Info.plist — REQUIRED or the call dies on first permission prompt: NSCameraUsageDescription + NSMicrophoneUsageDescription. For calls that survive backgrounding, add Background Modes → Audio, AirPlay and Picture in Picture (+ Voice over IP if you use VoIP push).

Credentials: App ID · Region · Auth Key (dev only). 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). Already have App ID / Region / Auth Key? Just paste them. Mint auth tokens server-side for production; never ship the Auth Key.

Init & login ordering (BAKED — invariant)

Init (once, must succeed) → CometChatCalls.login(...) → then generateToken / joinSession / listeners. Nothing joins before init+login resolve.

• DEFAULT to CometChatCalls.initFromSettings(onSuccess:onError:) — the ai-agent / telemetry-attributed path (persists integrationSource="ai-agent"). It takes no settings argument: it reads a physical cometchat-settings.json from Bundle.main (root appId + region; optional callsSDK → host/adminHost/clientHost/callsHost). The file MUST be in the target's Copy Bundle Resources or init fails SETTINGS_FILE_NOT_FOUND. It is intentionally undocumented (ai-agent-only) — the settings shape is baked in references/docs-map.md.
• Fallback (public-doc path): CallAppSettingsBuilder().set(appID:).set(region:).build() → CometChatCalls(callsAppSettings:onSuccess:onError:). ⚠️ Use set(appID:)/set(region:) — the setAppId/setRegion/setHost spellings the docs use are deprecated in 5.0.4.
• ⚠️ Never do both. A direct builder init AFTER initFromSettings re-attributes the app to "manual" and the ai-agent telemetry is lost.

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

• Lifecycle: CometChatCalls.initFromSettings · CometChatCalls(callsAppSettings:) · CallAppSettingsBuilder · CometChatCalls.login (UID+authKey / UID+apiKey / authToken) · logout · getLoggedInUser → CallsUser
• Session: CometChatCalls.generateToken · CometChatCalls.joinSession · CometChatCalls.sessionSettingsBuilder · SessionSettingsBuilder → SessionSettingsBuilder.SessionSettings (NESTED — that is the type joinSession(callSetting:) takes)
• ⚠️ TWO join paths, both real in 5.0.4 — pick one: generateToken(sessionID:) → joinSession(callToken:callSetting:container:), or joinSession(sessionID:callSetting:container:) directly.
• In-call actions — on CallSession.shared, for CUSTOM controls ONLY (the default surface already renders them; see pitfall #1): leaveSession · muteAudio/unmuteAudio · pauseVideo/resumeVideo · setLayout · setAudioMode · switchCamera · raiseHand/lowerHand · startRecording/stopRecording · startTranscription/stopTranscription · startStreaming/stopStreaming · pinParticipant/unpinParticipant · muteParticipant · pauseParticipantVideo · enablePictureInPictureLayout/disablePictureInPictureLayout · isCallSessionActive
• Listeners (add on CallSession.shared, remove on teardown): SessionStatusListener · MediaEventsListener · ParticipantEventListener · LayoutListener · ButtonClickListener · clearAllListeners
• Call logs: CallLogsBuilder → CallLogsRequest → CallLog (+ CallUser/CallGroup/CallEntity/CallStatus/CallCategory/CallDirection)
• Enums: AudioMode (.speaker/.earpiece/.bluetooth/.headphones) · SessionType (.video/.voice) · LayoutType (.tile/.spotlight/.sidebar) · CameraFacing (.FRONT/.REAR — UPPERCASE, the ONE Calls-SDK enum that breaks the lowercase convention; .front/.rear fail to compile, and the docs' .BACK does NOT exist — see Doc corrections)

This map is a curated highlight, NOT the full surface — the AUTHORITATIVE closed list is the ios-calls-v5.json catalog (60 symbols). A symbol is real iff it's in the catalog — confirm THERE, then fetch its exact signature from the docs page in references/docs-map.md.

Listener lifecycle (BAKED)

Register listeners on CallSession.shared BEFORE joining; remove each one (or clearAllListeners()) on teardown, and call CallSession.shared.leaveSession() when the screen goes away. For ringing also CometChat.removeCallListener(<id>). Never leak.

The listener contract (all five, verified in the 5.0.4 interface):

• Every listener protocol is @objc and EVERY member is optional. Implement ONLY the callbacks you need — do NOT stub the rest. A name that is NOT in the protocol also compiles, then silently never fires — copy callback names from the events page / references/docs-map.md, never by analogy.
• Because they are @objc, the conforming type MUST be a class inheriting NSObject.
• Exact add/remove pairs on CallSession.shared — the names are NOT in the catalog (it is types-only), so use these:

• ButtonClickListener callbacks fire BEFORE the SDK's own action, and do NOT suppress it. Reacting to onLeaveSessionButtonClicked must NOT also call leaveSession() — the SDK is already leaving; doing both double-leaves.
• Participant has EXACTLY 12 fields, all Optional: uid · name · avatar · mid · state · isJoined · joinedAt · leftAt · deviceID · totalAudioMinutes · totalVideoMinutes · totalDurationInMinutes. Identity is uid (String? — unwrap before passing to muteParticipant(participantId:)), never name.
• ⚠️ The docs use SIX Participant fields that DO NOT EXIST — pid, isPinned, isAudioMuted, isVideoPaused, isPresenting, raisedHandTimestamp. Copying any of them fails to compile. pid → use uid; the five state flags have no field at all — track that state yourself from the ParticipantEventListener callbacks (onParticipantAudioMuted/Unmuted, onParticipantHandRaised/Lowered, onParticipantStarted/StoppedScreenShare).

Least-code recipe (meet-style — ORDER, not signatures)

// Fetch every signature/field from references/docs-map.md. This is the ORDER, which is the part that bites.
import UIKit
import CometChatCallsSDK

1. CometChatCalls.initFromSettings(onSuccess:onError:)   // ai-agent default; reads bundled cometchat-settings.json
2. CometChatCalls.login(UID:authKey:onSuccess:onError:)   // or login(authToken:) in production
3. let settings = CometChatCalls.sessionSettingsBuilder.setSessionType(.video).build()   // NOT .setType — see Doc corrections
4. CallSession.shared.addSessionStatusListener(self)      // register BEFORE joining
5. CometChatCalls.joinSession(sessionID:callSetting:container:onSuccess:onError:)  // container = a UIView with REAL bounds
   //   or: generateToken(sessionID:) -> joinSession(callToken:callSetting:container:)
6. // NO control buttons needed — the joined surface ALREADY renders mute/video/leave.
7. // teardown -> CallSession.shared.clearAllListeners(); CallSession.shared.leaveSession()

The container MUST have real bounds — a zero-frame view renders invisibly. In SwiftUI wrap it with UIViewRepresentable.

VoIP call notifications (SEPARATE package — CometChatPushNotifications)

Ringing a user whose app is backgrounded or terminated is NOT the Calls SDK's job. It is CometChatPushNotifications 1.0.0 — a different package. Do not hand-roll it.

• Install: SPM https://github.com/cometchat/push-notifications-sdk-ios @ 1.0.0 (product CometChatPushNotificationsSwift). Its Package.swift declares NO dependencies, yet the binary imports CometChatSDK + CometChatCallsSDK — the app must ALSO have both packages above (chat-sdk-ios + calls-sdk-ios) or the build fails. import CometChatPushNotificationsSwift — the module name differs from the class name; importing CometChatPushNotifications does not compile.
• Three steps, nothing more:
  1. after CometChat.init: CometChatPushNotifications.shared.initialize(config: .init(providerId:)) then set .delegate
  2. in AppDelegate: forward registerDeviceToken(_:) (+ handleRegistrationFailure(_:))
  3. implement CometChatPushNotificationsDelegate — every method is optional; the ones that matter are presentCallScreen(for:sessionId:) and onCallCleanupComplete()
• NEVER emit a PKPushRegistryDelegate or a CXProviderDelegate. The SDK owns both. Writing either is the #1 mistake here — it fights the SDK for the same callbacks.
• Cold start: call CometChatPushNotifications.shared.notifyCallsSDKReady() from the login success — NOT init success. It only lifts the buffer; it does not check that anyone is logged in, so releasing at init hands presentCallScreen an unauthenticated session and the joinSession after it fails on auth. (A 3s safety timeout fires the buffered call anyway, so a slow login can still present early — do not assume a live session in the call screen.)
• The call is ALREADY accepted when presentCallScreen fires — present UI and join; do not accept again.
• Prerequisites (state them, they are not code): an APNs VoIP provider in the dashboard, the Push Notifications + Background Modes (Voice over IP, Remote notifications) capabilities, and a PHYSICAL DEVICE — VoIP pushes are never delivered to the Simulator.
• ForegroundCallPresentation = .callKit (default) · .inApp (CometChatIncomingCallView, styled via CometChatIncomingCallStyle) · .none (present your own).

Callback shapes differ PER API and ?. on a non-optional does not compile — login/logout hand you a NON-optional CometChatCallException; initFromSettings/generateToken/joinSession hand you an Optional. Exact table + isCallSessionActive() arity: references/docs-map.md.