Cometchat iOS Calls

Companion skills (read first)

• cometchat-ios-core owns setup and the chat surface. This skill ADDS calling. Note core ALREADY links CometChatCallsSDK at exactly 5.0.3 — on 5.1.22 (as since 5.1.19) the kit's interface imports it, so it is required even for chat-only builds. Do not add it twice or at a different version.

Use this skill when

"add voice/video calling", "show an incoming call screen", "add call history".

Calls has its OWN login — the UI Kit's login is not enough

CometChatUIKit.login(uid:) does NOT authenticate the Calls SDK. Built without the bootstrap below, CometChatCallLogs shows "Oops! Looks like something went wrong" — its request goes out with an EMPTY authToken (measured on 5.1.19/5.0.3). No error points at the cause. After the UI Kit login succeeds, run:

// DEFAULT — the ai-agent / telemetry-attributed init (persists integrationSource="ai-agent").
// Takes NO settings argument: it reads the SAME bundled cometchat-settings.json the core skill
// already ships (Copy Bundle Resources) — do not build a second settings object.
_ = CometChatCalls.initFromSettings(onSuccess: { _ in
    guard let token = CometChat.getUserAuthToken() else { return }
    CometChatCalls.login(authToken: token,
                         onSuccess: { _ in /* calls surfaces are now live */ },
                         onError:   { error in debugPrint("calls login:", error.errorDescription) })
}, onError: { error in debugPrint("calls init:", error?.errorDescription ?? "nil") })

⚠️ Init the Calls SDK via CometChatCalls.initFromSettings, NOT the classic CometChatCalls(callsAppSettings: CallAppSettingsBuilder()…) builder — that path attributes the app to "manual" and loses the ai-agent telemetry (RULES §5 / AUDIT-175, the SAME rule the headless cometchat-ios-v5-sdk follows). The builder init is the FALLBACK ONLY, for an app that does not bundle cometchat-settings.json:

// FALLBACK — only when no cometchat-settings.json is bundled. Loses ai-agent attribution.
let callSettings = CallAppSettingsBuilder().set(appID: appID).set(region: region).build()
_ = CometChatCalls(callsAppSettings: callSettings, onSuccess: { _ in /* … login as above … */ },
                   onError: { error in debugPrint("calls init:", error?.errorDescription ?? "nil") })

Never do both — a builder init AFTER initFromSettings re-attributes the app to "manual". initFromSettings fails SETTINGS_FILE_NOT_FOUND if the file is not in Copy Bundle Resources — the core skill already adds it for chat, so a UI-Kit app that shipped chat first already satisfies this.

The docs' calling-integration page says linking the SDK is enough; it is not — that gap is logged for the docs. Chat-only apps skip all of this (they link the Calls SDK purely to satisfy 5.1.19's import — see the core skill's install notes).

The five components

CometChatCallLogs callbacks are Any-typed — cast before touching anything. Unlike every other list component, five of its setters hand back untyped values and will not compile if you use them directly: set(onItemClick:) → (_ callLog: Any) · set(onCallButtonClicked:) → (Any) · set(options:) → (_ callLog: Any) · set(onLoad:) → ([Any]) · set(onError:) → (_ error: Any), not CometChatException like everywhere else.

logs.set(onItemClick: { callLog in
    guard let log = callLog as? CallLog else { return }   // NOT `as? Call` — that cast FAILS at
    …  // runtime and makes the tap a silent no-op (measured: RUNTIME TYPE = CallLog).
    // CallLog exposes status, type, mode, initiator, receiver — not the Call spellings
    // (callStatus/callType/callInitiator/callReceiver). CallLog is a Calls-SDK type.
})
logs.set(onError: { error in
    // The value is the CALLS SDK's exception type — casting to the chat SDK's
    // CometChatException fails and prints nothing useful (measured).
    debugPrint((error as? CometChatCallException)?.errorDescription ?? "\(error)")
})

sessionID vs sessionId — the same concept, spelled two ways. The SDK's Call exposes sessionID (capital), while the kit's CometChatOngoingCall takes set(sessionId:) (lowercase). Reading a log and starting a call in the same function means using both spellings; neither compiles in the other's place.

Voice/video click handlers on CometChatCallButtons are properties: callButtons.onVoiceCallClick = { user, group in … }, onVideoCallClick likewise. And it is set(callSettingsBuilder:) — plural "Settings".

@MainActor if you construct these in a factory. Inside a UIViewController this wiring is free (already main-actor). But if you wrap it in a standalone factory/enum/static method, mark that context @MainActor — the components' setters are main-actor-isolated. CometChatOutgoingCall is the strictest: unlike CometChatIncomingCall/CometChatCallButtons it carries no @preconcurrency, so under Swift 5 its set(call:)/set(onCancelClick:) are a HARD ERROR from a nonisolated context ("call to main actor-isolated instance method … in a synchronous nonisolated context"), not just a warning. (Same rule as cometchat-ios-core's @MainActor-factory note.)

// Minimum voice-video-calls wiring — all five components (inside a @MainActor context, e.g. a UIViewController)
let callButtons = CometChatCallButtons(width: 180, height: 40)
callButtons.set(user: user)          // or .set(group:) for a group call
callButtons.set(controller: self)
callButtons.onVoiceCallClick = { user, group in /* initiate voice call */ }
callButtons.onVideoCallClick = { user, group in /* initiate video call */ }

// Present incoming call over any screen via a global app-level listener
let incoming = CometChatIncomingCall()
incoming.set(call: incomingCall)
// accept/cancel closures are TWO-arg: (call: Call?, controller: UIViewController?). A one-arg
// `{ call in … }` does NOT compile ("expects 2 arguments, but 1 was used").
incoming.set(onAcceptClick: { call, _ in /* push CometChatOngoingCall */ })
incoming.set(onCancelClick: { call, _ in self.dismiss(animated: true) })

let outgoing = CometChatOutgoingCall()
outgoing.set(call: pendingCall)
outgoing.set(onCancelClick: { call, _ in self.dismiss(animated: true) })

let ongoing = CometChatOngoingCall()
// `Call.sessionID` (uppercase D, SDK) is OPTIONAL (String?); `set(sessionId:)` (lowercase d, kit)
// wants a non-optional String — so GUARD it. Passing the optional directly does not compile.
if let sid = pendingCall.sessionID { ongoing.set(sessionId: sid) }

let logs = CometChatCallLogs()
// NOTE: CometChatCallLogs has NO `set(controller:)` — present/push it like any UIViewController
// (e.g. UINavigationController(rootViewController: logs)). Its only setters are the Any-typed
// callbacks below plus set(callRequestBuilder:).
logs.set(onItemClick: { callLog in guard let log = callLog as? CallLog else { return } /* … */ })