{/* Joining overlay */} {isJoining && (

Joining call...

)} {/* Call controls */} {isJoined && (

)} ); }; export default CallPage; ``` ### Step 5: Create the Home Page Create a home page where users can enter a session ID and join a call: ```tsx theme={null} // src/pages/Home.tsx import { useState } from "react"; import { IonContent, IonPage, IonHeader, IonToolbar, IonTitle, IonItem, IonLabel, IonInput, IonButton, IonSpinner, IonText, useIonRouter } from "@ionic/react"; import { useCometChatCalls } from "../providers/CometChatCallsProvider"; const HomePage: React.FC = () => { const { isReady, user, error } = useCometChatCalls(); const router = useIonRouter(); const [sessionId, setSessionId] = useState(""); const joinCall = () => { if (sessionId) { router.push(`/call/${sessionId}`); } }; return ( CometChat Calls {error && (

{error}

)} {!isReady ? (

) : ( <>

Logged in as: {user?.name || user?.uid}

Session ID setSessionId(e.detail.value || "")} placeholder="Enter Session ID" /> Join Call )} ); }; export default HomePage; ``` ## Ionic Vue ### Step 2: Create the Composable Create a composable that handles SDK initialization and authentication: ```typescript theme={null} // src/composables/useCometChatCalls.ts import { ref, readonly } from "vue"; import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; interface User { uid: string; name: string; avatar?: string; } // Replace with your CometChat credentials const APP_ID = "YOUR_APP_ID"; const REGION = "YOUR_REGION"; const API_KEY = "YOUR_API_KEY"; // Shared state across all components const isReady = ref(false); const user = ref(null); const error = ref(null); const initialized = ref(false); export function useCometChatCalls() { async function initAndLogin(uid: string): Promise { if (initialized.value) { return isReady.value; } try { // Step 1: Initialize the SDK const initResult = await CometChatCalls.init({ appId: APP_ID, region: REGION, }); if (!initResult.success) { throw new Error("SDK initialization failed"); } // Step 2: Check if already logged in let loggedInUser = CometChatCalls.getLoggedInUser(); // Step 3: Login if not already logged in if (!loggedInUser) { loggedInUser = await CometChatCalls.login(uid, API_KEY); } user.value = loggedInUser; isReady.value = true; initialized.value = true; return true; } catch (err: any) { console.error("CometChat Calls setup failed:", err); error.value = err.message || "Setup failed"; return false; } } return { isReady: readonly(isReady), user: readonly(user), error: readonly(error), initAndLogin, }; } ``` ### Step 3: Initialize in App Component Initialize the SDK and login when the app starts: ```vue theme={null} ``` ### Step 4: Create the Call Page Create a call page that handles joining sessions, media controls, and cleanup: ```vue theme={null} ``` ### Step 5: Create the Home Page Create a home page where users can enter a session ID and join a call: ```vue theme={null} ``` ### Step 6: Configure Routes Set up the router with the home and call pages: ```typescript theme={null} // src/router/index.ts import { createRouter, createWebHistory } from "@ionic/vue-router"; import { RouteRecordRaw } from "vue-router"; import HomePage from "../views/HomePage.vue"; import CallPage from "../views/CallPage.vue"; const routes: Array = [ { path: "/", component: HomePage, }, { path: "/call/:sessionId", component: CallPage, }, ]; const router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes, }); export default router; ``` ## Related Documentation For more detailed information on specific topics covered in this guide, refer to the main documentation: * [Setup](/docs/calls/javascript/setup) - Detailed SDK installation and initialization * [Authentication](/docs/calls/javascript/authentication) - Login methods and user management * [Session Settings](/docs/calls/javascript/session-settings) - All available call configuration options * [Join Session](/docs/calls/javascript/join-session) - Session joining and token generation * [Events](/docs/calls/javascript/events) - Complete list of event listeners * [Actions](/docs/calls/javascript/actions) - All available call control methods * [Call Layouts](/docs/calls/javascript/call-layouts) - Layout options and customization * [Participant Management](/docs/calls/javascript/participant-management) - Managing call participants # Join Session Source: https://www.cometchat.com/docs/calls/javascript/join-session Join CometChat Calls SDK v5 sessions on JavaScript with session IDs, call tokens, participant setup, and in-call UI launch. Join a call session using one of two approaches: the quick start method with a session ID, or the advanced flow with manual token generation for more control. ## Overview The CometChat Calls SDK provides two ways to join a session: | Approach | Best For | Complexity | | - | - | - | | **Join with Token** | Most use cases - recommended approach | Low - Two-step process | | **Generate Token Separately** | Custom token management, pre-generation, caching | Medium - Separate token handling | > [!NOTE] > > Both approaches require a container element in your HTML where the call interface will be rendered. ## Container Setup Add a container element to your HTML where the call interface will be rendered: ```html theme={null}

``` The call UI will be dynamically rendered inside this container when you join the session. ## Generate Token Generate a call token for the session. Each token is unique to a specific session and user combination. ```javascript theme={null} const sessionId = "SESSION_ID"; try { const result = await CometChatCalls.generateToken(sessionId); console.log("Token generated:", result.token); // Use the token to join the session } catch (error) { console.error("Token generation failed:", error.errorDescription); } ``` | Parameter | Type | Description | | - | - | - | | `sessionId` | String | Unique identifier for the call session | The method returns an object with: | Property | Type | Description | | - | - | - | | `token` | String | The generated call token | > [!NOTE] > > The `generateToken()` method uses the auth token of the currently logged-in user. Ensure a user is logged in before calling this method. ## Join Session Use the generated token to join the session along with your call settings and container element. ```javascript theme={null} const container = document.getElementById("call-container"); const callSettings = { sessionType: "VIDEO", layout: "TILE", startAudioMuted: false, startVideoPaused: false, }; const result = await CometChatCalls.joinSession(callToken, callSettings, container); if (result.error) { console.error("Failed to join session:", result.error); } else { console.log("Joined session successfully"); } ``` | Parameter | Type | Description | | - | - | - | | `callToken` | String | Previously generated call token | | `callSettings` | Object | Configuration for the session (see [Session Settings](/docs/calls/javascript/session-settings)) | | `container` | HTMLElement | Container element for the call UI | The method returns an object with: | Property | Type | Description | | - | - | - | | `data` | undefined | Undefined on success | | `error` | Object \| null | Error details if join failed | ## Complete Example ```javascript theme={null} const sessionId = "SESSION_ID"; const container = document.getElementById("call-container"); // Step 1: Generate token try { const tokenResult = await CometChatCalls.generateToken(sessionId); // Step 2: Configure session settings const callSettings = { sessionType: "VIDEO", layout: "TILE", startAudioMuted: false, startVideoPaused: false, }; // Step 3: Join session const joinResult = await CometChatCalls.joinSession( tokenResult.token, callSettings, container ); if (joinResult.error) { console.error("Failed to join session:", joinResult.error); } else { console.log("Joined session successfully"); } } catch (error) { console.error("Error:", error); } ``` > [!NOTE] > > All participants joining the same call must use the same session ID. ## One Session at a Time `CometChatCalls` is a singleton that holds a single active session. Joining a second session while one is in progress is not supported - leave the current session first, wait for `onSessionLeft`, then join the next one. ```javascript theme={null} CometChatCalls.addEventListener("onSessionLeft", async () => { const { token } = await CometChatCalls.generateToken(nextSessionId); await CometChatCalls.joinSession(token, callSettings, container); }); CometChatCalls.leaveSession(); ``` This is also why `leaveSession()` and the other [actions](/docs/calls/javascript/actions) take no session ID - they always apply to the session that is currently active. See [Single Active Session](/docs/calls/javascript/overview#single-active-session) for the full behavior. ## Error Handling Common errors when joining a session: | Error Code | Description | | - | - | | `ERROR_SDK_NOT_INITIALIZED` | SDK not initialized - call `init()` first | | `ERROR_AUTH_TOKEN_MISSING` | User not logged in or auth token invalid | | `ERROR_SESSION_ID_MISSING` | Session ID is null or empty | | `VALIDATION_ERROR` | Invalid call settings | # Changelog Source: https://www.cometchat.com/docs/calls/javascript/link/changelog Navigate to Changelog documentation. # GitHub Source: https://www.cometchat.com/docs/calls/javascript/link/github Navigate to GitHub documentation. # Live Demo Source: https://www.cometchat.com/docs/calls/javascript/link/live-demo Navigate to Live Demo documentation. # Sample Apps Source: https://www.cometchat.com/docs/calls/javascript/link/sample-apps Navigate to Sample Apps documentation. # Migrating from Legacy Ringing Source: https://www.cometchat.com/docs/calls/javascript/migrating-from-legacy-ringing Move a web app from Chat SDK call signalling (CometChat.initiateCall, acceptCall, rejectCall) to ringing with the Calls SDK 5.1: what to add, what to delete, and how each method maps. Legacy ringing signalled calls through the Chat SDK: `CometChat.initiateCall` created the call, a `CallListener` on the Chat SDK's real-time connection told the callee, and `acceptCall`, `rejectCall` and `endCall` answered, declined and ended it. Ringing now runs on the Calls SDK: it creates the call, prepares and joins the session, and ends the ring. The Chat SDK's calling methods are superseded by the Calls SDK and no longer used. On the web, the Chat SDK's `CallListener` stays: it is still how an incoming call reaches an open tab. This page is the diff. For the full description of the current flow see [Ringing](/docs/calls/javascript/ringing). ## Before you start Ringing with the Calls SDK is opt-in on the client: update your app to the APIs below. While some of your users are still on legacy ringing, one dashboard setting lets the two flows call each other; see [While some users are still on legacy ringing](#while-some-users-are-still-on-legacy-ringing). This page is for apps that use the SDKs directly. If you use the CometChat UI Kit, its support for this flow comes with a coming UI Kit release; keep legacy ringing until then. > [!NOTE] > > Web and mobile apps ring each other on this flow when the mobile app also rings with the Calls SDK 5.1 and the Push Notifications SDK 2.0. Calls between an app on legacy ringing and an app on this flow ring once **Connect legacy ringing** is on in the dashboard; see [While some users are still on legacy ringing](#while-some-users-are-still-on-legacy-ringing). ## Why it changed | Legacy | Now | | - | - | | The Chat SDK created the call, and `acceptCall` / `rejectCall` / `endCall` were HTTP calls your app had to sequence with `generateToken` and `joinSession` | The Calls SDK creates the call and prepares its session. Answer = join; decline, busy, cancel and no answer are one `endCall(sessionId, status)` | | The caller only knew "accepted" or "rejected" | The caller sees "Ringing…" (the callee's device was reached) and "answered" from the Calls SDK. A decline, busy or no answer still arrives as the Chat SDK's `onOutgoingCallRejected`, with the reason in its status | | Joining took a token request and a full connect after the answer | The session is prepared while it rings, so the join is near-instant | | Web and mobile rang through different paths | One call, rung in the callee's open tabs (Chat SDK) and on the callee's phones (Push Notifications SDK 2.0, in a mobile app on the Calls SDK 5.1) | ## Before and after ```mermaid theme={null} sequenceDiagram participant A as Caller participant Chat as Chat SDK participant B as Callee rect rgb(240,240,240) Note over A,B: Legacy ringing A->>Chat: CometChat.initiateCall(call) Chat-->>B: CallListener.onIncomingCallReceived B->>Chat: CometChat.acceptCall(sessionId) Chat-->>A: onOutgoingCallAccepted A->>A: generateToken + joinSession B->>B: generateToken + joinSession A->>Chat: CometChat.endCall(sessionId) Chat-->>B: onCallEndedMessageReceived end ``` ```mermaid theme={null} sequenceDiagram participant A as Caller · Calls SDK participant BE as Backend participant Chat as Callee · Chat SDK participant C as Callee · Calls SDK rect rgb(232,244,236) Note over A,C: Ringing now A->>BE: CometChatCalls.initiateCall(receiver, options) BE-->>Chat: call message (initiated) Chat-->>C: onIncomingCallReceived → CometChatCalls.connect(sessionId) C-->>A: onParticipantConnected ("Ringing…") C->>C: Answer → session.join(container) C-->>A: onParticipantJoined → data.session.join(container) A->>A: session.leave() to hang up end ``` ## Step 1: Update dependencies ```bash theme={null} npm install @cometchat/calls-sdk-javascript@5.1.0 # @cometchat/chat-sdk-javascript (4.2.1 or later) stays: chat, and incoming calls on the web ``` Keep both SDKs initialized and logged in as the same user: the Calls SDK for `initiateCall`, `connect` and `endCall`, the Chat SDK for the incoming call message. For TypeScript: in 5.1 the error type of `joinSession()` and `session.join(container)` is `JoinSessionException` (it was `VerifyTokenException` in 5.0), which adds `SESSION_SETTINGS_REQUIRED`, `SESSION_ALREADY_PREPARED` and `SESSION_CANCELLED`. See "5.0 to 5.1" in the [v5 migration guide](/docs/calls/javascript/migration-guide-v5). ## Step 2: Rewrite the caller | Legacy | Now | Notes | | - | - | - | | `CometChat.initiateCall(new CometChat.Call(receiverId, callType, receiverType))` | `CometChatCalls.initiateCall(receiver, { type, receiverType, sessionSettings })` → `{ data, error }` | `data.session` is the caller's session, already preparing. Set `sessionType` in `sessionSettings`, and `isPeerCall: true` for a 1:1 call | | `CometChat.initiateCall(call, timeout)` | No timeout parameter | Run your own timer on the caller and end the call with `endCall(sessionId, "unanswered")` after 45 s, the default length of a phone's ring | | `onOutgoingCallAccepted(call)` | `CometChatCalls.addEventListener("onParticipantJoined", ...)` on the prepared session, then `data.session.join(container)` | New in-between event: `onParticipantConnected` = the callee's device is ringing | | `onOutgoingCallRejected(call)` | Unchanged: a decline, busy or no answer still arrives on the Chat SDK's `CallListener`, with the reason in `call.getStatus()`. Also `onConnectionClosed` when a callee that had prepared a 1:1 session declines | The Calls SDK reports no reason itself. Check `getCallInitiator()`: a 1:1 decline reaches the callee's other tabs too. Keep a 3 s status poll as a backstop for a message a tab missed (asleep, reconnecting) | | `CometChat.rejectCall(sessionId, CometChat.CALL_STATUS.CANCELLED)` | `CometChatCalls.endCall(sessionId, "cancelled")` | Tears the caller's prepared session down first | | `generateToken` + `joinSession` after the answer | `data.session.join(container)` | Takes no settings: the ones passed to `initiateCall` apply | > [tab] Before > > ```javascript theme={null} > const call = new CometChat.Call(receiverId, CometChat.CALL_TYPE.VIDEO, CometChat.RECEIVER_TYPE.USER); > const outgoingCall = await CometChat.initiateCall(call); > > CometChat.addCallListener("caller", new CometChat.CallListener({ > onOutgoingCallAccepted: async (accepted) => { > const { token } = await CometChatCalls.generateToken(accepted.getSessionId()); > await CometChatCalls.joinSession(token, { sessionType: "VIDEO" }, container); > }, > onOutgoingCallRejected: () => closeOutgoingScreen(), > })); > > function cancel() { > CometChat.rejectCall(outgoingCall.getSessionId(), CometChat.CALL_STATUS.CANCELLED); > } > ``` > [tab] After > > ```javascript theme={null} > const { data: call, error } = await CometChatCalls.initiateCall(receiverId, { > type: "video", > sessionSettings: { sessionType: "VIDEO", isPeerCall: true }, > }); > if (error) throw new Error(`Could not start the call: ${error.message}`); > > const offConnected = CometChatCalls.addEventListener("onParticipantConnected", () => setStatus("Ringing…")); > const offJoined = CometChatCalls.addEventListener("onParticipantJoined", () => { > stopWatching(); > call.session.join(container); > }); > const offClosed = CometChatCalls.addEventListener("onConnectionClosed", () => closeOutgoingScreen()); > const stopWatching = () => { offConnected(); offJoined(); offClosed(); }; > // Keep onOutgoingCallRejected on your CallListener for a decline, busy or no answer. > // Plus: poll the call's status every 3 s as a backstop and a 45 s ring timer (see Ringing). > > function cancel() { > stopWatching(); > CometChatCalls.endCall(call.sessionId, "cancelled"); > } > ``` ## Step 3: Rewrite the callee | Legacy | Now | Notes | | - | - | - | | `CallListener.onIncomingCallReceived(call)` | Unchanged: the call still arrives on the Chat SDK's `CallListener`. Then prepare it with `CometChatCalls.connect(call.getSessionId(), settings)` | The caller's own tabs receive their 1:1 call as "incoming" too: skip calls whose `getCallInitiator()` is the logged-in user | | `CometChat.acceptCall(sessionId)` then `generateToken` + `joinSession` | `session.join(container)` on the session `connect` prepared. Nothing else to send | If the prepare failed, `generateToken` + `joinSession` as before | | `CometChat.rejectCall(sessionId, CometChat.CALL_STATUS.REJECTED)` | `CometChatCalls.endCall(sessionId, "rejected")` | `"busy"` when the user is in another call. A group call's decline is local: `session.leave()` | | `onIncomingCallCancelled(call)` | Still fires (also when the caller gives up as `unanswered`); also `onConnectionClosed` on a prepared 1:1 session | Keep a 3 s status poll while ringing as a backstop for a message the tab missed (asleep, reconnecting) | | — | Your own ring timer on the callee | Stop ringing after 60 s, a little after the caller gives up at 45 s | > [tab] Before > > ```javascript theme={null} > CometChat.addCallListener("callee", new CometChat.CallListener({ > onIncomingCallReceived: (call) => showIncomingScreen(call), > onIncomingCallCancelled: () => closeIncomingScreen(), > })); > > async function answer(call) { > await CometChat.acceptCall(call.getSessionId()); > const { token } = await CometChatCalls.generateToken(call.getSessionId()); > await CometChatCalls.joinSession(token, { sessionType: "VIDEO" }, container); > } > > function decline(call) { > CometChat.rejectCall(call.getSessionId(), CometChat.CALL_STATUS.REJECTED); > } > ``` > [tab] After > > ```javascript theme={null} > // Settings for an incoming 1:1 call: the type comes from the call, or an audio call opens the camera. > const settingsFor = (call) => ({ > sessionType: call.getType() === "audio" ? "VOICE" : "VIDEO", > isPeerCall: true, > }); > > CometChat.addCallListener("callee", new CometChat.CallListener({ > onIncomingCallReceived: (call) => { > if (call.getCallInitiator()?.getUid() === CometChatCalls.getLoggedInUser()?.uid) return; > showIncomingScreen(call); > CometChatCalls.connect(call.getSessionId(), settingsFor(call)) > .catch(() => {}); // answer falls back to a direct join > }, > onIncomingCallCancelled: () => closeIncomingScreen(), > })); > > async function answer(call) { > const session = CometChatCalls.getActiveSession(); > if (session?.sessionId === call.getSessionId()) { > await session.join(container); > } else { > const { token } = await CometChatCalls.generateToken(call.getSessionId()); > await CometChatCalls.joinSession(token, settingsFor(call), container); > } > } > > function decline(call) { > CometChatCalls.endCall(call.getSessionId(), "rejected"); > } > ``` ## Step 4: Replace the remaining calls | Legacy | Now | Notes | | - | - | - | | `CometChat.endCall(sessionId)` after a call | `session.leave()` or `CometChatCalls.leaveSession()` | No status to send; with `isPeerCall` the call ends for both | | `CometChat.getActiveCall()` | `CometChatCalls.getActiveSession()` | `null` when no session is preparing, prepared or joined. `session.sessionId` names the call for a session from `initiateCall` or `connect` (it is `null` after a direct `joinSession`) | | `CometChat.clearActiveCall()` | Nothing | The Calls SDK clears its session when it ends | | `onCallEndedMessageReceived(call)` | `onSessionLeft` / `onConnectionClosed` on the joined session | | | `CometChat.startCall(...)`, Chat SDK `CallSettings` | `joinSession` + the 5.x events (see the [v5 migration guide](/docs/calls/javascript/migration-guide-v5)) | | | `CometChat.CALL_STATUS.*` values for a decline or cancel | `"rejected"`, `"busy"`, `"cancelled"`, `"unanswered"` strings passed to `endCall` | The `Call` message model and `CometChat.CALL_STATUS` still describe call messages in a conversation's history | ## While some users are still on legacy ringing Your users don't all update at once, so during the rollout one CometChat app has devices on both flows. A device's flow comes from its push registration: a device on the Calls SDK 5.1 and Push Notifications SDK 2.0 receives only the call-initiated push, and a device still on legacy ringing keeps receiving the legacy call events. To let users on the two flows call each other, turn on **Connect legacy ringing** in the CometChat dashboard under **Voice & Video Calls → Settings**. CometChat then also sends calls made on this flow as legacy call events, so devices on either flow ring for calls from the other. * Turn it on before the first users update, and leave it on while any version of your apps still in use rings the legacy way. * It can't be turned off from the dashboard. * The six legacy call events (ongoing, cancelled, rejected, unanswered, busy and ended) are under **Show legacy** in **Notifications → Settings → Call Preferences**. They only reach devices on legacy ringing. ## What users will notice * The caller sees "Ringing…" once the callee's tab or phone is reached, and the call screen closes when the call is declined, busy or missed (from `onOutgoingCallRejected`, the status poll, or the ring timer). * Answering joins almost at once, because the session was prepared while it rang. * Calls ring between web and mobile users in both directions, when the mobile app also rings with the Calls SDK 5.1 and the Push Notifications SDK 2.0. Calls between an app on legacy ringing and an app on this flow ring too, once **Connect legacy ringing** is on in the dashboard. * The browser asks for the camera and microphone when the call is joined, not while it rings. ## Checklist * [ ] `@cometchat/calls-sdk-javascript` 5.1; the Chat SDK (4.2.1 or later) stays, initialized and logged in as the same user * [ ] The mobile apps your web app calls also ring with the Calls SDK 5.1 and the Push Notifications SDK 2.0, or **Connect legacy ringing** is on in the dashboard * [ ] `initiateCall` passes `sessionSettings` with `sessionType`, and `isPeerCall: true` for a 1:1 call * [ ] Caller listens for `onParticipantConnected` / `onParticipantJoined` / `onConnectionClosed` and joins only on `onParticipantJoined` with `data.session.join(container)` * [ ] Caller ends the screen on `onOutgoingCallRejected`, polls the call's status every 3 s while ringing as a backstop, and runs a ring timer that ends the call as `unanswered` * [ ] Callee skips its own outgoing calls, prepares with `connect`, and answers with `session.join(container)` * [ ] Callee stops ringing on `onIncomingCallCancelled`, `onConnectionClosed`, its ring timer and the status poll * [ ] Decline, busy and cancel use `CometChatCalls.endCall`; no `CometChat.acceptCall`, `rejectCall` or `endCall` left * [ ] Hang-up uses `session.leave()` or `CometChatCalls.leaveSession()` * [ ] Tested: web to web, web to phone and phone to web; decline, busy, cancel, no answer; two open tabs # Migration Guide Source: https://www.cometchat.com/docs/calls/javascript/migration-guide-v5 Migrate to CometChat Calls SDK v5 on JavaScript with updated setup, APIs, call sessions, layouts, and feature changes. This guide covers migrating from Calls SDK v4 to v5 for JavaScript (React, Vue, Angular, etc.). ## Drop-in Compatibility Calls SDK v5 is a **drop-in replacement** for v4. All v4 APIs are preserved as deprecated methods that internally delegate to the new v5 implementations. You can update the package version and your existing code will compile and run without changes. ```bash theme={null} npm install @cometchat/calls-sdk-javascript@5 ``` > [!NOTE] > > If you're using CometChat UI Kits, simply updating the Calls SDK version is sufficient. The UI Kit will continue to work with v5 through the deprecated compatibility layer. ## Why Migrate to v5 APIs? While v4 APIs will continue to work, migrating to v5 APIs gives you: * **Granular event listeners** — subscribe to specific events like `onParticipantJoined` or `onSessionLeft` instead of one monolithic `OngoingCallListener` * **Dedicated `login()` method** — the Calls SDK now handles its own authentication instead of depending on the Chat SDK's auth token or REST APIs * **Simplified initialization** — pass plain objects to `init()` and `joinSession()` instead of using builder classes * **Strongly-typed enums** — `LayoutType`, `SessionType` instead of raw strings *** ## Initialization v5 accepts a plain object instead of requiring `CallAppSettingsBuilder`. > [tab] v4 > > ```javascript theme={null} > const callAppSettings = new CometChatCalls.CallAppSettingsBuilder() > .setAppId("APP_ID") > .setRegion("REGION") > .build(); > > CometChatCalls.init(callAppSettings).then( > () => { /* initialized */ }, > (error) => { /* handle error */ } > ); > ``` > [tab] v5 > > ```javascript theme={null} > const callAppSettings = { > appId: "APP_ID", > region: "REGION", > }; > > CometChatCalls.init(callAppSettings).then( > () => { /* initialized */ }, > (error) => { /* handle error */ } > ); > ``` > [!NOTE] > > `CallAppSettingsBuilder` still works in v5 — it's deprecated but functional. *** ## Authentication In v4, the Calls SDK had no dedicated authentication step. It relied on the Chat SDK's auth token (the logged-in user's `getAuthToken()`) or a REST API to obtain an auth token, which you then passed manually to `generateToken()`. v5 introduces its own `login()` method. After calling `login()`, the SDK caches the auth token internally. > [tab] v4 > > ```javascript theme={null} > // No dedicated Calls SDK login — relied on Chat SDK for auth token > const authToken = (await CometChat.getLoggedinUser()).getAuthToken(); > > // Had to pass authToken manually > CometChatCalls.generateToken(sessionId, authToken).then( > (token) => { /* use token to start session */ }, > (error) => { } > ); > ``` > [tab] v5 > > ```javascript theme={null} > // Login to the Calls SDK once (after your Chat SDK login) > CometChatCalls.loginWithAuthToken(authToken).then( > (user) => { /* Calls SDK is now authenticated */ }, > (error) => { } > ); > > // generateToken no longer needs the authToken parameter > CometChatCalls.generateToken(sessionId).then( > (token) => { /* use token */ }, > (error) => { } > ); > ``` > [!NOTE] > > Call `CometChatCalls.loginWithAuthToken()` once after your user authenticates. The SDK stores the auth token internally, so subsequent calls like `generateToken()` and `joinSession()` use it automatically. *** ## Session Settings `CallSettingsBuilder` is replaced by passing a plain `SessionSettings` object directly to `joinSession()`. > [tab] v4 > > ```javascript theme={null} > const callSettings = new CometChatCalls.CallSettingsBuilder() > .enableDefaultLayout(true) > .setIsAudioOnlyCall(true) > .showEndCallButton(true) > .showMuteAudioButton(true) > .showPauseVideoButton(true) > .showRecordingButton(true) > .showScreenShareButton(true) > .showModeButton(true) > .startWithAudioMuted(false) > .startWithVideoMuted(false) > .setMode("DEFAULT") > .setCallListener(new CometChatCalls.OngoingCallListener({ > onCallEnded: () => { }, > onCallEndButtonPressed: () => { }, > onUserJoined: (user) => { }, > onUserLeft: (user) => { }, > onUserListUpdated: (userList) => { }, > onError: (error) => { }, > })) > .build(); > ``` > [tab] v5 > > ```javascript theme={null} > const sessionSettings = { > sessionType: "VIDEO", // or "VOICE" > layout: "TILE", // or "SPOTLIGHT", "SIDEBAR" > startAudioMuted: false, > startVideoPaused: false, > hideLeaveSessionButton: false, > hideToggleAudioButton: false, > hideToggleVideoButton: false, > hideRecordingButton: false, > hideScreenSharingButton: false, > hideChangeLayoutButton: false, > hideControlPanel: false, > autoStartRecording: false, > }; > ``` ### Settings Property Mapping | v4 Builder Method | v5 Property | Notes | | - | - | - | | `setIsAudioOnlyCall(true)` | `sessionType: "VOICE"` | Use `"VIDEO"` for video calls | | `enableDefaultLayout(bool)` | `hideControlPanel: !bool` | Inverted logic | | `showEndCallButton(bool)` | `hideLeaveSessionButton: !bool` | Inverted logic | | `showMuteAudioButton(bool)` | `hideToggleAudioButton: !bool` | Inverted logic | | `showPauseVideoButton(bool)` | `hideToggleVideoButton: !bool` | Inverted logic | | `showRecordingButton(bool)` | `hideRecordingButton: !bool` | Inverted logic | | `showScreenShareButton(bool)` | `hideScreenSharingButton: !bool` | Inverted logic | | `showModeButton(bool)` | `hideChangeLayoutButton: !bool` | Inverted logic | | `startWithAudioMuted(bool)` | `startAudioMuted: bool` | Same logic | | `startWithVideoMuted(bool)` | `startVideoPaused: bool` | Same logic | | `setMode("DEFAULT")` | `layout: "SIDEBAR"` | `"DEFAULT"` maps to `"SIDEBAR"` | | `startRecordingOnCallStart(bool)` | `autoStartRecording: bool` | Same logic | | `setCallListener(listener)` | Use `addEventListener()` | See [Events](#event-listeners) section | *** ## Joining a Session `startSession()` is replaced by `joinSession()`. > [tab] v4 > > ```javascript theme={null} > CometChatCalls.generateToken(sessionId, authToken).then((token) => { > CometChatCalls.startSession(token, callSettings, document.getElementById("callContainer")); > }); > ``` > [tab] v5 > > ```javascript theme={null} > // Generate a call token for the session, then join with it > CometChatCalls.generateToken(sessionId).then(({ token }) => { > CometChatCalls.joinSession(token, sessionSettings, document.getElementById("callContainer")); > }); > ``` *** ## Session Control (Actions) Static methods remain on `CometChatCalls` but some have been renamed. > [!NOTE] > > **Boolean toggles are now paired methods.** In v4, `muteAudio()` took a boolean: `muteAudio(true)` muted the mic and `muteAudio(false)` unmuted it. In v5 these are two separate, argument-free methods — replace `muteAudio(true)` with `muteAudio()` and `muteAudio(false)` with `unmuteAudio()`. The same split applies to `pauseVideo(true)` / `pauseVideo(false)`, which become `pauseVideo()` and `resumeVideo()`. ```javascript theme={null} // v4 CometChatCalls.muteAudio(true); // mute CometChatCalls.muteAudio(false); // unmute // v5 CometChatCalls.muteAudio(); // mute CometChatCalls.unmuteAudio(); // unmute ``` | v4 Method | v5 Method | | - | - | | `CometChatCalls.endSession()` | `CometChatCalls.leaveSession()` | | `CometChatCalls.switchCamera()` | `CometChatCalls.switchCamera()` | | `CometChatCalls.muteAudio(true)` | `CometChatCalls.muteAudio()` | | `CometChatCalls.muteAudio(false)` | `CometChatCalls.unmuteAudio()` | | `CometChatCalls.pauseVideo(true)` | `CometChatCalls.pauseVideo()` | | `CometChatCalls.pauseVideo(false)` | `CometChatCalls.resumeVideo()` | | `CometChatCalls.setMode(mode)` | `CometChatCalls.setLayout(layout)` | | `CometChatCalls.startScreenShare()` | `CometChatCalls.startScreenSharing()` | | `CometChatCalls.stopScreenShare()` | `CometChatCalls.stopScreenSharing()` | | `CometChatCalls.openVirtualBackground()` | `CometChatCalls.showVirtualBackgroundDialog()` | | `CometChatCalls.closeVirtualBackground()` | `CometChatCalls.hideVirtualBackgroundDialog()` | | `CometChatCalls.setBackgroundBlur(level)` | `CometChatCalls.setVirtualBackgroundBlurLevel(level)` | | `CometChatCalls.setBackgroundImage(url)` | `CometChatCalls.setVirtualBackgroundImage(url)` | | `CometChatCalls.startRecording()` | `CometChatCalls.startRecording()` | | `CometChatCalls.stopRecording()` | `CometChatCalls.stopRecording()` | | `CometChatCalls.switchToVideoCall()` | *Removed* | | `CometChatCalls.getCallDetails()` | *Removed* | *** ## Event Listeners The single `OngoingCallListener` is replaced by `addEventListener()` with specific event types. ### v4: Single Listener Object ```javascript theme={null} const callSettings = new CometChatCalls.CallSettingsBuilder() .setCallListener(new CometChatCalls.OngoingCallListener({ onCallEnded: () => { }, onCallEndButtonPressed: () => { }, onUserJoined: (user) => { }, onUserLeft: (user) => { }, onUserListUpdated: (userList) => { }, onUserMuted: (muteInfo) => { }, onRecordingStarted: (recordingInfo) => { }, onRecordingStopped: () => { }, onError: (error) => { }, })) .build(); ``` ### v5: Granular Event Subscriptions ```javascript theme={null} // Session events CometChatCalls.addEventListener("onSessionJoined", () => { }); CometChatCalls.addEventListener("onSessionLeft", () => { }); CometChatCalls.addEventListener("onSessionTimedOut", () => { }); CometChatCalls.addEventListener("onConnectionLost", () => { }); CometChatCalls.addEventListener("onConnectionRestored", () => { }); // Participant events CometChatCalls.addEventListener("onParticipantJoined", (participant) => { }); CometChatCalls.addEventListener("onParticipantLeft", (participant) => { }); CometChatCalls.addEventListener("onParticipantListChanged", (participants) => { }); CometChatCalls.addEventListener("onParticipantAudioMuted", (participant) => { }); CometChatCalls.addEventListener("onParticipantAudioUnmuted", (participant) => { }); // Media events CometChatCalls.addEventListener("onAudioMuted", () => { }); CometChatCalls.addEventListener("onAudioUnMuted", () => { }); CometChatCalls.addEventListener("onRecordingStarted", () => { }); CometChatCalls.addEventListener("onRecordingStopped", () => { }); // Button click events CometChatCalls.addEventListener("onLeaveSessionButtonClicked", () => { }); CometChatCalls.addEventListener("onToggleAudioButtonClicked", () => { }); CometChatCalls.addEventListener("onToggleVideoButtonClicked", () => { }); // Layout events CometChatCalls.addEventListener("onCallLayoutChanged", (layoutType) => { }); ``` > [!NOTE] > > `addEventListener()` returns an unsubscribe function. Call it to remove the listener. You can also pass an `AbortSignal` for cleanup. ### New Events Require `addEventListener()` The events introduced in v5 are only delivered through `addEventListener()`. The v4 registration path — `setCallListener()` on `CallSettingsBuilder` — never fires them, because `OngoingCallListener` only carries the legacy v4 event set. (v4's `CometChatCalls.addCallEventListener()` is not in v5 at all.) Events such as `onSessionJoined`, `onConnectionLost`, `onLeaveSessionButtonClicked`, and `onCallLayoutChanged` are unreachable from a v4 listener no matter how it is registered. You don't have to migrate everything at once. `addEventListener()` works alongside an existing v4 listener without breaking it — keep your current `OngoingCallListener` for the legacy events and add `addEventListener()` subscriptions for the new ones. ```javascript theme={null} // Existing v4 listener keeps working const callSettings = new CometChatCalls.CallSettingsBuilder() .setCallListener(new CometChatCalls.OngoingCallListener({ onCallEnded: () => { }, onUserJoined: (user) => { }, })) .build(); // Add v5-only events alongside it CometChatCalls.addEventListener("onConnectionLost", () => { }); CometChatCalls.addEventListener("onCallLayoutChanged", (layoutType) => { }); ``` ### Event Mapping | v4 Event | v5 Event | | - | - | | `onCallEnded` | `onSessionLeft` | | `onCallEndButtonPressed` | `onLeaveSessionButtonClicked` | | `onUserJoined(user)` | `onParticipantJoined(participant)` | | `onUserLeft(user)` | `onParticipantLeft(participant)` | | `onUserListUpdated(userList)` | `onParticipantListChanged(participants)` | | `onUserMuted(info)` | `onParticipantAudioMuted(participant)` | | `onRecordingStarted` / `onRecordingStopped` | `onRecordingStarted` / `onRecordingStopped` | | `onError(error)` | Errors returned via Promise rejection | *** ## Deprecated Classes Summary | Deprecated | Replacement | | - | - | | `CometChatCalls.CallAppSettingsBuilder` | Pass plain object to `init()` | | `CometChatCalls.CallSettingsBuilder` | Pass plain `SessionSettings` object to `joinSession()` | | `CometChatCalls.OngoingCallListener` | `CometChatCalls.addEventListener()` | | `CometChatCalls.startSession()` | `CometChatCalls.joinSession()` | | `CometChatCalls.endSession()` | `CometChatCalls.leaveSession()` | *** ## 5.0 to 5.1 5.1 moves ringing onto the Calls SDK. No 5.0 method is deprecated; the Chat SDK's calling methods are superseded: | Superseded | Replacement | | - | - | | Chat SDK calling: `CometChat.initiateCall`, `acceptCall`, `rejectCall`, `endCall`, `startCall`, `getActiveCall`, `clearActiveCall`, Chat SDK `CallSettings` | `CometChatCalls.initiateCall`, `connect`, `session.join(container)`, `endCall(sessionId, status)`, `session.leave()`, `getActiveSession()` | `CometChat.addCallListener` is not superseded on the web: an incoming call still reaches an open tab through it. New in 5.1: * `CometChatCalls.initiateCall(receiver, options)` with `InitiateCallOptions`, resolving with `{ data, error }` where `data` is an `InitiatedCall` * `CometChatCalls.endCall(sessionId, status)` with `EndCallStatus` (`"rejected"`, `"busy"`, `"cancelled"`, `"unanswered"`) * `CometChatCalls.connect(sessionId, sessionSettings)`, which prepares a session ahead of the join, and `PrepareStatus` (`"none"`, `"pending"`, `"prepared"`, `"cancelled"`, `"failed"`) * `CometChatCalls.getActiveSession()`, `CometChatCalls.getSessionState()` and `CometChatCalls.getParticipants()` * The `CallSession` session object: `sessionId`, `callToken`, `settings`, `prepareStatus`, `settled`, `error`, `join(container)`, `leave()`, `endSessionForAll()`, `isSessionActive()`, `isSessionJoined()`, `getSessionState()`, `getParticipants()`, `addEventListener()` and every session action as a method * The `onConnected` and `onParticipantConnected` events * The exported `CallParticipant` type Changed in 5.1: * `CallSession` replaces the placeholder class 5.0 exported under that name: its `getInstance()` is gone, and `addEventListener()` now returns an unsubscribe function instead of `{ remove }`. Get the session from `initiateCall`, `connect` or `getActiveSession()`. * `joinSession()` can return more errors: `SESSION_SETTINGS_REQUIRED` (no settings passed), `SESSION_ALREADY_PREPARED` and `SESSION_CANCELLED` (the join was cancelled by `leaveSession()` before it completed). A failed token verification is now returned as `error` too. * For TypeScript: the error type of `joinSession()` (and of `session.join(container)`) is now the exported `JoinSessionException`; in 5.0 it was `VerifyTokenException`. `JoinSessionException` covers the token-verification error plus the three names above, so code that narrows on `error.name` may need the new cases. * `leaveSession()` returns a Promise that resolves when the leave has been handled. `joinSession()` returns `SESSION_ALREADY_PREPARED` while a session is prepared: join that one with `session.join(container)`, or cancel it with `session.leave()` first. A prepared session keeps the settings it was prepared with. The step-by-step move from Chat SDK signalling is on [Migrating from Legacy Ringing](/docs/calls/javascript/migrating-from-legacy-ringing). # Next.js Integration Source: https://www.cometchat.com/docs/calls/javascript/nextjs-integration Integrate CometChat Calls SDK v5 in Next.js apps with client-side setup, initialization, call UI rendering, and routing support. This guide walks you through integrating the CometChat Calls SDK into a Next.js application. By the end, you'll have a working video call implementation with proper server-side rendering handling and authentication. ## Prerequisites Before you begin, ensure you have: * A CometChat account with an app created ([Sign up](https://app.cometchat.com/signup)) * Your App ID, Region, and API Key from the CometChat Dashboard * A Next.js project (App Router or Pages Router) * Node.js 16+ installed ## Important: Client-Side Only The CometChat Calls SDK uses browser APIs (WebRTC, DOM) that are not available during server-side rendering. You must ensure the SDK only loads and runs on the client side. This guide shows you how to handle this properly with both the App Router and Pages Router. ## Step 1: Install the SDK Install the CometChat Calls SDK package: ```bash theme={null} npm install @cometchat/calls-sdk-javascript ``` ## Step 2: Configure Environment Variables Add your CometChat credentials to `.env.local`. The `NEXT_PUBLIC_` prefix makes these variables available in the browser: ```env theme={null} NEXT_PUBLIC_COMETCHAT_APP_ID=your_app_id NEXT_PUBLIC_COMETCHAT_REGION=us NEXT_PUBLIC_COMETCHAT_API_KEY=your_api_key ``` > [!WARNING] > > Never expose your API Key in production client-side code. Use a backend service to generate auth tokens securely. The API Key approach shown here is for development and testing only. ## Step 3: Create the Provider Create a context provider that handles SDK initialization and user authentication. The `"use client"` directive ensures this component only runs in the browser. ```tsx theme={null} // providers/CometChatCallsProvider.tsx "use client"; import { createContext, useContext, useEffect, useState, ReactNode } from "react"; interface User { uid: string; name: string; avatar?: string; } interface CometChatCallsContextType { isReady: boolean; user: User | null; error: string | null; CometChatCalls: any; } const CometChatCallsContext = createContext({ isReady: false, user: null, error: null, CometChatCalls: null, }); interface ProviderProps { children: ReactNode; uid: string; } export function CometChatCallsProvider({ children, uid }: ProviderProps) { const [isReady, setIsReady] = useState(false); const [user, setUser] = useState(null); const [error, setError] = useState(null); const [CometChatCalls, setCometChatCalls] = useState(null); useEffect(() => { async function initAndLogin() { try { // Dynamic import ensures the SDK only loads on the client const { CometChatCalls: SDK } = await import("@cometchat/calls-sdk-javascript"); // Step 1: Initialize the SDK const initResult = await SDK.init({ appId: process.env.NEXT_PUBLIC_COMETCHAT_APP_ID!, region: process.env.NEXT_PUBLIC_COMETCHAT_REGION!, }); if (!initResult.success) { throw new Error("SDK initialization failed"); } // Step 2: Check if already logged in let loggedInUser = SDK.getLoggedInUser(); // Step 3: Login if not already logged in if (!loggedInUser) { loggedInUser = await SDK.login( uid, process.env.NEXT_PUBLIC_COMETCHAT_API_KEY! ); } setCometChatCalls(SDK); setUser(loggedInUser); setIsReady(true); } catch (err: any) { console.error("CometChat Calls setup failed:", err); setError(err.message || "Setup failed"); } } if (uid) { initAndLogin(); } }, [uid]); return ( {children} ); } export function useCometChatCalls(): CometChatCallsContextType { return useContext(CometChatCallsContext); } ``` ## Step 4: Add Provider to Layout (App Router) Wrap your application with the provider. Since the provider is a client component, you can still use it in a server component layout: ```tsx theme={null} // app/layout.tsx import { CometChatCallsProvider } from "@/providers/CometChatCallsProvider"; export default function RootLayout({ children }: { children: React.ReactNode }) { // In a real app, get this from your authentication system const currentUserId = "cometchat-uid-1"; return ( {children} ); } ``` ## Step 5: Create the Call Component Build a client-side call component that handles joining sessions, media controls, and cleanup. The component uses the SDK instance from the context provider: ```tsx theme={null} // components/CallScreen.tsx "use client"; import { useEffect, useRef, useState } from "react"; import { useCometChatCalls } from "@/providers/CometChatCallsProvider"; interface CallScreenProps { sessionId: string; onCallEnd?: () => void; } export default function CallScreen({ sessionId, onCallEnd }: CallScreenProps) { const { isReady, CometChatCalls } = useCometChatCalls(); const containerRef = useRef(null); // Call state const [isJoined, setIsJoined] = useState(false); const [isJoining, setIsJoining] = useState(false); const [isMuted, setIsMuted] = useState(false); const [isVideoOff, setIsVideoOff] = useState(false); const [error, setError] = useState(null); // Store unsubscribe functions for cleanup const unsubscribersRef = useRef([]); useEffect(() => { // Don't proceed if SDK isn't ready or container isn't mounted if (!isReady || !CometChatCalls || !containerRef.current || !sessionId) return; async function joinCall() { setIsJoining(true); setError(null); try { // Register event listeners before joining unsubscribersRef.current = [ CometChatCalls.addEventListener("onSessionJoined", () => { setIsJoined(true); setIsJoining(false); }), CometChatCalls.addEventListener("onSessionLeft", () => { setIsJoined(false); onCallEnd?.(); }), CometChatCalls.addEventListener("onAudioMuted", () => setIsMuted(true)), CometChatCalls.addEventListener("onAudioUnMuted", () => setIsMuted(false)), CometChatCalls.addEventListener("onVideoPaused", () => setIsVideoOff(true)), CometChatCalls.addEventListener("onVideoResumed", () => setIsVideoOff(false)), ]; // Generate a call token for this session const tokenResult = await CometChatCalls.generateToken(sessionId); // Join the call session const joinResult = await CometChatCalls.joinSession( tokenResult.token, { sessionType: "VIDEO", layout: "TILE", startAudioMuted: false, startVideoPaused: false, }, containerRef.current ); if (joinResult.error) { throw new Error(joinResult.error.message); } } catch (err: any) { console.error("Failed to join call:", err); setError(err.message || "Failed to join call"); setIsJoining(false); } } joinCall(); // Cleanup when component unmounts return () => { unsubscribersRef.current.forEach((unsub) => unsub()); unsubscribersRef.current = []; CometChatCalls?.leaveSession(); }; }, [isReady, CometChatCalls, sessionId, onCallEnd]); // Control handlers const toggleAudio = () => { isMuted ? CometChatCalls.unmuteAudio() : CometChatCalls.muteAudio(); }; const toggleVideo = () => { isVideoOff ? CometChatCalls.resumeVideo() : CometChatCalls.pauseVideo(); }; const leaveCall = () => { CometChatCalls.leaveSession(); }; // Loading state if (!isReady) { return

Initializing...

; } // Error state if (error) { return (

Error: {error}

); } return (

{/* Video container - SDK renders the call UI here */}

{/* Loading overlay */} {isJoining && (

Joining call...

)} {/* Call controls */} {isJoined && (

)}

); } ``` ## Step 6: Create the Call Page Create a page that uses the call component. This example shows a simple interface where users can enter a session ID and join a call: ```tsx theme={null} // app/page.tsx "use client"; import { useState } from "react"; import { useCometChatCalls } from "@/providers/CometChatCallsProvider"; import CallScreen from "@/components/CallScreen"; export default function HomePage() { const { isReady, user, error } = useCometChatCalls(); const [sessionId, setSessionId] = useState(""); const [isInCall, setIsInCall] = useState(false); if (error) { return (

Error: {error}

); } if (!isReady) { return (

); } if (isInCall) { return ( setIsInCall(false)} /> ); } return (

CometChat Calls

Logged in as: {user?.name || user?.uid}

setSessionId(e.target.value)} className="w-full p-3 border rounded-lg" />

); } ``` ## Dynamic Route for Call Sessions For a cleaner URL structure, create a dynamic route that accepts the session ID as a parameter: ```tsx theme={null} // app/call/[sessionId]/page.tsx "use client"; import { useParams, useRouter } from "next/navigation"; import CallScreen from "@/components/CallScreen"; export default function CallPage() { const params = useParams(); const router = useRouter(); const sessionId = params.sessionId as string; return ( router.push("/")} /> ); } ``` ## Pages Router Setup If you're using the Pages Router instead of the App Router, use dynamic imports to prevent server-side rendering of the SDK: ```tsx theme={null} // pages/_app.tsx import type { AppProps } from "next/app"; import dynamic from "next/dynamic"; const CometChatCallsProvider = dynamic( () => import("@/providers/CometChatCallsProvider").then(mod => mod.CometChatCallsProvider), { ssr: false } ); export default function App({ Component, pageProps }: AppProps) { const currentUserId = "cometchat-uid-1"; return ( ); } ``` ```tsx theme={null} // pages/call/[sessionId].tsx import dynamic from "next/dynamic"; import { useRouter } from "next/router"; const CallScreen = dynamic(() => import("@/components/CallScreen"), { ssr: false, loading: () =>

Loading call...

, }); export default function CallPage() { const router = useRouter(); const { sessionId } = router.query; if (!sessionId) { return

; } return ( router.push("/")} /> ); } ``` ## Custom Hook (Optional) For more complex applications, extract call logic into a reusable hook: ```tsx theme={null} // hooks/useCall.ts "use client"; import { useState, useCallback, useRef, useEffect } from "react"; import { useCometChatCalls } from "@/providers/CometChatCallsProvider"; export function useCall() { const { CometChatCalls, isReady } = useCometChatCalls(); const [isInCall, setIsInCall] = useState(false); const [isMuted, setIsMuted] = useState(false); const [isVideoOff, setIsVideoOff] = useState(false); const [participants, setParticipants] = useState([]); const unsubscribersRef = useRef([]); const joinCall = useCallback(async (sessionId: string, container: HTMLElement, settings = {}) => { if (!CometChatCalls) return; // Setup listeners unsubscribersRef.current = [ CometChatCalls.addEventListener("onAudioMuted", () => setIsMuted(true)), CometChatCalls.addEventListener("onAudioUnMuted", () => setIsMuted(false)), CometChatCalls.addEventListener("onVideoPaused", () => setIsVideoOff(true)), CometChatCalls.addEventListener("onVideoResumed", () => setIsVideoOff(false)), CometChatCalls.addEventListener("onParticipantListChanged", setParticipants), CometChatCalls.addEventListener("onSessionLeft", () => setIsInCall(false)), ]; const tokenResult = await CometChatCalls.generateToken(sessionId); await CometChatCalls.joinSession( tokenResult.token, { sessionType: "VIDEO", layout: "TILE", ...settings }, container ); setIsInCall(true); }, [CometChatCalls]); const leaveCall = useCallback(() => { CometChatCalls?.leaveSession(); unsubscribersRef.current.forEach((unsub) => unsub()); unsubscribersRef.current = []; setIsInCall(false); }, [CometChatCalls]); const toggleAudio = useCallback(() => { isMuted ? CometChatCalls?.unmuteAudio() : CometChatCalls?.muteAudio(); }, [CometChatCalls, isMuted]); const toggleVideo = useCallback(() => { isVideoOff ? CometChatCalls?.resumeVideo() : CometChatCalls?.pauseVideo(); }, [CometChatCalls, isVideoOff]); // Cleanup on unmount useEffect(() => { return () => { unsubscribersRef.current.forEach((unsub) => unsub()); }; }, []); return { isReady, isInCall, isMuted, isVideoOff, participants, joinCall, leaveCall, toggleAudio, toggleVideo, }; } ``` ## Related Documentation For more detailed information on specific topics covered in this guide, refer to the main documentation: * [Setup](/docs/calls/javascript/setup) - Detailed SDK installation and initialization * [Authentication](/docs/calls/javascript/authentication) - Login methods and user management * [Session Settings](/docs/calls/javascript/session-settings) - All available call configuration options * [Join Session](/docs/calls/javascript/join-session) - Session joining and token generation * [Events](/docs/calls/javascript/events) - Complete list of event listeners * [Actions](/docs/calls/javascript/actions) - All available call control methods * [Call Layouts](/docs/calls/javascript/call-layouts) - Layout options and customization * [Participant Management](/docs/calls/javascript/participant-management) - Managing call participants # Calls SDK Source: https://www.cometchat.com/docs/calls/javascript/overview Use CometChat Calls SDK v5 for JavaScript to add voice and video calling, call sessions, participants, layouts, and in-call features. The CometChat Calls SDK enables real-time voice and video calling capabilities in your web application. Built on top of WebRTC, it provides a complete calling solution with built-in UI components and extensive customization options. ## Prerequisites Before integrating the Calls SDK, ensure you have: 1. **CometChat Account**: [Sign up](https://app.cometchat.com/signup) and create an app to get your App ID, Region, and API Key 2. **CometChat Users**: Users must exist in CometChat to use calling features. For testing, create users via the [Dashboard](https://app.cometchat.com) or [REST API](/docs/rest-api/users/create). Authentication is handled by the Calls SDK - see [Authentication](/docs/calls/javascript/authentication) 3. **Browser Requirements**: See [Browser Compatibility](#browser-compatibility) below 4. **Permissions**: Camera and microphone permissions for video/audio calls ## Browser Compatibility The Calls SDK requires a modern browser with WebRTC support: | Browser | Minimum Version | Notes | | - | - | - | | Chrome | 72+ | Full support | | Firefox | 68+ | Full support | | Safari | 12.1+ | Full support | | Edge | 79+ | Chromium-based | | Opera | 60+ | Full support | | Samsung Internet | 12+ | Full support | ### Requirements * **HTTPS**: Required for camera/microphone access in production. Localhost is exempt during development. * **WebRTC**: The browser must support WebRTC APIs (`getUserMedia`, `RTCPeerConnection`) * **JavaScript**: ES6+ support required ### Mobile Browsers | Browser | Support | | - | - | | Chrome for Android | ✅ Full support | | Safari for iOS | ✅ iOS 12.1+ | | Firefox for Android | ✅ Full support | | Samsung Internet | ✅ Full support | > [!NOTE] > > For native mobile apps, consider using the [iOS](/docs/calls/ios/overview) or [Android](/docs/calls/android/overview) SDKs for better performance and native features like CallKit/VoIP. ## Framework Integrations Get started quickly with framework-specific guides that include complete setup, authentication, and working call implementations: > [card] [React](/docs/calls/javascript/react-integration) > > Context provider pattern with hooks > [card] [Vue](/docs/calls/javascript/vue-integration) > > Composables and reactive state management > [card] [Angular](/docs/calls/javascript/angular-integration) > > Service-based architecture with RxJS > [card] [Next.js](/docs/calls/javascript/nextjs-integration) > > SSR handling with App Router and Pages Router > [card] [Ionic](/docs/calls/javascript/ionic-integration) > > Cross-platform with Angular, React, and Vue ## Call Flow ```mermaid theme={null} sequenceDiagram participant App participant CometChatCalls App->>CometChatCalls: init() App->>CometChatCalls: login() App->>CometChatCalls: generateToken() App->>CometChatCalls: joinSession() CometChatCalls-->>App: Session joined App->>CometChatCalls: Actions (mute, pause, etc.) CometChatCalls-->>App: Event callbacks App->>CometChatCalls: leaveSession() ``` Every call is a session joined by ID. Where the ID comes from depends on the kind of call: * **Direct call**: your app shares a session ID (for example in a message) and each participant generates a token and calls `joinSession` with it. Group calls and meetings work this way. * **Ringing call**: the caller starts it with `CometChatCalls.initiateCall`, the callee's open tabs receive it through the Chat SDK and prepare it with `CometChatCalls.connect`, and both sides join the prepared session with `session.join(container)` once the callee answers. See [Ringing](/docs/calls/javascript/ringing). ## Features > [card] [Ringing](/docs/calls/javascript/ringing) > > Start a call, ring the callee's open tabs and phones, show "Ringing…", answer, decline, cancel and end > [card] [Call Layouts](/docs/calls/javascript/call-layouts) > > Tile, Sidebar, and Spotlight view modes for different call scenarios > [card] [Recording](/docs/calls/javascript/recording) > > Record call sessions for later playback > [card] [Call Logs](/docs/calls/javascript/call-logs) > > Retrieve call history and details > [card] [Participant Management](/docs/calls/javascript/participant-management) > > Mute, pin, and manage call participants > [card] [Screen Sharing](/docs/calls/javascript/screen-sharing) > > Share your screen with other participants > [card] [Virtual Background](/docs/calls/javascript/virtual-background) > > Apply blur or custom image backgrounds > [card] [Raise Hand](/docs/calls/javascript/raise-hand) > > Signal to get attention during calls > [card] [Idle Timeout](/docs/calls/javascript/idle-timeout) > > Automatic session termination when alone in a call ## Architecture The SDK is organized around these core components: | Component | Description | | - | - | | `CometChatCalls` | Main entry point for SDK initialization, authentication, session management, and call actions | | `CallAppSettings` | Configuration object for SDK initialization (App ID, Region) | | `CallSettings` | Configuration object for individual call sessions | | `CallSession` | The session object `initiateCall`, `connect` and `getActiveSession()` return: `sessionId`, `prepareStatus`, `join(container)`, `leave()` and every session action | | `addEventListener` | Method to register event listeners for session, participant, media, and UI events | ## Single Active Session `CometChatCalls` is a singleton, and it tracks one active call session at a time. Every session method acts on that current session, which is why methods like `leaveSession()` take no session ID: ```javascript theme={null} // Joins and becomes the active session await CometChatCalls.joinSession(callToken, callSettings, container); // Acts on whatever session is currently active - no session ID needed CometChatCalls.leaveSession(); ``` | Behavior | Detail | | - | - | | One session at a time | The SDK does not support being connected to two sessions simultaneously. Leave the current session before joining another. A session that is only prepared (an outgoing call still ringing) counts too: `joinSession` refuses to run while it exists. | | Session methods take no session ID | `leaveSession()` and the other [actions](/docs/calls/javascript/actions) apply to the active session only. | | Actions apply to the active session | `muteAudio()`, `pauseVideo()`, `startScreenShare()`, and similar methods target the session currently in progress. | | Events are not session-scoped | Listeners registered with `addEventListener` fire for the active session. | To move a user from one call to another, leave the current session, wait for the `onSessionLeft` event, then generate a token for the new session and join: ```javascript theme={null} CometChatCalls.addEventListener("onSessionLeft", async () => { const { token } = await CometChatCalls.generateToken(nextSessionId); await CometChatCalls.joinSession(token, callSettings, container); }); CometChatCalls.leaveSession(); ``` > [!NOTE] > > The limit applies per SDK instance. Separate browser tabs or windows each load their own instance, so they can hold separate sessions independently. ## Sample App > [card] [React](https://github.com/cometchat/calls-sdk-javascript/tree/v5/sample-apps/cometchat-calls-sample-app-react) > > React sample app > [card] [Angular](https://github.com/cometchat/calls-sdk-javascript/tree/v5/sample-apps/cometchat-calls-sample-app-angular) > > Angular sample app > [card] [Vue](https://github.com/cometchat/calls-sdk-javascript/tree/v5/sample-apps/cometchat-calls-sample-app-vue) > > Vue sample app > [card] [Svelte](https://github.com/cometchat/calls-sdk-javascript/tree/v5/sample-apps/cometchat-calls-sample-app-svelte) > > Svelte sample app > [card] [Ionic](https://github.com/cometchat/calls-sdk-javascript/tree/v5/sample-apps/cometchat-calls-sample-app-ionic) > > Ionic sample app > [card] [Changelog](https://github.com/cometchat/calls-sdk-javascript/releases) > > View the latest releases and changes # Participant Management Source: https://www.cometchat.com/docs/calls/javascript/participant-management Manage CometChat Calls SDK v5 participants on JavaScript with mute, pause video, pinning, permissions, and participant events. Manage call participants including muting, pinning, and monitoring their status during a call. ## Participant Actions ### Mute Participant Mute a specific participant's audio. This is typically a moderator action. ```javascript theme={null} CometChatCalls.muteParticipant(participantId); ``` | Parameter | Type | Description | | - | - | - | | `participantId` | String | The participant's unique identifier | ### Pause Participant Video Pause a specific participant's video. This is typically a moderator action. ```javascript theme={null} CometChatCalls.pauseParticipantVideo(participantId); ``` | Parameter | Type | Description | | - | - | - | | `participantId` | String | The participant's unique identifier | ### Pin Participant Pin a participant to keep them prominently displayed regardless of who is speaking. ```javascript theme={null} CometChatCalls.pinParticipant(participantId, type); ``` | Parameter | Type | Description | | - | - | - | | `participantId` | String | The participant's unique identifier | | `type` | String | The participant type | ### Unpin Participant Remove the pin, returning to automatic speaker highlighting. ```javascript theme={null} CometChatCalls.unpinParticipant(); ``` ## Participant Events ### Participant Joined Fired when a participant joins the call: ```javascript theme={null} CometChatCalls.addEventListener("onParticipantJoined", (participant) => { console.log(`${participant.name} joined the call`); }); ``` ### Participant Left Fired when a participant leaves the call: ```javascript theme={null} CometChatCalls.addEventListener("onParticipantLeft", (participant) => { console.log(`${participant.name} left the call`); }); ``` ### Participant List Changed Fired when the participant list is updated: ```javascript theme={null} CometChatCalls.addEventListener("onParticipantListChanged", (participants) => { console.log(`Total participants: ${participants.length}`); participants.forEach(p => console.log(p.name)); }); ``` ### Participant Audio State Monitor when participants mute or unmute: ```javascript theme={null} CometChatCalls.addEventListener("onParticipantAudioMuted", (participant) => { console.log(`${participant.name} muted their audio`); }); CometChatCalls.addEventListener("onParticipantAudioUnmuted", (participant) => { console.log(`${participant.name} unmuted their audio`); }); ``` ### Participant Video State Monitor when participants turn their camera on or off: ```javascript theme={null} CometChatCalls.addEventListener("onParticipantVideoPaused", (participant) => { console.log(`${participant.name} turned off their camera`); }); CometChatCalls.addEventListener("onParticipantVideoResumed", (participant) => { console.log(`${participant.name} turned on their camera`); }); ``` ### Dominant Speaker Changed Fired when the active speaker changes: ```javascript theme={null} CometChatCalls.addEventListener("onDominantSpeakerChanged", (participant) => { console.log(`Active speaker: ${participant.name}`); }); ``` ## Participant List UI ### Show/Hide Participant List Button Control visibility of the participant list button: ```javascript theme={null} const callSettings = { hideParticipantListButton: false, // Show the button // ... other settings }; ``` ### Listen for Participant List Events Monitor when the participant list panel is opened or closed: ```javascript theme={null} CometChatCalls.addEventListener("onParticipantListVisible", () => { console.log("Participant list opened"); }); CometChatCalls.addEventListener("onParticipantListHidden", () => { console.log("Participant list closed"); }); ``` ### Listen for Participant List Button Clicks Intercept participant list button clicks: ```javascript theme={null} CometChatCalls.addEventListener("onParticipantListButtonClicked", () => { console.log("Participant list button clicked"); }); ``` ## Participant Object | Property | Type | Description | | - | - | - | | `uid` | String | Unique identifier (CometChat user ID) | | `name` | String | Display name | | `avatar` | String | URL of avatar image | # Permissions Handling Source: https://www.cometchat.com/docs/calls/javascript/permissions-handling Handle browser camera, microphone, and screen permissions for CometChat Calls SDK v5 in JavaScript calling apps. Handle camera and microphone permissions gracefully to provide a good user experience when joining calls. ## Permission Requirements The Calls SDK requires: * **Microphone**: Required for audio calls * **Camera**: Required for video calls (optional for audio-only) ## Check Permissions Before Joining Check if permissions are granted before attempting to join a call: ```javascript theme={null} async function checkMediaPermissions() { try { const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true }); // Stop the tracks immediately - we just needed to check permissions stream.getTracks().forEach(track => track.stop()); return { video: true, audio: true }; } catch (error) { if (error.name === "NotAllowedError") { return { video: false, audio: false, denied: true }; } if (error.name === "NotFoundError") { return { video: false, audio: false, notFound: true }; } throw error; } } ``` ## Query Permission Status Use the Permissions API to check status without prompting: ```javascript theme={null} async function getPermissionStatus() { const permissions = {}; try { const camera = await navigator.permissions.query({ name: "camera" }); permissions.camera = camera.state; // "granted", "denied", or "prompt" const microphone = await navigator.permissions.query({ name: "microphone" }); permissions.microphone = microphone.state; } catch (error) { // Permissions API not supported permissions.supported = false; } return permissions; } // Usage const status = await getPermissionStatus(); if (status.camera === "denied" || status.microphone === "denied") { showPermissionDeniedMessage(); } ``` ## Handle Permission Denial Show helpful messages when permissions are denied: ```javascript theme={null} async function joinCallWithPermissionCheck(sessionId, container) { const permissions = await checkMediaPermissions(); if (permissions.denied) { showError( "Camera and microphone access denied. " + "Please enable permissions in your browser settings and refresh the page." ); return; } if (permissions.notFound) { showError( "No camera or microphone found. " + "Please connect a device and try again." ); return; } // Permissions granted, proceed with joining const tokenResult = await CometChatCalls.generateToken(sessionId); await CometChatCalls.joinSession(tokenResult.token, { sessionType: "VIDEO" }, container); } ``` ## Permission Request UI Create a pre-call permission check screen: ```javascript theme={null} function PermissionCheck({ onPermissionsGranted, onPermissionsDenied }) { const [status, setStatus] = useState("checking"); useEffect(() => { checkPermissions(); }, []); async function checkPermissions() { const result = await checkMediaPermissions(); if (result.video && result.audio) { setStatus("granted"); onPermissionsGranted(); } else if (result.denied) { setStatus("denied"); onPermissionsDenied(); } else { setStatus("prompt"); } } async function requestPermissions() { setStatus("requesting"); const result = await checkMediaPermissions(); if (result.video && result.audio) { setStatus("granted"); onPermissionsGranted(); } else { setStatus("denied"); onPermissionsDenied(); } } if (status === "checking") { return

Checking permissions...

; } if (status === "prompt") { return (

We need access to your camera and microphone for the call.

); } if (status === "denied") { return (

Camera and microphone access was denied.

To join the call, please:

Click the camera icon in your browser's address bar
Select "Allow" for camera and microphone
Refresh this page

); } return null; } ``` ## Listen for Permission Changes Monitor permission changes in real-time: ```javascript theme={null} async function watchPermissions(onChange) { try { const camera = await navigator.permissions.query({ name: "camera" }); const microphone = await navigator.permissions.query({ name: "microphone" }); camera.addEventListener("change", () => { onChange({ camera: camera.state, microphone: microphone.state }); }); microphone.addEventListener("change", () => { onChange({ camera: camera.state, microphone: microphone.state }); }); } catch (error) { console.log("Permission watching not supported"); } } // Usage watchPermissions((status) => { if (status.camera === "denied" || status.microphone === "denied") { // Handle permission revocation during call showWarning("Permissions were revoked. Some features may not work."); } }); ``` ## HTTPS Requirement Camera and microphone access requires a secure context: ```javascript theme={null} function isSecureContext() { // Localhost is considered secure for development if (window.location.hostname === "localhost" || window.location.hostname === "127.0.0.1") { return true; } return window.location.protocol === "https:"; } if (!isSecureContext()) { showError("Video calls require HTTPS. Please access this page via HTTPS."); } ``` ## Browser-Specific Instructions Provide browser-specific help for enabling permissions: ```javascript theme={null} function getBrowserPermissionInstructions() { const ua = navigator.userAgent; if (ua.includes("Chrome")) { return { browser: "Chrome", steps: [ "Click the lock/camera icon in the address bar", "Set Camera and Microphone to 'Allow'", "Refresh the page" ] }; } if (ua.includes("Firefox")) { return { browser: "Firefox", steps: [ "Click the permissions icon (camera/lock) in the address bar", "Remove the block for camera and microphone", "Refresh the page" ] }; } if (ua.includes("Safari")) { return { browser: "Safari", steps: [ "Go to Safari > Settings > Websites", "Select Camera and Microphone", "Set this website to 'Allow'", "Refresh the page" ] }; } return { browser: "your browser", steps: [ "Check your browser settings for camera and microphone permissions", "Allow access for this website", "Refresh the page" ] }; } ``` ## Audio-Only Fallback If camera permission is denied but microphone is available, offer audio-only mode: ```javascript theme={null} async function joinWithFallback(sessionId, container) { let hasVideo = false; let hasAudio = false; // Check audio try { const audioStream = await navigator.mediaDevices.getUserMedia({ audio: true }); audioStream.getTracks().forEach(track => track.stop()); hasAudio = true; } catch (e) { console.log("No audio permission"); } // Check video try { const videoStream = await navigator.mediaDevices.getUserMedia({ video: true }); videoStream.getTracks().forEach(track => track.stop()); hasVideo = true; } catch (e) { console.log("No video permission"); } if (!hasAudio) { showError("Microphone access is required to join the call."); return; } const tokenResult = await CometChatCalls.generateToken(sessionId); await CometChatCalls.joinSession(tokenResult.token, { sessionType: hasVideo ? "VIDEO" : "VOICE", startVideoPaused: !hasVideo, }, container); if (!hasVideo) { showInfo("Joined in audio-only mode. Enable camera permission for video."); } } ``` # Raise Hand Source: https://www.cometchat.com/docs/calls/javascript/raise-hand Add raise hand behavior in CometChat Calls SDK v5 on JavaScript so participants can request attention during group calls. The raise hand feature allows participants to signal that they want to speak or get attention during a call without interrupting the current speaker. ## Raise Hand Show a hand-raised indicator to other participants: ```javascript theme={null} CometChatCalls.raiseHand(); ``` ## Lower Hand Remove the hand-raised indicator: ```javascript theme={null} CometChatCalls.lowerHand(); ``` ## Raise Hand Events ### Participant Hand Raised Fired when a participant raises their hand: ```javascript theme={null} CometChatCalls.addEventListener("onParticipantHandRaised", (participant) => { console.log(`${participant.name} raised their hand`); // Show notification or update UI }); ``` ### Participant Hand Lowered Fired when a participant lowers their hand: ```javascript theme={null} CometChatCalls.addEventListener("onParticipantHandLowered", (participant) => { console.log(`${participant.name} lowered their hand`); }); ``` ## Raise Hand Button ### Hide Raise Hand Button To hide the raise hand button from the control panel: ```javascript theme={null} const callSettings = { hideRaiseHandButton: true, // ... other settings }; ``` ### Listen for Button Clicks Intercept raise hand button clicks for custom behavior: ```javascript theme={null} CometChatCalls.addEventListener("onRaiseHandButtonClicked", () => { console.log("Raise hand button clicked"); }); ``` # React Integration Source: https://www.cometchat.com/docs/calls/javascript/react-integration Integrate CometChat Calls SDK v5 in React apps with package setup, initialization, call UI rendering, and component usage. This guide walks you through integrating the CometChat Calls SDK into a React application. By the end, you'll have a working video call implementation with proper state management and lifecycle handling. ## Prerequisites Before you begin, ensure you have: * A CometChat account with an app created ([Sign up](https://app.cometchat.com/signup)) * Your App ID, Region, and API Key from the CometChat Dashboard * A React project (Create React App, Vite, or similar) * Node.js 16+ installed ## Step 1: Install the SDK Install the CometChat Calls SDK package: ```bash theme={null} npm install @cometchat/calls-sdk-javascript ``` ## Step 2: Initialize and Login Create a provider component to handle SDK initialization and authentication. This ensures the SDK is ready before any call components render. ```jsx theme={null} // src/providers/CometChatCallsProvider.jsx import { createContext, useContext, useEffect, useState } from "react"; import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; const CometChatCallsContext = createContext({ isReady: false, user: null, error: null, }); const APP_ID = "YOUR_APP_ID"; // Replace with your App ID const REGION = "YOUR_REGION"; // Replace with your Region (us, eu, in) const API_KEY = "YOUR_API_KEY"; // Replace with your API Key export function CometChatCallsProvider({ children, uid }) { const [isReady, setIsReady] = useState(false); const [user, setUser] = useState(null); const [error, setError] = useState(null); useEffect(() => { async function initAndLogin() { try { // Step 1: Initialize the SDK const initResult = await CometChatCalls.init({ appId: APP_ID, region: REGION, }); if (!initResult.success) { throw new Error("SDK initialization failed"); } // Step 2: Check if already logged in let loggedInUser = CometChatCalls.getLoggedInUser(); // Step 3: Login if not already logged in if (!loggedInUser) { loggedInUser = await CometChatCalls.login(uid, API_KEY); } setUser(loggedInUser); setIsReady(true); } catch (err) { console.error("CometChat Calls setup failed:", err); setError(err.message || "Setup failed"); } } if (uid) { initAndLogin(); } }, [uid]); return ( {children} ); } export function useCometChatCalls() { return useContext(CometChatCallsContext); } ``` ## Step 3: Wrap Your App Add the provider to your app's root component: ```jsx theme={null} // src/App.jsx import { CometChatCallsProvider } from "./providers/CometChatCallsProvider"; import CallPage from "./pages/CallPage"; function App() { // In a real app, get this from your authentication system const currentUserId = "cometchat-uid-1"; return ( ); } export default App; ``` ## Step 4: Create the Call Component Build a call component that handles joining, controls, and cleanup: ```jsx theme={null} // src/components/CallScreen.jsx import { useEffect, useRef, useState } from "react"; import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; import { useCometChatCalls } from "../providers/CometChatCallsProvider"; export default function CallScreen({ sessionId, onCallEnd }) { const { isReady } = useCometChatCalls(); const containerRef = useRef(null); // Call state const [isJoined, setIsJoined] = useState(false); const [isJoining, setIsJoining] = useState(false); const [isMuted, setIsMuted] = useState(false); const [isVideoOff, setIsVideoOff] = useState(false); const [error, setError] = useState(null); // Store unsubscribe functions for cleanup const unsubscribersRef = useRef([]); useEffect(() => { // Don't proceed if SDK isn't ready or container isn't mounted if (!isReady || !containerRef.current || !sessionId) return; async function joinCall() { setIsJoining(true); setError(null); try { // Register event listeners before joining unsubscribersRef.current = [ CometChatCalls.addEventListener("onSessionJoined", () => { setIsJoined(true); setIsJoining(false); }), CometChatCalls.addEventListener("onSessionLeft", () => { setIsJoined(false); onCallEnd?.(); }), CometChatCalls.addEventListener("onAudioMuted", () => setIsMuted(true)), CometChatCalls.addEventListener("onAudioUnMuted", () => setIsMuted(false)), CometChatCalls.addEventListener("onVideoPaused", () => setIsVideoOff(true)), CometChatCalls.addEventListener("onVideoResumed", () => setIsVideoOff(false)), ]; // Generate a call token for this session const tokenResult = await CometChatCalls.generateToken(sessionId); // Join the call session const joinResult = await CometChatCalls.joinSession( tokenResult.token, { sessionType: "VIDEO", layout: "TILE", startAudioMuted: false, startVideoPaused: false, }, containerRef.current ); if (joinResult.error) { throw new Error(joinResult.error.message); } } catch (err) { console.error("Failed to join call:", err); setError(err.message || "Failed to join call"); setIsJoining(false); } } joinCall(); // Cleanup when component unmounts return () => { unsubscribersRef.current.forEach((unsub) => unsub()); unsubscribersRef.current = []; CometChatCalls.leaveSession(); }; }, [isReady, sessionId, onCallEnd]); // Control handlers const toggleAudio = () => { isMuted ? CometChatCalls.unmuteAudio() : CometChatCalls.muteAudio(); }; const toggleVideo = () => { isVideoOff ? CometChatCalls.resumeVideo() : CometChatCalls.pauseVideo(); }; const leaveCall = () => { CometChatCalls.leaveSession(); }; // Loading state if (!isReady) { return

Initializing...

; } // Error state if (error) { return (

Error: {error}

); } return (

{/* Video container - SDK renders the call UI here */}

{/* Loading overlay */} {isJoining && (

Joining call...

)} {/* Call controls */} {isJoined && (

)}

); } ``` ## Step 5: Use the Call Component Create a page that uses the call component: ```jsx theme={null} // src/pages/CallPage.jsx import { useState } from "react"; import { useCometChatCalls } from "../providers/CometChatCallsProvider"; import CallScreen from "../components/CallScreen"; export default function CallPage() { const { isReady, user, error } = useCometChatCalls(); const [sessionId, setSessionId] = useState(""); const [isInCall, setIsInCall] = useState(false); if (error) { return

Error: {error}

; } if (!isReady) { return

; } if (isInCall) { return ( setIsInCall(false)} /> ); } return (

CometChat Calls

Logged in as: {user?.name || user?.uid}

setSessionId(e.target.value)} style={{ width: "100%", padding: "12px", marginBottom: "10px" }} />

); } ``` ## Custom Hook (Optional) For more complex applications, extract call logic into a reusable hook: ```jsx theme={null} // src/hooks/useCall.js import { useState, useCallback, useRef, useEffect } from "react"; import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; export function useCall() { const [isInCall, setIsInCall] = useState(false); const [isMuted, setIsMuted] = useState(false); const [isVideoOff, setIsVideoOff] = useState(false); const [participants, setParticipants] = useState([]); const unsubscribersRef = useRef([]); const joinCall = useCallback(async (sessionId, container, settings = {}) => { // Setup listeners unsubscribersRef.current = [ CometChatCalls.addEventListener("onAudioMuted", () => setIsMuted(true)), CometChatCalls.addEventListener("onAudioUnMuted", () => setIsMuted(false)), CometChatCalls.addEventListener("onVideoPaused", () => setIsVideoOff(true)), CometChatCalls.addEventListener("onVideoResumed", () => setIsVideoOff(false)), CometChatCalls.addEventListener("onParticipantListChanged", setParticipants), CometChatCalls.addEventListener("onSessionLeft", () => setIsInCall(false)), ]; const tokenResult = await CometChatCalls.generateToken(sessionId); await CometChatCalls.joinSession( tokenResult.token, { sessionType: "VIDEO", layout: "TILE", ...settings }, container ); setIsInCall(true); }, []); const leaveCall = useCallback(() => { CometChatCalls.leaveSession(); unsubscribersRef.current.forEach((unsub) => unsub()); unsubscribersRef.current = []; setIsInCall(false); }, []); const toggleAudio = useCallback(() => { isMuted ? CometChatCalls.unmuteAudio() : CometChatCalls.muteAudio(); }, [isMuted]); const toggleVideo = useCallback(() => { isVideoOff ? CometChatCalls.resumeVideo() : CometChatCalls.pauseVideo(); }, [isVideoOff]); // Cleanup on unmount useEffect(() => { return () => { unsubscribersRef.current.forEach((unsub) => unsub()); }; }, []); return { isInCall, isMuted, isVideoOff, participants, joinCall, leaveCall, toggleAudio, toggleVideo, }; } ``` ## TypeScript Support The SDK includes TypeScript definitions. Here's a typed version of the provider: ```tsx theme={null} // src/providers/CometChatCallsProvider.tsx import { createContext, useContext, useEffect, useState, ReactNode } from "react"; import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; interface User { uid: string; name: string; avatar?: string; } interface CometChatCallsContextType { isReady: boolean; user: User | null; error: string | null; } const CometChatCallsContext = createContext({ isReady: false, user: null, error: null, }); interface ProviderProps { children: ReactNode; uid: string; } export function CometChatCallsProvider({ children, uid }: ProviderProps) { // ... same implementation as above } export function useCometChatCalls(): CometChatCallsContextType { return useContext(CometChatCallsContext); } ``` ## Related Documentation For more detailed information on specific topics covered in this guide, refer to the main documentation: * [Setup](/docs/calls/javascript/setup) - Detailed SDK installation and initialization * [Authentication](/docs/calls/javascript/authentication) - Login methods and user management * [Session Settings](/docs/calls/javascript/session-settings) - All available call configuration options * [Join Session](/docs/calls/javascript/join-session) - Session joining and token generation * [Events](/docs/calls/javascript/events) - Complete list of event listeners * [Actions](/docs/calls/javascript/actions) - All available call control methods * [Call Layouts](/docs/calls/javascript/call-layouts) - Layout options and customization * [Participant Management](/docs/calls/javascript/participant-management) - Managing call participants # Recording Source: https://www.cometchat.com/docs/calls/javascript/recording Use CometChat Calls SDK v5 recording on JavaScript to start, stop, access, and manage recordings for supported call sessions. Record call sessions for later playback, compliance, or training purposes. Recordings are stored server-side and can be accessed through the CometChat dashboard. > [!NOTE] > > Recording is enabled by default on all CometChat apps. Start it automatically with `autoStartRecording: true`, or let users start it from the recording button. Recordings are available in the Dashboard under **Calls → Call Logs** and via the [Call Logs API](/docs/rest-api/calls-apis/list-calls). ## Auto-Start Recording Configure recording to start automatically when the session begins: ```javascript theme={null} const callSettings = { autoStartRecording: true, // ... other settings }; await CometChatCalls.joinSession(callToken, callSettings, container); ``` ## Manual Recording Control ### Start Recording Begin recording during an active call: ```javascript theme={null} CometChatCalls.startRecording(); ``` ### Stop Recording Stop the current recording: ```javascript theme={null} CometChatCalls.stopRecording(); ``` > [!NOTE] > > **A recording runs until it is stopped.** Whether it was started manually or automatically through `autoStartRecording`, it keeps running until someone stops it. If nobody does, it stops on its own when either: > > * Everyone leaves the session — the recording ends about a minute later. > * Everyone in the session stays muted for 10 minutes. ## Recording Events ### Recording Started Fired when recording begins: ```javascript theme={null} CometChatCalls.addEventListener("onRecordingStarted", () => { console.log("Recording started"); // Update UI to show recording indicator }); ``` ### Recording Stopped Fired when recording ends: ```javascript theme={null} CometChatCalls.addEventListener("onRecordingStopped", () => { console.log("Recording stopped"); // Update UI to hide recording indicator }); ``` ### Participant Recording Events Monitor when other participants start or stop recording: ```javascript theme={null} CometChatCalls.addEventListener("onParticipantStartedRecording", (participant) => { console.log(`${participant.name} started recording`); }); CometChatCalls.addEventListener("onParticipantStoppedRecording", (participant) => { console.log(`${participant.name} stopped recording`); }); ``` ## Recording Button Visibility By default, the recording button is hidden. To show it: ```javascript theme={null} const callSettings = { hideRecordingButton: false, // ... other settings }; ``` ## Listen for Recording Button Clicks Intercept recording button clicks for custom behavior: ```javascript theme={null} CometChatCalls.addEventListener("onRecordingToggleButtonClicked", () => { console.log("Recording button clicked"); // Add custom logic like confirmation dialogs }); ``` ## Accessing Recordings Recordings are available through: * The CometChat Dashboard under your app's call logs * The [Call Logs API](/docs/calls/api/list-calls) to retrieve call details including recording URLs # Ringing Source: https://www.cometchat.com/docs/calls/javascript/ringing Ring users from a web app with the CometChat Calls SDK: start a call, show it ringing, answer, decline, cancel and end it, and tell the caller why the ring ended. Ringing lets one user call another and lets the callee answer or decline. On the web, an incoming call rings in every open tab of your app where the callee is logged in. Two SDKs do the work: | SDK | Owns | | - | - | | **Calls SDK** (`@cometchat/calls-sdk-javascript` 5.1+) | Creating the call, preparing and joining the session, declining, cancelling, ending, and the call events your code listens to | | **Chat SDK** (`@cometchat/chat-sdk-javascript`) | Delivering an incoming call to an open tab: the call message arrives on the Chat SDK's real-time connection and is reported to `CometChat.addCallListener` | The web has no VoIP push. A tab that is closed does not ring, and your app plays the ringtone, shows the incoming-call screen and stops ringing when the ring is over. A callee on Android or iOS rings through the Push Notifications SDK. > [!NOTE] > > Web and mobile users can call each other when the mobile app also rings with the Calls SDK 5.1 and the Push Notifications SDK 2.0. Calls between an app on legacy ringing (the Chat SDK's calling methods) and an app on this flow ring once **Connect legacy ringing** is on in the CometChat dashboard; see [Migrating from Legacy Ringing](/docs/calls/javascript/migrating-from-legacy-ringing#while-some-users-are-still-on-legacy-ringing). > [!NOTE] > > **Coming from the earlier ringing flow?** The Chat SDK's calling methods (`CometChat.initiateCall`, `acceptCall`, `rejectCall`, `endCall`, `startCall`) are superseded by the Calls SDK and are no longer used. `CometChat.addCallListener` is the exception on the web: it is still how an incoming call reaches a tab. See [Migrating from legacy ringing](/docs/calls/javascript/migrating-from-legacy-ringing) for a method-by-method mapping. ## How ringing works The caller creates the call with the Calls SDK. The CometChat backend delivers the call message to the callee's open tabs through the Chat SDK, and to the callee's phones by push. The callee's tab rings and prepares the session while it rings; when the callee answers, it joins. The caller's app learns that the callee is ringing and has answered from the Calls SDK, without joining the session first. ```mermaid theme={null} sequenceDiagram participant A as Caller app participant BE as CometChat backend participant Chat as Callee · Chat SDK participant C as Callee · Calls SDK A->>BE: CometChatCalls.initiateCall(receiver, options) Note over A: Session prepared, not joined ("Calling…") BE-->>Chat: call message (initiated) Chat->>Chat: onIncomingCallReceived → your app rings Chat->>C: CometChatCalls.connect(sessionId, settings) C-->>A: onParticipantConnected → "Ringing…" C->>C: Answer → session.join(container) C-->>A: onParticipantJoined → caller joins too Note over A,C: In call. Hang up with session.leave() ``` What each side sees: | Stage | Caller | Callee (web) | | - | - | - | | Call created | `initiateCall` resolves; show "Calling…" | `onIncomingCallReceived` in each open tab; ring and call `connect` | | Callee's device reached | `onParticipantConnected` → show "Ringing…" | Ringing | | Callee answers | `onParticipantJoined` → `data.session.join(container)` | `session.join(container)` | | Callee declines / is busy / does not answer | The Chat SDK's `onOutgoingCallRejected`, with `call.getStatus()` saying why; also `onConnectionClosed` when the callee had prepared a 1:1 session. [Poll the status](#detect-a-decline-busy-or-no-answer) and keep your [ring timer](#ring-timeout) as a backstop | `endCall(sessionId, "rejected")` or `"busy"`; your own ring timer | | Caller cancels | — (you ended it) | `onIncomingCallCancelled`, or (1:1) `onConnectionClosed` on the prepared session; [poll the status](#stop-ringing-on-the-callee) as a backstop | | Either side hangs up | `onParticipantLeft` / `onSessionLeft` | same | > [!NOTE] > > The Calls SDK does not report why a ring ended. `endCall` records the status on the server, which sends it as a Chat SDK call message: a decline, busy or no answer reaches the caller as `CallListener.onOutgoingCallRejected` (`call.getStatus()` is `rejected`, `busy` or `unanswered`), and a cancel reaches the callee as `onIncomingCallCancelled`. A 1:1 decline from a callee whose device had prepared the session also closes the caller's prepared session (`onConnectionClosed`), which carries no reason. A tab can still miss a message (it was asleep in the background, or reconnecting), and if the caller's own prepare failed, the caller is not in the room and hears neither the ring nor the answer. So while the call rings, also read its status from the server every 3 seconds as a backstop, and keep the [ring timer](#ring-timeout). ## Prerequisites * [Calls SDK set up](/docs/calls/javascript/setup) and the user [logged in](/docs/calls/javascript/authentication) with `CometChatCalls.login` or `loginWithAuthToken`. `initiateCall`, `connect` and `endCall` need a logged-in Calls SDK user. * The Chat SDK (`@cometchat/chat-sdk-javascript` 4.2.1 or later) initialized and logged in as the **same user**, so that incoming calls, declines and cancels reach the tab. See [Chat SDK setup](/docs/sdk/javascript/setup-sdk). * HTTPS in production, for camera and microphone access. ```bash theme={null} npm install @cometchat/calls-sdk-javascript@5.1.0 @cometchat/chat-sdk-javascript@^4.2.1 ``` ## Start a call `CometChatCalls.initiateCall` creates the call on the backend, which rings the callee, and starts preparing the caller's session. The caller does **not** join yet. ```javascript theme={null} import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; const isGroup = false; // true to ring a group (see Group calls) const sessionSettings = { sessionType: "VOICE", // "VIDEO" for a video call isPeerCall: !isGroup, // 1:1: the call ends for both when either leaves }; const { data: call, error } = await CometChatCalls.initiateCall(receiverUid, { type: "audio", // or "video" (the default) receiverType: isGroup ? "group" : "user", sessionSettings, }); if (error) { console.error("Could not start the call:", error.name, error.message); } else { console.log("Calling", call.receiver, "session", call.sessionId); showOutgoingScreen(call); } ``` | Parameter | Description | | - | - | | `receiver` | UID of the user to call, or the group's GUID with `receiverType: "group"` (see [Group calls](#group-calls)) | | `options.type` | `"audio"` or `"video"` (default) | | `options.receiverType` | `"user"` (default) or `"group"` | | `options.sessionSettings` | The [session settings](/docs/calls/javascript/session-settings) the caller's session is prepared with. See the warning below | `initiateCall` never rejects. It resolves with `{ data, error }`: * `data` is the `InitiatedCall`: `sessionId`, `messageId` (the id of the call message in the conversation), `conversationId`, `sender`, `receiver`, `receiverType`, `type`, `status`, `initiatedAt` (in seconds) and `session`, the `CallSession` being prepared. * `error` is set when no call was created: `USER_NOT_LOGGED_IN`, `VALIDATION_ERROR` (no receiver), `SESSION_ALREADY_ACTIVE` (the user is joining or in another call; leave it first), `BAD_RESPONSE`, or the failure of the request. `initiateCall` resolves as soon as the call exists, before the caller's session has finished preparing: `call.session.prepareStatus` is `"pending"` at first. A failed prepare does not fail `initiateCall`, because the callee is already ringing; it shows on `call.session.prepareStatus` (`"failed"`) and `call.session.error`. After a failed prepare `call.session.join(container)` still performs a direct join, unless no call token came back with the call (it then resolves with `VALIDATION_ERROR`: generate a token and use `joinSession`, as `joinOutgoing` below does). > [!WARNING] > > **Always set the session type in `sessionSettings`, and `isPeerCall: true` for a 1:1 call.** The Calls SDK freezes the session settings when it prepares the session, and `session.join(container)` takes no settings: the ones you pass here are the ones the caller joins with. The default session type is video, so an audio call started without `sessionType: "VOICE"` opens the caller's camera. Without `isPeerCall`, a hang-up only removes one side from the room and the other side stays in it alone. ## Show "Ringing…" and detect the answer The caller stays on the session that `initiateCall` prepared and listens to it. Do not join yet: joining only when the callee has joined keeps the caller's camera and microphone off until there is someone to talk to. While the session is only prepared, the SDK still reports the callee's device reaching the room and the callee joining it. Listeners registered with `CometChatCalls.addEventListener` (or `call.session.addEventListener`) are global: they work before the prepare has finished and stay registered across sessions until you call the function they return. Register them right after `initiateCall` resolves, and check that the event belongs to the call on screen. ```javascript theme={null} // State of the outgoing call on screen. let answered = false; let cancelled = false; let ended = false; let stopWatching = () => {}; function watchOutgoingCall(call, container, isGroup) { const me = CometChatCalls.getLoggedInUser()?.uid; answered = cancelled = ended = false; const done = () => answered || cancelled || ended; // Every way the ring can end goes through here, once. const finish = (endText) => { if (done()) return; ended = true; stopWatching(); closeOutgoingScreen(endText); }; // The callee's device received the call and prepared the session: it is ringing there. const offConnected = CometChatCalls.addEventListener("onParticipantConnected", (participant) => { if (!done() && participant.uid !== me) setStatus("Ringing…"); // not one of your own devices }); // The callee answered: now the caller joins. const offJoined = CometChatCalls.addEventListener("onParticipantJoined", () => { if (done()) return; answered = true; stopWatching(); joinOutgoing(call, container); }); // The prepared session closed before anyone joined: the call is over. const offClosed = CometChatCalls.addEventListener("onConnectionClosed", async () => { if (done()) return; // The close carries no reason: ask the server (see the next section). finish(outgoingRingIsOver(await fetchCallStatus(call.sessionId)) ?? "Call ended"); }); // Read the call's status every 3 s (see the next section). const poll = setInterval(() => checkOutgoingStatus(call, container, finish), 3000); // Give up after 45 s (see Ring timeout). const ringTimer = setTimeout(() => { if (done()) return; // A group call is withdrawn ("cancelled"): "unanswered" is a 1:1 outcome. CometChatCalls.endCall(call.sessionId, isGroup ? "cancelled" : "unanswered"); finish("No answer"); }, 45_000); stopWatching = () => { offConnected(); offJoined(); offClosed(); clearInterval(poll); clearTimeout(ringTimer); }; } async function joinOutgoing(call, container) { const { error } = await call.session.join(container); if (error?.name === "VALIDATION_ERROR") { // No call token came with the call: generate one and join directly, // with the settings the call was started with. const { token } = await CometChatCalls.generateToken(call.sessionId); await CometChatCalls.joinSession(token, call.session.settings, container); } else if (error) { console.error("Join failed:", error); } } ``` | Event | On the prepared session it means | | - | - | | `onConnected` | Your own prepare finished; the join will be near-instant | | `onParticipantConnected(participant)` | The callee's device prepared the session: it is ringing there. `participant` carries `uid`, `name`, `pid` and `avatar` | | `onParticipantJoined(participant)` | The callee answered. Join now | | `onConnectionClosed` | The call ended before anyone joined (declined, cancelled, the room went away, or the prepared session expired after 5 minutes). It carries no reason. `onSessionTimedOut` is not part of this: it only reports an idle joined session | `call.session.join(container)` called while the prepare is still running waits for it. See [Join the session](#join-the-session). These events come from the room, so they only arrive while the caller's session is in it. If the caller's own prepare failed (`call.session.prepareStatus === "failed"`), neither arrives: the status poll below then reports the answer as `ongoing`. ## Detect a decline, busy or no answer A decline, busy or no answer reaches the caller as `onOutgoingCallRejected` on the Chat SDK's `CallListener`, with the reason in `call.getStatus()` (see [Receive a call](#receive-a-call)). As a backstop for a message the tab missed, and for an answer the caller cannot hear because its own prepare failed, also read the call's status from the server every 3 seconds from the moment `initiateCall` resolves until the call is answered, cancelled or times out (`watchOutgoingCall` above starts and stops the poll). Start at once, not only after "Ringing…": a callee who declines before their device prepared the session never sends `onParticipantConnected`. The status is the call's entry in [Call Logs](/docs/calls/javascript/call-logs), read with the logged-in user's auth token: ```javascript theme={null} const APP_ID = "APP_ID"; const REGION = "us"; // your app's region, in lower case async function fetchCallStatus(sessionId) { const authToken = CometChatCalls.getUserAuthToken(); if (!authToken) return null; const url = `https://${APP_ID}.call-${REGION}.cometchat.io/v3.0/calls/${encodeURIComponent(sessionId)}`; try { const response = await fetch(url, { headers: { accept: "application/json", appid: APP_ID, authtoken: authToken }, }); if (!response.ok) return null; const body = await response.json(); const entry = Array.isArray(body.data) ? body.data[0] : body.data; return entry?.status ?? null; } catch { return null; // offline or a failed request: keep ringing } } // What the caller's screen says, or null while the call still rings. function outgoingRingIsOver(status) { if (!status) return null; switch (status.toLowerCase()) { case "initiated": case "ongoing": // answered: handled separately return null; case "rejected": return "Declined"; case "busy": return "Busy"; default: return "Call ended"; } } // Called every 3 s by watchOutgoingCall until the ring ends. async function checkOutgoingStatus(call, container, finish) { const status = await fetchCallStatus(call.sessionId); if (answered || cancelled || ended) return; if (status?.toLowerCase() === "ongoing" && call.session.prepareStatus === "failed") { // Answered, but the caller is not in the room to hear onParticipantJoined. answered = true; stopWatching(); joinOutgoing(call, container); return; } const endText = outgoingRingIsOver(status); if (endText) finish(endText); } ``` > [!WARNING] > > `fetchCallStatus` calls a CometChat REST endpoint directly: the Calls SDK has no public method that returns a call's status, so this endpoint is not part of the SDK's API. The sample builds the URL for the default host, `{appId}.call-{region}.cometchat.io`; if your app initializes the Calls SDK with a custom host, build the URL from that host instead. Never end a call because the status could not be read: `null` means "keep ringing". The Chat SDK's `CallListener.onOutgoingCallRejected` carries the same outcome (`rejected`, `busy` or `unanswered`); end the screen on whichever arrives first (see [Receive a call](#receive-a-call) for filtering it). ## Receive a call On the web an incoming call arrives as a call message on the Chat SDK's real-time connection. Register a `CallListener` once, after the Chat SDK login, and remove it at logout. ```javascript theme={null} import { CometChat } from "@cometchat/chat-sdk-javascript"; const LISTENER_ID = "ringing"; const myUid = () => CometChatCalls.getLoggedInUser()?.uid; CometChat.addCallListener( LISTENER_ID, new CometChat.CallListener({ onIncomingCallReceived: (call) => { // The caller's own tabs receive their 1:1 call as "incoming" too. if (call.getCallInitiator()?.getUid() === myUid()) return; // A message delivered late (a sleeping tab, a reconnect) for a call that stopped ringing long ago. const initiatedAt = call.getInitiatedAt(); // seconds if (initiatedAt && Date.now() / 1000 - initiatedAt > 60) return; const isGroup = call.getReceiverType() === CometChat.RECEIVER_TYPE.GROUP; if (isBusy()) { // A 1:1 caller is told you are busy. A group call is just not shown. if (!isGroup) CometChatCalls.endCall(call.getSessionId(), "busy"); return; } ringIncomingCall(call); }, // The caller cancelled, or gave up ("unanswered"). A cancel reaches the caller's own tabs too. onIncomingCallCancelled: (call) => { stopRinging(call.getSessionId(), "over"); }, // A 1:1 "rejected" / "busy" reaches every tab of both users; "unanswered" reaches the caller. onOutgoingCallRejected: (call) => { if (call.getCallInitiator()?.getUid() === myUid()) { // Your own outgoing call: call.getStatus() is "rejected", "busy" or "unanswered". endOutgoingIfShowing(call.getSessionId(), call.getStatus()); } else { // Declined on another of your tabs or devices. stopRinging(call.getSessionId(), "over"); } }, }) ); // At logout: CometChat.removeCallListener(LISTENER_ID); ``` Your app does the ringing itself: play a ringtone, show the incoming-call screen, and, if the tab is in the background, show a browser notification (request the `Notification` permission on a user gesture, for example when the user places their first call). Browsers may block audio that starts without a user gesture on the page. `endCall(sessionId, "busy")` while the user is in another call leaves that other call untouched: `endCall` only tears down the live session when it is the call being ended. ## Prepare the ringing call As soon as the call rings, prepare its session with `CometChatCalls.connect`. Preparing is signalling only: no camera or microphone is opened and the caller does not see the callee in the call, but it is what turns the caller's screen to "Ringing…" and makes the answer near-instant. In a 1:1 call (`isPeerCall: true`) it also lets the caller's cancel reach this tab as `onConnectionClosed`, because the caller leaving a prepared peer session ends the room. ```javascript theme={null} // The incoming call on screen. state: "ringing" | "answered" | "over" | "elsewhere" let ring = null; function ringIncomingCall(call) { const thisRing = { call, state: "ringing" }; ring = thisRing; const sessionId = call.getSessionId(); showIncomingScreen(call); startRingtone(); startIncomingRingTimer(sessionId); CometChatCalls.connect(sessionId, { sessionType: call.getType() === "audio" ? "VOICE" : "VIDEO", isPeerCall: call.getReceiverType() !== CometChat.RECEIVER_TYPE.GROUP, }) .then((session) => { // The ring ended without an answer while the prepare ran: release it. if (thisRing.state === "over" && session.prepareStatus === "prepared" && !session.isSessionJoined()) { session.leave(); } }) .catch((error) => { // Answer falls back to a direct join; the status poll keeps watching the ring. console.warn("Preparing the call failed:", error); }); } ``` `connect(sessionId, sessionSettings)` resolves with the `CallSession` once the prepare has settled: `session.prepareStatus` is `"prepared"`, or `"cancelled"` when `leave()` was called meanwhile or a later `connect` for another session replaced it. Calling it again for the same session while it is preparing or prepared returns the same prepare. It rejects when the session could not be prepared, with one of two shapes: * `{ errorCode, errorDescription }` before the prepare starts: `ERROR_SESSION_ID_MISSING`, `ERROR_USER_NOT_LOGGED_IN`, or a failed call token request. * `{ name, message }` (`PrepareSessionException`) for everything after: a token verification, connection or conference failure, or `SESSION_ALREADY_ACTIVE` while another session is joined. The same error is left on `session.error`. The settings you pass to `connect` are frozen: they are the ones the callee joins with. A prepared session that nobody joins within 5 minutes is torn down: `onConnectionClosed` fires and `getActiveSession()` returns `null`, while `session.prepareStatus` stays `"prepared"` (it is `"failed"` with `PREPARE_TIMEOUT` only if the prepare had not finished connecting by then). `onSessionTimedOut` does not fire for it. > [!WARNING] > > **Leaving a prepared 1:1 session ends the room for everyone in it.** With `isPeerCall: true`, tearing down a prepared session that is in the room, whether by `leave()`, `endCall`, a `connect` or `initiateCall` for another session, or the 5-minute expiry, asks the server to end the room, not only to remove this tab. That is how a cancel or decline reaches the other side, and it does no harm once the ring is over. > > It is a problem when the call was answered in another tab or on another device: that tab's prepared session is still in the room of the live call. Do not call `leave()` on it. That only delays the problem: the 5-minute expiry, or the next `connect` or `initiateCall` in that tab, tears the session down the same way. The Calls SDK has no local-only leave for a prepared 1:1 session, so there is no client-side way around this. ### Stop ringing on the callee Stop ringing when any of these happens for the ringing call: * `onIncomingCallCancelled` arrives on the Chat SDK listener (the caller cancelled or gave up). * `onOutgoingCallRejected` arrives for a call you did not place (you declined it in another tab or on another device). * `onConnectionClosed` fires while the call is still ringing and this tab had prepared it (in a 1:1 call: the caller cancelled, or the call ended). * Your own ring timer runs out. * Another of your tabs tells you it answered or declined the call (see [Several tabs and devices](#several-tabs-and-devices)). * The call's status is no longer `initiated`. Poll it every 3 seconds while ringing, with the `fetchCallStatus` function above, as a backstop for a message this tab missed (it was asleep in the background, or reconnecting): `onConnectionClosed` only fires when the room is destroyed. ```javascript theme={null} // "over": the ring ended without an answer. "elsewhere": answered on another tab or device. function stopRinging(sessionId, reason) { if (!ring || ring.state !== "ringing" || ring.call.getSessionId() !== sessionId) return; ring.state = reason; stopRingtone(); stopIncomingRingTimer(); closeIncomingScreen(); // Release the prepared session only when the call is over (see the warning above). const session = CometChatCalls.getActiveSession(); if (reason === "over" && session?.sessionId === sessionId && !session.isSessionJoined()) { session.leave(); } } // From the status poll. A 1:1 call stops on anything but "initiated"; "ongoing" means it was answered // on another of the user's devices. A group call keeps ringing while it goes on, until it is over. function ringStatusReason(status, isGroup) { if (!status) return null; // could not read it: keep ringing const s = status.toLowerCase(); if (isGroup) return ["ended", "cancelled", "unanswered", "rejected"].includes(s) ? "over" : null; if (s === "initiated") return null; return s === "ongoing" ? "elsewhere" : "over"; } ``` ## Answer a call There is no separate "accept" call. Answering is joining the session the tab prepared; if the prepare failed, join directly. ```javascript theme={null} async function answer(container) { if (!ring || ring.state !== "ringing") return; ring.state = "answered"; const call = ring.call; const sessionId = call.getSessionId(); stopRingtone(); stopIncomingRingTimer(); tellOtherTabs("handled", sessionId); // The session this tab prepared: join waits for a prepare still running, and joins // directly with the frozen settings if the prepare failed after it started. const session = CometChatCalls.getActiveSession(); if (session?.sessionId === sessionId) { const { error } = await session.join(container); if (!error) return; if (error.name !== "VALIDATION_ERROR") return console.error("Join failed:", error); // VALIDATION_ERROR: no call token could be generated for the prepare; join directly below. } // Nothing prepared for this call (the prepare failed or never ran): join directly. const { token } = await CometChatCalls.generateToken(sessionId); const { error } = await CometChatCalls.joinSession(token, { sessionType: call.getType() === "audio" ? "VOICE" : "VIDEO", isPeerCall: call.getReceiverType() !== CometChat.RECEIVER_TYPE.GROUP, }, container); if (error) console.error("Join failed:", error); } ``` The browser asks for the camera and microphone when the session is joined, not when it is prepared. ## Join the session Both sides join the same way: the callee when the user answers, the caller from `onParticipantJoined`. `session.join(container)` mounts the call UI into `container` and takes no settings. | State of the session | What `session.join(container)` does | | - | - | | Prepared, or still preparing | The actual join, near-instant. `onSessionJoined` fires, then the camera and microphone open | | The prepare failed or expired, and nothing is live | A normal direct join with the settings frozen at prepare. If no call token was generated (`TOKEN_GENERATION_FAILED`, or none came back with `initiateCall`), it resolves with `VALIDATION_ERROR`: use `generateToken` and `joinSession` instead | | The prepare was cancelled (`leave()`) | Resolves with `SESSION_CANCELLED`: call `connect` again, or join directly | | Already joined | Resolves with success and does nothing | `session.join` resolves with `{ data, error }` like `joinSession`. `CometChatCalls.joinSession(token, settings, container)` refuses to run while a session is preparing or prepared (`SESSION_ALREADY_PREPARED`): join the prepared one with `session.join(container)`, or cancel it with `session.leave()` first. > [!NOTE] > > `CometChatCalls.getActiveSession()` returns the SDK's one `CallSession` while a session is preparing, prepared, being joined or joined: from the moment `connect` is called, or from the moment `initiateCall` has created the call. It returns `null` otherwise, including after a failed or cancelled prepare and after the 5-minute expiry. Always check it for `null` (`getActiveSession()?.leave()`), and compare `session.sessionId` with the call you mean: a later `connect` for another session re-points the same object, so an old reference describes the newer session. `sessionId` is set only for a session from `connect` or `initiateCall`; after a direct `joinSession` it is `null`. See [Join Session](/docs/calls/javascript/join-session) for the container, [Session Settings](/docs/calls/javascript/session-settings) for layouts and controls, and [Events](/docs/calls/javascript/events) for everything the joined session reports. ## Decline a call Decline a 1:1 call with `endCall` and the `rejected` status. When this tab had prepared the session, `endCall` first starts tearing it down (in a 1:1 call that asks the server to end the room), then tells the server the status. `onConnectionClosed` follows when the room closes. ```javascript theme={null} async function decline() { if (!ring || ring.state !== "ringing") return; ring.state = "over"; const call = ring.call; stopRingtone(); stopIncomingRingTimer(); closeIncomingScreen(); tellOtherTabs("handled", call.getSessionId()); if (call.getReceiverType() === CometChat.RECEIVER_TYPE.GROUP) { // A group call's decline is local: the call carries on for the other members. const session = CometChatCalls.getActiveSession(); if (session?.sessionId === call.getSessionId()) session.leave(); return; } const { error } = await CometChatCalls.endCall(call.getSessionId(), "rejected"); if (error) console.warn("Decline failed:", error); } ``` Use `"busy"` instead of `"rejected"` when the user is already in another call. `endCall(sessionId, status)` never rejects. It resolves with `{ data: undefined, error: null }` once the server has the new status, or with `error` set: `USER_NOT_LOGGED_IN`, `VALIDATION_ERROR` (no session ID), or the failure of the request. The status defaults to `"rejected"`. ## Cancel a call The caller ends a call that is still ringing with `endCall` and the `cancelled` status. The SDK first starts tearing the caller's prepared session down, then tells the server; `onConnectionClosed` follows when the room closes (the sample below has already removed its own listener). The callee's ring stops. ```javascript theme={null} async function cancelOutgoingCall(sessionId) { cancelled = true; stopWatching(); closeOutgoingScreen(); // close locally whatever the server says const { error } = await CometChatCalls.endCall(sessionId, "cancelled"); if (error) console.warn("Cancel failed:", error); } ``` Disable the cancel button after the first click, and ignore an `onParticipantJoined` that arrives after you cancelled: the cancel wins. If the user cancels before `initiateCall` has resolved, cancel the call when it resolves, or the callee rings for a call nobody is waiting on: ```javascript theme={null} let callSeq = 0; async function startCall(receiverUid, options, container) { const seq = ++callSeq; const { data: call } = await CometChatCalls.initiateCall(receiverUid, options); if (seq !== callSeq) { // Cancelled while "Calling…" (the cancel button did ++callSeq): the call exists now, so withdraw it. if (call) CometChatCalls.endCall(call.sessionId, "cancelled"); return; } if (call) watchOutgoingCall(call, container, options.receiverType === "group"); } ``` ## Ring timeout Nothing in the web SDKs ends a ring on a timer, so run a timer on both sides. On the caller, start it when `initiateCall` resolves and end the call as `unanswered` when it runs out; `watchOutgoingCall` above does this. Use 45 seconds, the default ring window of a callee on a phone. A callee on a phone stops ringing at its Push SDK's ring window, but if the callee's device is never reached, nothing else ends the caller's ringing until the prepared session expires after 5 minutes. A group call the caller stops waiting on is withdrawn as `cancelled` instead: `unanswered` is a 1:1 outcome. On the callee, stop ringing after 60 seconds, a little after the caller would have given up, with `stopRinging(sessionId, "over")`. Do not send a status: the caller ends the call. ## End a call Hang up by leaving the session with `session.leave()` or `CometChatCalls.leaveSession()`. The other side receives `onParticipantLeft`, and in a peer call (`isPeerCall: true`) the session ends for both. No status needs to be sent and the call is logged by the backend. ```javascript theme={null} // The default call UI's Leave button leaves the session itself; only clean up here. CometChatCalls.addEventListener("onLeaveSessionButtonClicked", () => { closeCallScreen(); }); // Your own hang-up control: async function hangUp() { await CometChatCalls.getActiveSession()?.leave(); closeCallScreen(); } // The other participant ended the call: CometChatCalls.addEventListener("onSessionLeft", closeCallScreen); CometChatCalls.addEventListener("onConnectionClosed", closeCallScreen); ``` `onConnectionClosed` fires for a joined call that ends and for a prepared session that is torn down, so check which screen is showing before acting on it. ## Several tabs and devices Every open tab where the callee is logged in receives the call and rings. Answering or declining in one tab does not stop the others by itself: * Tell your other tabs, for example with a [`BroadcastChannel`](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel) (`tellOtherTabs` in the samples above). A tab that hears another tab answered calls `stopRinging(sessionId, "elsewhere")`, which does not call `leave()` on its prepared session, because releasing a prepared 1:1 session ends the room. The session still expires after 5 minutes, with the same effect (see the warning under [Prepare the ringing call](#prepare-the-ringing-call)). A tab that hears another tab declined calls `stopRinging(sessionId, "over")`. * A 1:1 decline also reaches your other tabs as `onOutgoingCallRejected`, as shown in [Receive a call](#receive-a-call). * The status poll is the backstop: a call answered on another of the user's devices reads `ongoing`, which stops a 1:1 ring as `"elsewhere"`. * While one tab is in a call, keep your other tabs from ringing (tell them over the same channel), and have the tab in the call decline a 1:1 call with `busy`, as `isBusy()` in [Receive a call](#receive-a-call) does. A tab that is already joined to a call cannot prepare another one: `connect` rejects with `SESSION_ALREADY_ACTIVE` and `initiateCall` returns `SESSION_ALREADY_ACTIVE`. ## Group calls To ring a group, call `initiateCall` with the group's GUID as the receiver and `receiverType: "group"`, and leave `isPeerCall` off so the call outlives any one member leaving. Every member's open tabs (and phones) ring. When a group call rings, declining it or letting it ring out sends nothing: the call carries on for the other members, and the decline is local to that tab. You can also start a group call without ringing: share a session ID (for example in a custom message) and have each member join it with [`joinSession`](/docs/calls/javascript/join-session). ## Logout End or cancel any call of your own before logging out: `endCall` needs a logged-in user. Then remove the `CallListener`, stop any ring, and log out of both SDKs (`CometChatCalls.logout()` and `CometChat.logout()`). ## Call status values | Status | Meaning | Sent by | | - | - | - | | `initiated` | Created, ringing | Backend, on `initiateCall` | | `ongoing` | Answered | Backend, when the callee joins | | `rejected` | Callee declined | Callee, `endCall(sessionId, "rejected")` | | `busy` | Callee was in another call | Callee, `endCall(sessionId, "busy")` | | `cancelled` | Caller ended it before an answer | Caller, `endCall(sessionId, "cancelled")` | | `unanswered` | Nobody answered in the ring window | Caller's timer, `endCall(sessionId, "unanswered")`, or a mobile callee's Push SDK | | `ended` | Hung up after being answered | Backend, when the session ends | | `missed` | How an unanswered or cancelled incoming call appears in call logs | Call logs | ## Related * [Migrating from legacy ringing](/docs/calls/javascript/migrating-from-legacy-ringing). * [Events](/docs/calls/javascript/events), [Actions](/docs/calls/javascript/actions), [Call Logs](/docs/calls/javascript/call-logs). * Ringing on mobile: [Android](/docs/calls/android/ringing) and [iOS](/docs/calls/ios/ringing). # Screen Sharing Source: https://www.cometchat.com/docs/calls/javascript/screen-sharing Add screen sharing in CometChat Calls SDK v5 on JavaScript with presenter controls, permissions, and in-call display behavior. Share your screen with other participants during a call. The browser will prompt users to select which screen, window, or browser tab to share. ## Start Screen Sharing Begin sharing your screen: ```javascript theme={null} CometChatCalls.startScreenSharing(); ``` The browser will display a dialog allowing the user to choose: * Entire screen * Application window * Browser tab ## Stop Screen Sharing Stop the current screen share: ```javascript theme={null} CometChatCalls.stopScreenSharing(); ``` ## Screen Sharing Events ### Local Screen Share Events Monitor your own screen sharing state: ```javascript theme={null} CometChatCalls.addEventListener("onScreenShareStarted", () => { console.log("You started screen sharing"); }); CometChatCalls.addEventListener("onScreenShareStopped", () => { console.log("You stopped screen sharing"); }); ``` ### Participant Screen Share Events Monitor when other participants start or stop screen sharing: ```javascript theme={null} CometChatCalls.addEventListener("onParticipantStartedScreenShare", (participant) => { console.log(`${participant.name} started screen sharing`); }); CometChatCalls.addEventListener("onParticipantStoppedScreenShare", (participant) => { console.log(`${participant.name} stopped screen sharing`); }); ``` ## Screen Sharing Button ### Hide Screen Sharing Button To hide the screen sharing button from the control panel: ```javascript theme={null} const callSettings = { hideScreenSharingButton: true, // ... other settings }; ``` ### Listen for Button Clicks Intercept screen share button clicks for custom behavior: ```javascript theme={null} CometChatCalls.addEventListener("onScreenShareButtonClicked", () => { console.log("Screen share button clicked"); }); ``` ## Browser Support Screen sharing requires browser support for the `getDisplayMedia` API: | Browser | Support | | - | - | | Chrome | ✅ Full support | | Firefox | ✅ Full support | | Safari | ✅ Safari 13+ | | Edge | ✅ Full support | > [!NOTE] > > Screen sharing requires HTTPS in production. Localhost is exempt during development. # Session Settings Source: https://www.cometchat.com/docs/calls/javascript/session-settings Configure CometChat Calls SDK v5 session settings on JavaScript for call behavior, UI options, participant controls, and features. The session settings object allows you to customize every aspect of your call session before participants join. From controlling the initial audio/video state to customizing the UI layout and hiding specific controls, these settings give you complete control over the call experience. > [!NOTE] > > These are pre-session configurations that must be set before joining a call. Once configured, pass the settings object to the `joinSession()` method, or, for a [ringing](/docs/calls/javascript/ringing) call, to `initiateCall()` (as `sessionSettings`) or `connect()`. A session prepared by `initiateCall()` or `connect()` keeps the settings it was prepared with: `session.join(container)` takes none. Settings cannot be changed after the session has started, though many features can be controlled dynamically during the call using call actions. ```javascript theme={null} const callSettings = { sessionType: "VIDEO", layout: "TILE", startAudioMuted: false, startVideoPaused: false, hideControlPanel: false, hideLeaveSessionButton: false, hideToggleAudioButton: false, hideToggleVideoButton: false, }; ``` ## Session Settings ### Session Type **Property:** `sessionType` Defines the type of call session. Choose `VIDEO` for video calls with camera enabled, or `VOICE` for audio-only calls. ```javascript theme={null} sessionType: "VIDEO" ``` | Value | Description | | - | - | | `VIDEO` | Video call with camera enabled | | `VOICE` | Audio-only call | **Default:** `VIDEO` ### Peer Call **Property:** `isPeerCall` Marks the session as a one-to-one call. In a peer call, when one participant leaves, the session ends for both instead of continuing with one person in it. The SDK also watches the other participant's connection and reports `onRemoteConnectionLost` when no media statistics arrive from them for 10 seconds, and `onRemoteConnectionRestored` when they resume. Set it for every 1:1 ringing call; leave it off for group calls and meetings. ```javascript theme={null} isPeerCall: true ``` **Default:** `false` ### Layout Mode **Property:** `layout` Sets the initial layout mode for displaying participants. ```javascript theme={null} layout: "TILE" ``` | Value | Description | | - | - | | `TILE` | Grid layout showing all participants equally | | `SIDEBAR` | Main speaker with participants in a sidebar | | `SPOTLIGHT` | Focus on active speaker with others in sidebar | **Default:** `TILE` ### Start Audio Muted **Property:** `startAudioMuted` Determines whether the microphone is muted when joining the session. ```javascript theme={null} startAudioMuted: true ``` **Default:** `false` ### Start Video Paused **Property:** `startVideoPaused` Controls whether the camera is turned off when joining the session. ```javascript theme={null} startVideoPaused: true ``` **Default:** `false` ### Auto Start Recording **Property:** `autoStartRecording` Automatically starts recording the session as soon as it begins. ```javascript theme={null} autoStartRecording: true ``` **Default:** `false` ### Auto Start Transcription *Available since v5.0.5* **Property:** `autoStartTranscription` Automatically starts transcribing the session as soon as it begins. See [Transcription](/docs/calls/javascript/transcription) for details. ```javascript theme={null} autoStartTranscription: true ``` **Default:** `false` ### Caption Language *Available since v5.0.5* **Property:** `captionLanguage` Sets the language used for transcription and closed captions. See [Transcription](/docs/calls/javascript/transcription) for the full list of supported codes. ```javascript theme={null} captionLanguage: "en-US" ``` **Default:** `en-US` ### Idle Timeout Period Before Prompt **Property:** `idleTimeoutPeriodBeforePrompt` Time in milliseconds before showing the idle timeout prompt when you're the only participant. ```javascript theme={null} idleTimeoutPeriodBeforePrompt: 60000 // 60 seconds ``` **Default:** `60000` (60 seconds) ### Idle Timeout Period After Prompt **Property:** `idleTimeoutPeriodAfterPrompt` Time in milliseconds after the prompt before automatically ending the session. ```javascript theme={null} idleTimeoutPeriodAfterPrompt: 180000 // 180 seconds (3 minutes) ``` **Default:** `180000` (180 seconds / 3 minutes) ## UI Visibility Settings ### Hide Control Panel **Property:** `hideControlPanel` Hides the bottom control bar that contains call action buttons. ```javascript theme={null} hideControlPanel: true ``` **Default:** `false` ### Hide Leave Session Button **Property:** `hideLeaveSessionButton` Hides the button that allows users to leave or end the call. ```javascript theme={null} hideLeaveSessionButton: true ``` **Default:** `false` ### Hide Toggle Audio Button **Property:** `hideToggleAudioButton` Hides the microphone mute/unmute button from the control panel. ```javascript theme={null} hideToggleAudioButton: true ``` **Default:** `false` ### Hide Toggle Video Button **Property:** `hideToggleVideoButton` Hides the camera on/off button from the control panel. ```javascript theme={null} hideToggleVideoButton: true ``` **Default:** `false` ### Hide Recording Button **Property:** `hideRecordingButton` Hides the recording start/stop button from the control panel. ```javascript theme={null} hideRecordingButton: true ``` **Default:** `true` ### Hide Transcription Button *Available since v5.0.5* **Property:** `hideTranscriptionButton` Hides the transcription start/stop item from the control panel's **More** menu. ```javascript theme={null} hideTranscriptionButton: false ``` **Default:** `true` ### Hide Closed Caption Button *Available since v5.0.5* **Property:** `hideClosedCaptionButton` Hides the closed-caption (CC) button from the control panel. Even when set to `false`, the button only appears while transcription is running. ```javascript theme={null} hideClosedCaptionButton: false ``` **Default:** `true` ### Hide Screen Sharing Button **Property:** `hideScreenSharingButton` Hides the screen sharing button from the control panel. ```javascript theme={null} hideScreenSharingButton: true ``` **Default:** `false` ### Hide Change Layout Button **Property:** `hideChangeLayoutButton` Hides the button that allows switching between different layout modes. ```javascript theme={null} hideChangeLayoutButton: true ``` **Default:** `false` ### Hide Virtual Background Button **Property:** `hideVirtualBackgroundButton` Hides the virtual background settings button. ```javascript theme={null} hideVirtualBackgroundButton: true ``` **Default:** `false` ### Virtual Background **Property:** `virtualBackground` Configures the virtual background picker (images, user uploads, blur options) and engine. See [Virtual Background](/docs/calls/javascript/virtual-background#configure-the-virtual-background-picker) for all options. ```javascript theme={null} virtualBackground: { images: ["https://cdn.example.com/backgrounds/office.jpg"], allowUserImages: false, allowBlur: true, } ``` **Default:** `undefined` (built-in images, uploads and blur enabled) ### Hide Network Indicator **Property:** `hideNetworkIndicator` Hides the network quality indicator. ```javascript theme={null} hideNetworkIndicator: true ``` **Default:** `true` ## Complete Example ```javascript theme={null} const callSettings = { // Session configuration sessionType: "VIDEO", layout: "TILE", startAudioMuted: false, startVideoPaused: false, autoStartRecording: false, autoStartTranscription: false, captionLanguage: "en-US", // Timeout settings idleTimeoutPeriodBeforePrompt: 60000, idleTimeoutPeriodAfterPrompt: 180000, // UI visibility hideControlPanel: false, hideLeaveSessionButton: false, hideToggleAudioButton: false, hideToggleVideoButton: false, hideRecordingButton: true, hideTranscriptionButton: true, hideClosedCaptionButton: true, hideScreenSharingButton: false, hideChangeLayoutButton: false, hideVirtualBackgroundButton: false, hideNetworkIndicator: true, }; ``` > [accordion] All Settings Reference > > | Property | Type | Default | Description | > | - | - | - | - | > | `sessionType` | String | `VIDEO` | Call type: `VIDEO` or `VOICE` | > | `isPeerCall` | Boolean | `false` | One-to-one call: the session ends for both when either participant leaves | > | `layout` | String | `TILE` | Layout: `TILE`, `SIDEBAR`, or `SPOTLIGHT` | > | `startAudioMuted` | Boolean | `false` | Start with microphone muted | > | `startVideoPaused` | Boolean | `false` | Start with camera off | > | `autoStartRecording` | Boolean | `false` | Auto-start recording | > | `autoStartTranscription` | Boolean | `false` | Auto-start transcription | > | `captionLanguage` | String | `en-US` | Transcription / caption language code | > | `idleTimeoutPeriodBeforePrompt` | Number | `60000` | Idle timeout before prompt (ms) | > | `idleTimeoutPeriodAfterPrompt` | Number | `180000` | Idle timeout after prompt (ms) | > | `hideControlPanel` | Boolean | `false` | Hide control panel | > | `hideLeaveSessionButton` | Boolean | `false` | Hide leave button | > | `hideToggleAudioButton` | Boolean | `false` | Hide audio toggle | > | `hideToggleVideoButton` | Boolean | `false` | Hide video toggle | > | `hideRecordingButton` | Boolean | `true` | Hide recording button | > | `hideTranscriptionButton` | Boolean | `true` | Hide transcription button | > | `hideClosedCaptionButton` | Boolean | `true` | Hide closed caption button | > | `hideScreenSharingButton` | Boolean | `false` | Hide screen share button | > | `hideChangeLayoutButton` | Boolean | `false` | Hide layout change button | > | `hideVirtualBackgroundButton` | Boolean | `false` | Hide virtual background button | > | `virtualBackground` | Object | `undefined` | Virtual background picker and engine configuration | > | `hideNetworkIndicator` | Boolean | `true` | Hide network indicator | # Setup Source: https://www.cometchat.com/docs/calls/javascript/setup Set up CometChat Calls SDK v5 for JavaScript with installation, app credentials, initialization, authentication, and the Chat SDK needed for ringing. > [!NOTE] > > **Faster Integration with UI Kits** > > If you're using CometChat UI Kits, voice and video calling can be quickly integrated: > > * Incoming & outgoing call screens > * Call buttons with one-tap calling > * Call logs with history > > 👉 [React UI Kit Calling Integration](/docs/ui-kit/react/calling-integration) > > Use this Calls SDK directly only if you need custom call UI or advanced control. This guide walks you through installing the CometChat Calls SDK and initializing it in your web application. ## Install the SDK Install the CometChat Calls SDK using npm or yarn: > [tab] npm > > ```bash theme={null} > npm install @cometchat/calls-sdk-javascript@5.1.0 > ``` > [tab] yarn > > ```bash theme={null} > yarn add @cometchat/calls-sdk-javascript@5.1.0 > ``` > [!NOTE] > > **Ringing users?** On the web, an incoming call reaches an open tab through the Chat SDK's call listener, so a > ringing app also needs `@cometchat/chat-sdk-javascript`, initialized and logged in as the same user. The Calls SDK > starts, prepares, joins and ends the call. See [Ringing](/docs/calls/javascript/ringing). ## Import the SDK Import the `CometChatCalls` class in your JavaScript or TypeScript file: ```javascript theme={null} import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; ``` ## Initialize CometChat Calls The `init()` method initializes the SDK with your app credentials. Call this method once when your application starts. ### CallAppSettings The initialization requires a configuration object with the following properties: | Parameter | Type | Required | Description | | - | - | - | - | | `appId` | String | Yes | Your CometChat App ID | | `region` | String | Yes | Your app region (`us`, `eu`, or `in`) | ```javascript theme={null} const appId = "APP_ID"; // Replace with your App ID const region = "REGION"; // Replace with your Region ("us", "eu", or "in") const callAppSettings = { appId: appId, region: region, }; const result = await CometChatCalls.init(callAppSettings); if (result.success) { console.log("CometChat Calls SDK initialized successfully"); } else { console.error("CometChat Calls SDK initialization failed:", result.error); } ``` The `init()` method returns an object with: | Property | Type | Description | | - | - | - | | `success` | Boolean | `true` if initialization succeeded | | `error` | Object \| null | Error details if initialization failed | ## Browser Requirements The Calls SDK requires a modern browser with WebRTC support: | Browser | Minimum Version | | - | - | | Chrome | 72+ | | Firefox | 68+ | | Safari | 12.1+ | | Edge | 79+ | > [!NOTE] > > HTTPS is required for camera and microphone access in production. Localhost is exempt from this requirement during development. ## Permissions The browser will prompt users for camera and microphone permissions when joining a call. Ensure your application handles permission denials gracefully. ```javascript theme={null} // Check if permissions are granted async function checkMediaPermissions() { try { const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true }); stream.getTracks().forEach(track => track.stop()); return true; } catch (error) { console.error("Media permissions denied:", error); return false; } } ``` # Share Invite Source: https://www.cometchat.com/docs/calls/javascript/share-invite Add invite sharing in CometChat Calls SDK v5 on JavaScript so users can share call links and bring participants into sessions. Allow participants to share call invitations with others using the share invite feature. ## Share Invite Button ### Show Share Invite Button By default, the share invite button is hidden. To show it: ```javascript theme={null} const callSettings = { hideShareInviteButton: false, // ... other settings }; ``` ### Listen for Share Invite Button Clicks Handle share invite button clicks to implement your sharing logic: ```javascript theme={null} CometChatCalls.addEventListener("onShareInviteButtonClicked", () => { console.log("Share invite button clicked"); // Implement your sharing logic shareCallInvite(); }); ``` ## Implementing Share Functionality When the share invite button is clicked, you can implement various sharing methods: ### Web Share API Use the native Web Share API for mobile-friendly sharing: ```javascript theme={null} async function shareCallInvite() { const shareData = { title: "Join my call", text: "Click the link to join my video call", url: `https://yourapp.com/call/${sessionId}` }; if (navigator.share) { try { await navigator.share(shareData); console.log("Shared successfully"); } catch (error) { console.log("Share cancelled or failed"); } } else { // Fallback for browsers that don't support Web Share API copyToClipboard(shareData.url); } } ``` ### Copy to Clipboard Provide a simple copy-to-clipboard option: ```javascript theme={null} function copyToClipboard(text) { navigator.clipboard.writeText(text).then(() => { console.log("Link copied to clipboard"); // Show a toast notification }).catch(err => { console.error("Failed to copy:", err); }); } ``` ### Custom Share Dialog Create a custom share dialog with multiple options: ```javascript theme={null} function showShareDialog() { const callLink = `https://yourapp.com/call/${sessionId}`; // Show your custom dialog with options like: // - Copy link // - Share via email // - Share via SMS // - Share to social media } ``` # Transcription & Closed Captions Source: https://www.cometchat.com/docs/calls/javascript/transcription Use CometChat Calls SDK v5 transcription on JavaScript to transcribe calls, show live closed captions, and retrieve transcripts after the call. > [!NOTE] > > **Available since v5.0.5** — transcription and closed captions require CometChat Calls SDK v5.0.5 or later for JavaScript. See [Setup](/docs/calls/javascript/setup) to install or upgrade. Transcribe call sessions in real time and display live closed captions on screen. Transcripts are stored server-side and can be retrieved after the call using `TranscriptRequestBuilder`. > [!WARNING] > > Transcription must be enabled for your CometChat app. Contact support if you need to enable this feature. ## How It Works Transcription and closed captions are two related but separate things: | Concept | What it does | | - | - | | **Transcription** | Server-side speech-to-text for the session. Starting it brings a transcriber into the call, which produces the transcript that is stored for later retrieval. | | **Closed captions** | The on-screen overlay that renders the live transcript as it arrives. Captions are produced from the running transcription, so they only appear while transcription is active. | Starting transcription is a prerequisite for captions — toggling captions on without an active transcription shows nothing. ## Starting Transcription ### Auto-Start Transcription Configure transcription to start automatically when the session begins: ```javascript theme={null} const callSettings = { autoStartTranscription: true, // ... other settings }; await CometChatCalls.joinSession(callToken, callSettings, container); ``` **Default:** `false` ### Manual Transcription Control #### Start Transcription Begin transcribing during an active call: ```javascript theme={null} CometChatCalls.startTranscription(); ``` #### Stop Transcription Stop the current transcription. Any captions currently on screen are cleared: ```javascript theme={null} CometChatCalls.stopTranscription(); ``` ## Built-in UI Controls ### Transcription Button By default, the transcription button in the control panel's **More** menu is hidden. To show it: ```javascript theme={null} const callSettings = { hideTranscriptionButton: false, // ... other settings }; ``` **Default:** `true` The menu item toggles between **Start Transcription** and **Stop Transcription** based on the current state. ### Closed Caption Button By default, the closed-caption (CC) button in the control panel is hidden. To show it: ```javascript theme={null} const callSettings = { hideClosedCaptionButton: false, // ... other settings }; ``` **Default:** `true` > [!NOTE] > > Even with `hideClosedCaptionButton: false`, the CC button only appears once transcription is running for the session, because captions are generated from the live transcript. ### Closed Caption Settings When the CC button is visible, the settings dialog gains a **Closed Caption** tab where the user can pick the caption language and enable or disable the on-screen captions. The gear icon on the captions overlay opens the dialog directly on that tab. ## Caption Language **Property:** `captionLanguage` Sets the language used for transcription and captions. ```javascript theme={null} const callSettings = { captionLanguage: "en-US", // ... other settings }; ``` **Default:** `en-US` > [accordion] Supported Language Codes > > | Code | Language | > | - | - | > | `en-US` | English (United States) | > | `de-DE` | German (Germany) | > | `en-GB` | English (United Kingdom) | > | `es-ES` | Spanish (Spain) | > | `fr-FR` | French (France) | > | `hi-IN` | Hindi (India) | > | `hu-HU` | Hungarian (Hungary) | > | `it-IT` | Italian (Italy) | > | `ja-JP` | Japanese (Japan) | > | `ko-KR` | Korean (South Korea) | > | `lt-LT` | Lithuanian (Lithuania) | > | `ms-MY` | Malay (Malaysia) | > | `nl-NL` | Dutch (Netherlands) | > | `pt-PT` | Portuguese (Portugal) | > | `ru-RU` | Russian (Russia) | > | `sv-SE` | Swedish (Sweden) | > | `tr-TR` | Turkish (Turkey) | > | `zh` | Chinese Mandarin (Simplified, China) | > | `zh-TW` | Chinese Mandarin (Traditional, Taiwan) | ## Retrieving Transcripts After a call, use `TranscriptRequestBuilder` to list the transcript artifacts for a session. Each record is a **pointer to a downloadable transcript file**, not the transcript text itself. > [!NOTE] > > The SDK must be initialized with `CometChatCalls.init()` and a user must be logged in. The auth token is read from the logged-in user at fetch time, so it automatically tracks re-logins. ### Building a Request ```javascript theme={null} const request = new CometChatCalls.TranscriptRequestBuilder() .setSessionId("v1.us.2547167fe69871fd.alice") // required .setLimit(10) // optional .build(); const transcripts = await request.fetchNext(); ``` | Method | Required | Description | | - | - | - | | `setSessionId(sessionId: string)` | Yes | The session ID whose transcripts to fetch. An empty value throws `SESSION_ID_REQUIRED` at `build()`. | | `setLimit(limit: number)` | No | Page size. Defaults to `30` and is clamped to the range `1`–`1000`. | | `build()` | Yes | Returns a `TranscriptRequest`. Throws synchronously for pre-flight errors. | ### Paginating A `TranscriptRequest` is a stateful cursor. Create one per session ID and drive it with `fetchNext()` and `fetchPrevious()`: ```javascript theme={null} const request = new CometChatCalls.TranscriptRequestBuilder() .setSessionId(sessionId) .setLimit(10) .build(); let page = await request.fetchNext(); // page 1 while (page.length > 0) { page.forEach((transcript) => console.log(transcript.transcriptUrl)); page = await request.fetchNext(); // page 2, 3, ... then [] at the end } ``` * `fetchNext()` resolves the next page, or `[]` when there are no more pages. A session with no transcripts resolves `[]`. * `fetchPrevious()` resolves the previous page, or `[]` when already on the first page. It never requests a page below `1`. * Only one fetch may be in flight at a time. Calling `fetchNext()` or `fetchPrevious()` while another request is pending rejects with `REQUEST_IN_PROGRESS`; the original call is unaffected and still completes. ### Transcript Properties | Property | Type | Description | | - | - | - | | `tid` | String | Transcript ID | | `mid` | String | Meeting ID | | `roomName` | String | Room name of the meeting | | `startTime` | Number | Meeting start time, in epoch **seconds** | | `endTime` | Number | Meeting end time, in epoch **seconds** | | `url` | String | Meeting URL | | `transcriptDate` | String | Transcript date | | `transcriptUrl` | String | URL of the downloadable transcript JSON | | `metaData` | Object | Arbitrary metadata | > [!NOTE] > > Every property is optional. The server omits keys whose value is empty, so sparse records are normal and should not be treated as an error. ### Reading the Transcript Content `transcriptUrl` points at the transcript file. Fetch it yourself to read the actual utterances: ```javascript theme={null} const [transcript] = await request.fetchNext(); if (transcript?.transcriptUrl) { const response = await fetch(transcript.transcriptUrl); const content = await response.json(); console.log(content); } ``` ### Error Handling `build()` throws synchronously; `fetchNext()` and `fetchPrevious()` reject. Both surface a `CometChatCallsException` carrying a `code`: | Condition | Code | Raised by | | - | - | - | | `init()` was not called | `NOT_INITIALIZED` | `build()` | | `sessionId` missing or empty | `SESSION_ID_REQUIRED` | `build()` | | No logged-in user | `NOT_LOGGED_IN` | `fetchNext()` / `fetchPrevious()` | | A fetch is already in flight | `REQUEST_IN_PROGRESS` | `fetchNext()` / `fetchPrevious()` | | Network failure | `NETWORK_ERROR` | `fetchNext()` / `fetchPrevious()` | | Missing or malformed response | `BAD_RESPONSE` | `fetchNext()` / `fetchPrevious()` | | Server-side API error | The server's own code (e.g. `AUTH_ERR_EMPTY_APPID`) | `fetchNext()` / `fetchPrevious()` | ```javascript theme={null} try { const transcripts = await request.fetchNext(); } catch (error) { console.error(error.code, error.message); } ``` ## Transcripts in Call Logs Call logs can be filtered to transcribed calls, which also attaches each call's transcripts to the log: ```javascript theme={null} const callLogRequest = new CometChatCalls.CallLogRequestBuilder() .setLimit(30) .setHasTranscriptions(true) .build(); const callLogs = await callLogRequest.fetchNext(); callLogs.forEach((callLog) => { callLog.getTranscriptions().forEach((transcription) => { console.log(transcription.getTid(), transcription.getTranscriptURL()); }); }); ``` `getTranscriptions()` returns an empty array when the server omitted transcripts, so it never needs a null check. > [accordion] Transcription Methods > > | Method | Returns | Description | > | - | - | - | > | `getTid()` | String | The transcript ID | > | `getMid()` | String | The meeting ID | > | `getRoomName()` | String | The room name of the meeting | > | `getStartTime()` | Number | Meeting start time, in epoch seconds | > | `getEndTime()` | Number | Meeting end time, in epoch seconds | > | `getTranscriptDate()` | String | The transcript date | > | `getTranscriptURL()` | String | URL of the downloadable transcript JSON | ## Complete Example ```javascript theme={null} // 1. Join a session with transcription enabled const callSettings = { sessionType: "VIDEO", autoStartTranscription: true, hideTranscriptionButton: false, hideClosedCaptionButton: false, captionLanguage: "en-US", }; await CometChatCalls.joinSession(callToken, callSettings, container); // 2. Control transcription during the call CometChatCalls.startTranscription(); CometChatCalls.stopTranscription(); // 3. Retrieve transcripts after the call const request = new CometChatCalls.TranscriptRequestBuilder() .setSessionId(sessionId) .setLimit(10) .build(); const transcripts = await request.fetchNext(); ``` ## Related Documentation * [Session Settings](/docs/calls/javascript/session-settings) * [Actions](/docs/calls/javascript/actions) * [Call Logs](/docs/calls/javascript/call-logs) # Troubleshooting Source: https://www.cometchat.com/docs/calls/javascript/troubleshooting Troubleshoot CometChat Calls SDK v5 on JavaScript for setup, authentication, permissions, call launch, media, and session issues. ## Installation & Setup | Symptom | Cause | Fix | | - | - | - | | `CometChatCalls is not defined` | SDK not installed or not imported | Run `npm install @cometchat/calls-sdk-javascript` and import `CometChatCalls` | | `init()` fails silently | Invalid App ID or Region | Double-check credentials from the [CometChat Dashboard](https://app.cometchat.com/) | | `init()` throws network error | Region mismatch or network issue | Ensure the Region matches your app's region (`us`, `eu`, `in`, `in-private`) | | Module not found error | Incorrect import path | Use `import { CometChatCalls } from "@cometchat/calls-sdk-javascript"` | *** ## Authentication | Symptom | Cause | Fix | | - | - | - | | `login()` fails with invalid UID | UID doesn't exist in CometChat | Create the user via [Dashboard](https://app.cometchat.com/) or [REST API](/docs/rest-api/users/create) first | | Auth token expired | Token has a limited lifetime | Generate a new auth token and call `login()` again | | `login()` called before `init()` | SDK not initialized | Always `await CometChatCalls.init()` before calling `login()` | *** ## Joining a Session | Symptom | Cause | Fix | | - | - | - | | `generateToken()` fails | User not logged in or invalid session ID | Ensure `login()` completes before generating a token. Verify the session ID is valid | | `joinSession()` shows blank screen | Container element not found or not visible | Ensure the HTML element passed to `CallSettings` exists in the DOM and has dimensions | | Session joins but no audio/video | Permissions denied by browser | Prompt the user to allow camera/microphone access. See [Permissions Handling](/docs/calls/javascript/permissions-handling) | | `joinSession()` throws error | Invalid or expired token | Generate a fresh token using `generateToken()` before joining | *** ## Audio & Video | Symptom | Cause | Fix | | - | - | - | | No audio from remote participants | Audio output device issue or muted | Check speaker selection and ensure remote participants are not muted | | Camera not working | Another app is using the camera | Close other apps using the camera, or select a different device | | Black video tiles | Browser blocked camera access | Check browser permissions. HTTPS is required in production | | Echo or feedback | No echo cancellation | Use headphones or enable browser echo cancellation | *** ## Screen Sharing | Symptom | Cause | Fix | | - | - | - | | Screen share button not working | Browser doesn't support `getDisplayMedia` | Ensure the browser supports screen sharing. See [Browser Compatibility](/docs/calls/javascript/overview#browser-compatibility) | | Screen share fails silently | User cancelled the share dialog | No action needed — this is expected behavior when the user dismisses the dialog | | Screen share not visible to others | Network or encoding issue | Check network connectivity and try reducing resolution | *** ## HTTPS & Deployment | Symptom | Cause | Fix | | - | - | - | | Camera/mic permissions blocked | App not served over HTTPS | Use HTTPS in production. Localhost is exempt during development | | WebRTC connection fails behind firewall | TURN/STUN servers blocked | Ensure your network allows WebRTC traffic. Contact your network admin | | SDK works locally but not in production | Mixed content or CORS issues | Ensure all resources are loaded over HTTPS | *** ## Framework-Specific | Symptom | Cause | Fix | | - | - | - | | SSR error in Next.js | SDK uses browser APIs (`window`, `navigator`) | Use dynamic import with `ssr: false` or wrap in `useEffect`. See [Next.js Integration](/docs/calls/javascript/nextjs-integration) | | Component renders but call UI doesn't appear | Container element not mounted yet | Ensure the DOM element is rendered before calling `joinSession()` | | Hot reload breaks call session | SDK state lost on HMR | Rejoin the session after hot reload, or disable HMR during active calls | *** ## Ringing | Symptom | Cause | Fix | | - | - | - | | Incoming calls do not ring in the browser | The Chat SDK is not logged in, is logged in as another user, or no `CometChat.addCallListener` is registered | Initialize and log in the Chat SDK as the same user as the Calls SDK, and register the `CallListener` after login. A closed tab never rings: the web has no VoIP push. See [Ringing](/docs/calls/javascript/ringing) | | Every outgoing call is declined "busy" at once | The caller's own tab treats its outgoing call as incoming (the Chat SDK delivers a 1:1 call message to the caller too) and declines it as busy | In `onIncomingCallReceived`, skip calls whose `getCallInitiator().getUid()` is the logged-in user | | Caller never sees "Ringing…" or "answered" | The callee never prepared the session, the caller's own prepare failed (`call.session.prepareStatus === "failed"`, so it is not in the room), or the listeners were registered too late | Have the callee call `connect(sessionId, settings)` as soon as the call rings; register the caller's listeners right after `initiateCall` resolves; poll the call's status, which reports an answer as `ongoing` | | Caller keeps ringing after the callee declined | No `onOutgoingCallRejected` handler on the caller's `CallListener`, or the tab missed the message (asleep, reconnecting). A busy decline, or a decline before the callee's device connected, does not close the caller's prepared session | Handle `onOutgoingCallRejected` for your own outgoing call, read the call's status every 3 s while ringing as a backstop, and run a ring timer that ends the call as `unanswered` | | Callee keeps ringing after the caller cancelled | No `onIncomingCallCancelled` handler, or the tab missed the message (asleep, reconnecting) and the room was not destroyed | Handle `onIncomingCallCancelled`, and poll the call's status while ringing as a backstop: stop on anything but `initiated` for a 1:1 call | | Audio call opens the camera | Session type not set when the session was prepared | Pass `sessionType: "VOICE"` in `initiateCall`'s `sessionSettings` and to `connect`; `session.join(container)` takes no settings | | One side stays in the call after the other hangs up | The session was not prepared or joined as a peer call | Pass `isPeerCall: true` for 1:1 calls | | A call answered in another tab or on another device ends | A tab released its prepared 1:1 session after the call was answered elsewhere: leaving a prepared peer session ends the room | Stop ringing without `leave()` when the call was answered elsewhere. The prepared session still expires after 5 minutes, or is torn down by the next `connect` or `initiateCall` in that tab, with the same effect; there is no local-only leave. See [Ringing](/docs/calls/javascript/ringing#prepare-the-ringing-call) | | `joinSession()` returns `SESSION_ALREADY_PREPARED` | A session is prepared for a ringing call | Join it with `session.join(container)`, or cancel it with `session.leave()` first | | `onSessionTimedOut` never fires for an unanswered call | A prepared session that nobody joins reports `onConnectionClosed` after 5 minutes | Listen for `onConnectionClosed`, and use your own ring timer | *** ## Events & Callbacks | Symptom | Cause | Fix | | - | - | - | | Event listener not firing | Wrong event name or listener not registered | Check the [Events](/docs/calls/javascript/events) page for exact event names | | Duplicate event triggers | Multiple listeners registered without cleanup | Remove listeners when the component unmounts or before re-registering | | `onParticipantJoined` not called | Listener registered after user already joined | Register listeners before calling `joinSession()` | # Virtual Background Source: https://www.cometchat.com/docs/calls/javascript/virtual-background Add virtual backgrounds in CometChat Calls SDK v5 for JavaScript calls with background effects and in-call video customization. Apply virtual backgrounds to your video feed during calls. You can blur your background or replace it with a custom image. ## Background Blur Apply a blur effect to your background: ```javascript theme={null} CometChatCalls.setVirtualBackgroundBlurLevel(10); ``` | Parameter | Type | Description | | - | - | - | | `blurLevel` | Number | The blur intensity level (higher = more blur) | ## Custom Background Image Set a custom image as your virtual background: ```javascript theme={null} CometChatCalls.setVirtualBackgroundImage("https://example.com/background.jpg"); ``` | Parameter | Type | Description | | - | - | - | | `imageUrl` | String | URL of the background image | > [!NOTE] > > The image URL must be accessible from the user's browser. Consider hosting images on a CDN for best performance. ## Clear Virtual Background Remove any applied virtual background: ```javascript theme={null} CometChatCalls.clearVirtualBackground(); ``` ## Virtual Background Dialog ### Show Dialog Open the built-in virtual background settings dialog: ```javascript theme={null} CometChatCalls.showVirtualBackgroundDialog(); ``` ### Hide Dialog Close the virtual background dialog: ```javascript theme={null} CometChatCalls.hideVirtualBackgroundDialog(); ``` ## Configure the Virtual Background Picker Use the `virtualBackground` session setting to control which images appear in the virtual background picker, whether users can upload their own images, and whether blur options are available. Pass it in the settings object to `joinSession()`: ```javascript theme={null} const callSettings = { virtualBackground: { images: [ "https://cdn.example.com/backgrounds/office.jpg", { src: "https://cdn.example.com/backgrounds/beach.jpg", label: "Beach" }, ], allowUserImages: false, allowBlur: true, }, // ... other settings }; await CometChatCalls.joinSession(callToken, callSettings, container); ``` | Property | Type | Default | Description | | - | - | - | - | | `images` | Array | Built-in CometChat images | Images shown in the picker. Each entry is either an image URL or an object with a `src` URL and an optional `label` (used as the tile's tooltip). Providing this **replaces** the built-in images. Pass `[]` to show no images. | | `allowUserImages` | Boolean | `true` | Show the **Add Background** tile that lets users upload their own image. When `false`, any images the user uploaded earlier in the same page load are also removed from the picker. | | `allowBlur` | Boolean | `true` | Show the **Slightly Blur** and **Blur** options. | | `enableV2` | Boolean | `false` | Use the V2 virtual background engine. See [Virtual Background V2 Engine](#virtual-background-v2-engine). | | `assetsBaseUrl` | String | CometChat CDN | Folder (with a trailing slash) the SDK downloads virtual background assets from. Only set this when self-hosting the assets. | > [!NOTE] > > Custom image URLs must be served with CORS enabled. If an image can't be loaded cross-origin, the effect fails to apply and the user sees a "Virtual background could not be applied" message. ### Default Images When you don't pass `images`, the picker shows these built-in images: **Nature**, **Office**, **Library**, **Home**, **Night Sky**, and **Office Lounge**. To add your own images alongside the built-in ones instead of replacing them, spread `DEFAULT_VIRTUAL_BACKGROUND_IMAGES` into your list: ```javascript theme={null} import { CometChatCalls, DEFAULT_VIRTUAL_BACKGROUND_IMAGES, } from "@cometchat/calls-sdk-javascript"; const callSettings = { virtualBackground: { images: [ ...DEFAULT_VIRTUAL_BACKGROUND_IMAGES, { src: "https://cdn.example.com/backgrounds/brand.jpg", label: "Brand" }, ], }, }; ``` ### TypeScript Types The configuration types are exported from the SDK: ```typescript theme={null} import type { VirtualBackgroundConfig, VirtualBackgroundImage, } from "@cometchat/calls-sdk-javascript"; const virtualBackground: VirtualBackgroundConfig = { images: [{ src: "https://cdn.example.com/backgrounds/office.jpg", label: "Office" }], allowUserImages: true, allowBlur: true, }; ``` ## Virtual Background V2 Engine The V2 engine runs background segmentation in a dedicated Web Worker and composites frames on the GPU. Compared to the default engine, it keeps the effect running smoothly when the tab is in the background, lowers main-thread CPU usage, and produces cleaner edges. The SDK picks the best backend for the device automatically: WebGPU or WebGL where a GPU is available, and a WebAssembly fallback otherwise. Enable it with `enableV2`: ```javascript theme={null} const callSettings = { virtualBackground: { enableV2: true, }, }; ``` If V2 fails to initialize (for example, when the worker script is blocked), the SDK logs the error and automatically falls back to the default engine for the rest of the page lifetime. ### Content Security Policy If your page sets a Content Security Policy, the V2 engine requires the following directives, where `` is the host serving the assets (`https://cdn.cometchat.io` by default, or the host of your `assetsBaseUrl`): | Directive | Value | Reason | | - | - | - | | `worker-src` | `blob:` | The inference worker is started from a `blob:` URL | | `script-src` | `` | The worker script is loaded from the assets host | | `connect-src` | `` | Segmentation models and WebAssembly files are downloaded from the assets host (also required by the default engine) | ### Self-Hosting Assets By default, virtual background assets are downloaded on demand from the CometChat CDN. To serve them from your own infrastructure, host the files below in one folder and set `assetsBaseUrl` to that folder: | File | Used by | | - | - | | `tflite.wasm`, `tflite-simd.wasm` | Default engine and V2 (WebAssembly fallback) | | `selfie_segmentation_landscape.tflite` | Default engine and V2 (WebAssembly fallback) | | `vb-inference-worker..min.js` | V2 only | | `selfie_segmentation_landscape_tfjs/model.json`, `selfie_segmentation_landscape_tfjs/group1-shard1of1.bin` | V2 only (WebGPU and WebGL backends) | ```javascript theme={null} const callSettings = { virtualBackground: { enableV2: true, assetsBaseUrl: "https://assets.example.com/cometchat/vb/", }, }; ``` > [!WARNING] > > The inference worker's file name includes a hash of its contents, and each SDK version requests one exact file name (visible in the browser's network tab, and in the console error when the file is missing). After upgrading the SDK, check whether the worker file name changed and copy the new file if needed. Keep the old file while pages may still load the previous SDK version. ## Hide Virtual Background Button To hide the virtual background button from the control panel: ```javascript theme={null} const callSettings = { hideVirtualBackgroundButton: true, // ... other settings }; ``` ## Browser Requirements Virtual backgrounds use machine learning for background segmentation. Performance may vary based on: * Device processing power * Browser version * Camera resolution ### Browser Compatibility | Platform | Browser | Supported | | - | - | - | | Desktop (Windows, macOS, Linux) | Chrome and other Chromium-based browsers (Microsoft Edge, Brave, Opera, etc.) | ✅ Yes | | Desktop (Windows, macOS, Linux) | Firefox and other Firefox-based browsers (Zen, etc.) | ✅ Yes | | Desktop (macOS) | Safari | ❌ Not supported | | Android | Chrome and other Chromium-based browsers (Microsoft Edge, Brave, etc.) | ✅ Yes | | Android | Firefox and other Firefox-based browsers | ✅ Yes | | iOS (iPhone, iPad) | Safari, Chrome, Edge, Brave, any browser | ❌ Not supported | > [!WARNING] > > Virtual background is **not supported on iOS**. Every browser on iOS, including Chrome, Edge, and Brave, is required to use Apple's WebKit engine (the same engine as Safari), which doesn't provide the APIs needed for real-time background segmentation. For best results, use a Chromium-based browser or Firefox on a device with adequate processing power. # Vue Integration Source: https://www.cometchat.com/docs/calls/javascript/vue-integration Integrate CometChat Calls SDK v5 in Vue apps with package setup, initialization, call UI rendering, and component usage. This guide walks you through integrating the CometChat Calls SDK into a Vue.js application. By the end, you'll have a working video call implementation with proper state management and lifecycle handling. ## Prerequisites Before you begin, ensure you have: * A CometChat account with an app created ([Sign up](https://app.cometchat.com/signup)) * Your App ID, Region, and API Key from the CometChat Dashboard * A Vue 3 project (Vite, Vue CLI, or Nuxt) * Node.js 16+ installed ## Step 1: Install the SDK Install the CometChat Calls SDK package: ```bash theme={null} npm install @cometchat/calls-sdk-javascript ``` ## Step 2: Create a Composable for SDK Management Create a composable that handles initialization, login, and provides reactive state: ```javascript theme={null} // src/composables/useCometChatCalls.js import { ref, readonly } from "vue"; import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; const APP_ID = "YOUR_APP_ID"; // Replace with your App ID const REGION = "YOUR_REGION"; // Replace with your Region (us, eu, in) const API_KEY = "YOUR_API_KEY"; // Replace with your API Key // Shared state across all components const isReady = ref(false); const user = ref(null); const error = ref(null); const isInitializing = ref(false); export function useCometChatCalls() { /** * Initialize the SDK and login the user. * Call this once when your app starts or when the user authenticates. */ async function initAndLogin(uid) { if (isInitializing.value || isReady.value) return; isInitializing.value = true; error.value = null; try { // Step 1: Initialize the SDK const initResult = await CometChatCalls.init({ appId: APP_ID, region: REGION, }); if (!initResult.success) { throw new Error("SDK initialization failed"); } // Step 2: Check if already logged in let loggedInUser = CometChatCalls.getLoggedInUser(); // Step 3: Login if not already logged in if (!loggedInUser) { loggedInUser = await CometChatCalls.login(uid, API_KEY); } user.value = loggedInUser; isReady.value = true; } catch (err) { console.error("CometChat Calls setup failed:", err); error.value = err.message || "Setup failed"; } finally { isInitializing.value = false; } } /** * Logout the current user and reset state. */ async function logout() { try { await CometChatCalls.logout(); user.value = null; isReady.value = false; } catch (err) { console.error("Logout failed:", err); } } return { // State (readonly to prevent external mutations) isReady: readonly(isReady), user: readonly(user), error: readonly(error), isInitializing: readonly(isInitializing), // Methods initAndLogin, logout, }; } ``` ## Step 3: Initialize in App.vue Initialize the SDK when your app mounts: ```vue theme={null} ``` ## Step 4: Create the Call Component Build a call component with proper lifecycle management: ```vue theme={null} ``` ## Step 5: Create the Call Page Create a page that manages the call flow: ```vue theme={null} ``` ## Call Composable (Optional) For reusable call logic across multiple components: ```javascript theme={null} // src/composables/useCall.js import { ref, onUnmounted } from "vue"; import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; export function useCall() { const isInCall = ref(false); const isMuted = ref(false); const isVideoOff = ref(false); const participants = ref([]); const unsubscribers = ref([]); async function joinCall(sessionId, container, settings = {}) { unsubscribers.value = [ CometChatCalls.addEventListener("onAudioMuted", () => { isMuted.value = true; }), CometChatCalls.addEventListener("onAudioUnMuted", () => { isMuted.value = false; }), CometChatCalls.addEventListener("onVideoPaused", () => { isVideoOff.value = true; }), CometChatCalls.addEventListener("onVideoResumed", () => { isVideoOff.value = false; }), CometChatCalls.addEventListener("onParticipantListChanged", (list) => { participants.value = list; }), CometChatCalls.addEventListener("onSessionLeft", () => { isInCall.value = false; }), ]; const tokenResult = await CometChatCalls.generateToken(sessionId); await CometChatCalls.joinSession( tokenResult.token, { sessionType: "VIDEO", layout: "TILE", ...settings }, container ); isInCall.value = true; } function leaveCall() { CometChatCalls.leaveSession(); cleanup(); } function toggleAudio() { isMuted.value ? CometChatCalls.unmuteAudio() : CometChatCalls.muteAudio(); } function toggleVideo() { isVideoOff.value ? CometChatCalls.resumeVideo() : CometChatCalls.pauseVideo(); } function cleanup() { unsubscribers.value.forEach((unsub) => unsub()); unsubscribers.value = []; isInCall.value = false; } onUnmounted(() => { cleanup(); }); return { isInCall, isMuted, isVideoOff, participants, joinCall, leaveCall, toggleAudio, toggleVideo, }; } ``` ## Vue 2 Support For Vue 2 projects using the Options API, see the [Vue 2 migration guide](https://v3-migration.vuejs.org/) or use the `@vue/composition-api` package to use the Composition API in Vue 2. ## Related Documentation For more detailed information on specific topics covered in this guide, refer to the main documentation: * [Setup](/docs/calls/javascript/setup) - Detailed SDK installation and initialization * [Authentication](/docs/calls/javascript/authentication) - Login methods and user management * [Session Settings](/docs/calls/javascript/session-settings) - All available call configuration options * [Join Session](/docs/calls/javascript/join-session) - Session joining and token generation * [Events](/docs/calls/javascript/events) - Complete list of event listeners * [Actions](/docs/calls/javascript/actions) - All available call control methods * [Call Layouts](/docs/calls/javascript/call-layouts) - Layout options and customization * [Participant Management](/docs/calls/javascript/participant-management) - Managing call participants # Platform Compatibility Source: https://www.cometchat.com/docs/calls/platform/compatibility Check CometChat Calls platform compatibility for SDK support, browser requirements, mobile platforms, features, and known limitations. This page provides detailed information about feature availability across platforms, browser support, and minimum version requirements. ## Platform Feature Comparison Not all features are available on every platform. Use this table to understand feature availability: | Feature | JavaScript | React Native | iOS | Android | Flutter | | - | :-: | :-: | :-: | :-: | :-: | | **Core Features** | | | | | | | Voice Calls | ✓ | ✓ | ✓ | ✓ | ✓ | | Video Calls | ✓ | ✓ | ✓ | ✓ | ✓ | | Group Calls | ✓ | ✓ | ✓ | ✓ | ✓ | | Screen Sharing | ✓ | ✓ | ✓ | ✓ | ✓ | | Recording | ✓ | ✓ | ✓ | ✓ | ✓ | | Call Layouts | ✓ | ✓ | ✓ | ✓ | ✓ | | **Call Management** | | | | | | | Ringing | ✓ | ✓ | ✓ | ✓ | ✓ | | Call Logs | ✓ | ✓ | ✓ | ✓ | ✓ | | Participant Management | ✓ | ✓ | ✓ | ✓ | ✓ | | In-Call Chat | ✓ | ✓ | ✓ | ✓ | ✓ | | **Advanced Features** | | | | | | | Virtual Background | ✓ | ✗ | ✗ | ✗ | ✗ | | Picture-in-Picture | ✓ | ✗ | ✗ | ✓ | ✗ | | Raise Hand | ✓ | ✓ | ✓ | ✓ | ✓ | | Audio Modes | ✗ | ✓ | ✓ | ✓ | ✓ | | **Customization** | | | | | | | Custom Control Panel | ✓ | ✓ | ✓ | ✓ | ✓ | | Idle Timeout | ✓ | ✓ | ✓ | ✓ | ✓ | | Device Management | ✓ | ✗ | ✗ | ✗ | ✗ | | **Platform-Specific** | | | | | | | VoIP / CallKit | ✗ | ✓ | ✓ | ✓ | ✗ | | Background Handling | ✗ | ✓ | ✓ | ✓ | ✗ | ✓ = Available, ✗ = Not Available ## Browser Support ### Desktop Browsers | Browser | Minimum Version | Notes | | - | - | - | | Chrome | 72+ | Recommended | | Firefox | 68+ | Full support | | Safari | 12.1+ | macOS 10.14.4+ | | Edge | 79+ | Chromium-based | | Opera | 60+ | Chromium-based | ### Mobile Browsers | Browser | Minimum Version | | - | - | | Chrome for Android | 72+ | | Firefox for Android | 68+ | | Samsung Internet | 12+ | | Edge for Android | 79+ | | Safari for iOS | 12.1+ | | Chrome for iOS | 72+ | | Edge for iOS | 79+ | ## Native Mobile Platforms ### iOS | Requirement | Value | | - | - | | Minimum Version | iOS 16.0+ | | Architecture | arm64 | | Package Manager | CocoaPods, SPM | | Platform Capabilities | CallKit, VoIP Push, Background Audio | ### Android | Requirement | Value | | - | - | | Minimum API | API 24 (Android 7.0+) | | Architecture | arm64-v8a, armeabi-v7a | | Package Manager | Gradle | | Platform Capabilities | PiP Mode, Foreground Service, ConnectionService | ## Cross-Platform Frameworks ### React Native | Requirement | Value | | - | - | | Minimum Version | 0.70+ | | Platforms | iOS, Android | | Package Manager | npm, yarn | | Expo Support | Bare workflow | ### Flutter | Requirement | Value | | - | - | | Minimum Flutter | 3.0+ | | Minimum Dart | 2.17+ | | Platforms | iOS, Android | | Package Manager | pub | ## Network Requirements ### Ports & Protocols | Protocol | Port | Purpose | | - | - | - | | HTTPS | 443 | API calls, signaling | | UDP | 10000-20000 | Media streaming (preferred) | | TCP | 443 | Media fallback (TURN) | ### Bandwidth Recommendations | Call Type | Bandwidth | | - | - | | Voice Call | 100 - 300 kbps | | Video Call (SD) | 500 kbps - 1 Mbps | | Video Call (HD) | 1.5 - 3 Mbps | | Screen Sharing | 1 - 2 Mbps | > [!WARNING] > > **HTTPS Required**: Camera and microphone access requires HTTPS in production environments. Localhost (`http://localhost` or `http://127.0.0.1`) is exempt during development. ## Permissions Required ### Web * Camera access * Microphone access * Screen capture (for screen sharing) * Notifications (optional) ### iOS ``` NSCameraUsageDescription NSMicrophoneUsageDescription ``` ### Android ```xml theme={null}

``` ## Next Steps > [card] [Key Features](/docs/calls/platform/features) > > Explore all available features > [card] [User Sync](/docs/calls/platform/user-sync) > > Set up user authentication # Key Features Source: https://www.cometchat.com/docs/calls/platform/features Explore CometChat Calls features for one-to-one and group calling, screen sharing, recording, layouts, chat, reactions, and moderation. The Calls SDK includes a comprehensive set of features for building professional calling experiences. Each feature is designed to work seamlessly across platforms while providing the flexibility to customize for your specific use case. ## Core Calling Features ### Voice Calls High-quality audio calls powered by WebRTC with enterprise-grade infrastructure designed for reliability and clarity. **How It Works:** Voice calls use WebRTC's audio processing pipeline with automatic codec selection (Opus preferred) for optimal quality. The SDK handles all the complexity of establishing peer connections, managing ICE candidates, and maintaining stable audio streams. **Technical Capabilities:** * Adaptive bitrate encoding that adjusts to network conditions * Automatic noise cancellation and echo reduction * Automatic gain control for consistent volume levels * Low latency audio streaming optimized for real-time communication * Automatic reconnection on network interruptions **Call Types Supported:** * 1-to-1 private voice calls * Group voice calls with multiple participants * Audio-only mode in video calls **Use Cases:** Customer support calls, team meetings, social audio rooms, telehealth consultations *** ### Video Calls HD video calling with adaptive quality optimization that delivers smooth video across varying network conditions. **How It Works:** Video calls leverage WebRTC's video processing with VP8/VP9/H.264 codec support. The SDK automatically selects the best codec based on browser/device capabilities and negotiates optimal resolution and framerate. **Technical Capabilities:** * HD video support with adaptive bitrate * Automatic quality adjustment based on network conditions * Front/back camera switching on mobile devices * Camera on/off toggle during calls * Video preview before joining calls **Use Cases:** Video consultations, remote interviews, virtual events, family video calls, remote team collaboration *** ### Group Calls Multi-participant calling with intelligent layout management and active speaker detection. **How It Works:** Group calls use a Selective Forwarding Unit (SFU) architecture where media streams are routed through CometChat's servers. This enables efficient bandwidth usage as each participant only uploads one stream while receiving multiple streams. **Participant Features:** * Support for multiple simultaneous video/audio participants * Dynamic participant join/leave handling * Participant list with real-time status (muted, video off) * Active speaker detection and highlighting **Use Cases:** Team meetings, webinars, virtual classrooms, group therapy sessions, online workshops *** ### Call Layouts Three view modes that automatically adapt to participant count and call context. **Available Layouts:** | Layout | Description | Best For | | - | - | - | | **Tile** | Grid layout with equally-sized tiles | Group discussions, team meetings | | **Sidebar** | Main speaker with participants in a sidebar | Presentations, webinars | | **Spotlight** | Large view for active speaker, small tiles for others | One-on-one calls, focused discussions | **Features:** * Set initial layout when joining a session * Switch layouts dynamically during calls * Each participant can independently choose their preferred layout * Automatic layout optimization based on participant count *** ### Screen Sharing Share your screen with other participants during a call. **How It Works:** Screen sharing uses the browser's `getDisplayMedia` API (web) or native screen capture APIs (mobile). The shared content is encoded as a video stream and transmitted to other participants. **Sharing Options (Web):** * Entire screen * Application window * Browser tab **Features:** * Start/stop screen sharing programmatically * Screen share events for local and remote participants * Configurable screen share button visibility * Button click interception for custom behavior **Use Cases:** Software demos, slide presentations, collaborative document editing, remote tech support, code reviews *** ### Recording Server-side call recording with cloud storage for later playback and compliance. **How It Works:** Recording happens on CometChat's media servers, not on participant devices. This ensures consistent quality regardless of individual network conditions and eliminates the risk of lost recordings due to client crashes. > [!NOTE] > > Recording is enabled by default on all CometChat apps. Start it automatically with the `autoStartRecording` setting, or let users start it from the recording button. Recordings are available in the Dashboard under **Calls → Call Logs** and via the [Call Logs API](/docs/rest-api/calls-apis/list-calls). **Features:** * Auto-start recording when session begins (configurable) * Manual start/stop recording during calls * Recording status indicators for all participants * Recording events (started, stopped) * Access recordings via CometChat Dashboard or REST API **Recording Controls:** * `startRecording()` - Begin recording * `stopRecording()` - End recording * `autoStartRecording` setting for automatic recording **Use Cases:** Meeting archives, compliance documentation, training content creation, interview recordings *** ### Virtual Background Replace or blur your real background with AI-powered segmentation for privacy and professionalism. **How It Works:** Virtual backgrounds use machine learning models to segment the person from the background in real-time. The segmentation mask is applied to each video frame, replacing the background with blur or a custom image. **Background Options:** * **Blur**: Gaussian blur applied to background (adjustable intensity via `setVirtualBackgroundBlurLevel`) * **Image**: Custom image as background (via `setVirtualBackgroundImage`) * **Clear**: Remove virtual background (via `clearVirtualBackground`) **Features:** * Built-in virtual background settings dialog * Configurable button visibility * Real-time background replacement **Platform Availability:** JavaScript (Web) only **Browser Requirements:** Modern browser with adequate processing power for best results **Use Cases:** Work from home privacy, professional video calls, hiding messy rooms, branded backgrounds *** ### Audio Modes Switch between different audio output routes on mobile devices. **Available Modes:** | Mode | Description | | - | - | | `SPEAKER` | Routes audio through the device loudspeaker | | `EARPIECE` | Routes audio through the phone earpiece (for private calls) | | `BLUETOOTH` | Routes audio through a connected Bluetooth device | | `HEADPHONES` | Routes audio through wired headphones | **Features:** * Set initial audio mode when joining * Change audio mode dynamically during calls * Audio mode change events via `MediaEventsListener` * Automatic detection of connected audio devices * Configurable audio mode button visibility **Platform Availability:** iOS, Android, React Native, Flutter (mobile platforms only) **Use Cases:** Switching to speaker during long calls, using Bluetooth in car, private calls with earpiece *** ### Raise Hand Virtual hand-raising feature for orderly communication in group calls without verbal interruption. **How It Works:** Participants can raise their hand to signal they want to speak. Other participants see a visual indicator, enabling orderly communication. **Features:** * `raiseHand()` - Show hand-raised indicator * `lowerHand()` - Remove hand-raised indicator * Events for when participants raise/lower hands * Configurable raise hand button visibility **Use Cases:** Q\&A sessions, classroom discussions, moderated panels, orderly group discussions *** ### Idle Timeout Automatic session termination when a participant is alone in a call, preventing abandoned sessions. **How It Works:** When all other participants leave, a countdown timer starts. After the timeout period, a prompt is shown. If no response, the session ends automatically. **Configuration:** * `idleTimeoutPeriodBeforePrompt` - Time before showing the timeout prompt (default: 60 seconds) * `idleTimeoutPeriodAfterPrompt` - Time after prompt before ending session (default: 120 seconds) **Features:** * Configurable timeout periods * Session timeout event (`onSessionTimedOut`) * Can be effectively disabled by setting very long timeout periods **Use Cases:** Preventing forgotten calls, resource management, automatic cleanup *** ## Advanced Features ### Custom Control Panel Build a fully customized control panel by hiding default controls and implementing your own UI. **How It Works:** Configure session settings to hide the default control panel (`hideControlPanel: true`), then implement your own buttons that call SDK actions. **Customization Options:** * Hide entire control panel * Hide individual buttons (mute, video, screen share, recording, etc.) * Intercept button clicks for custom behavior * Build completely custom UI with SDK actions **Available Actions:** * `muteAudio()` / `unMuteAudio()` * `pauseVideo()` / `resumeVideo()` * `switchCamera()` * `startScreenSharing()` / `stopScreenSharing()` * `startRecording()` / `stopRecording()` * `leaveSession()` **Use Cases:** Branded call experience, simplified UI for specific use cases, adding app-specific actions *** ### Picture-in-Picture Continue video calls in a floating window while using other content. **How It Works:** Picture-in-Picture uses the browser's Picture-in-Picture API (web) or native PiP frameworks (Android) to display the call video in a floating overlay window. **Features:** * `enablePictureInPictureLayout()` - Enable PiP mode * `disablePictureInPictureLayout()` - Return to normal view * Floating video window that stays on top * Works when switching tabs or apps **Browser Support (Web):** * Chrome 70+ * Safari 13.1+ * Edge (Chromium-based) * Opera 57+ **Platform Availability:** JavaScript (Web) and Android only **Use Cases:** Multitasking during calls, reference documents while on call, monitoring calls while working *** ### Device Management Select and switch between available cameras and microphones during calls. **How It Works:** The SDK enumerates available media devices and allows users to select their preferred input/output devices. Changes take effect immediately without interrupting the call. **Features:** * `getAudioInputDevices()` - List available microphones * `getAudioOutputDevices()` - List available speakers * `getVideoInputDevices()` - List available cameras * `setAudioInputDevice(deviceId)` - Switch microphone * `setAudioOutputDevice(deviceId)` - Switch speaker * `setVideoInputDevice(deviceId)` - Switch camera * Device change events when devices are connected/disconnected * Built-in settings dialog (`showSettingsDialog()`) **Platform Availability:** JavaScript (Web) only **Use Cases:** Switching to external webcam, using USB microphone, selecting Bluetooth headset *** ### VoIP Calling Native VoIP integration with system-level call handling for a phone-like calling experience. **How It Works:** VoIP calling integrates with the operating system's native call infrastructure (CallKit on iOS, ConnectionService on Android) to provide system-level call UI and lock screen controls. **iOS (CallKit) Features:** * Native iOS incoming call UI (full screen) * Lock screen call controls * Call appears in Phone app's Recents * CarPlay integration * Do Not Disturb respect **Android Features:** * System notification with call controls * Foreground service for reliable call handling * Lock screen call controls **Requirements:** * VoIP push certificate (iOS) * Push notifications configured * Platform-specific implementation (CallManager, PushKit delegate) **Platform Availability:** iOS, Android, React Native **Use Cases:** Phone-like calling experience, reliable incoming calls, car integration *** ### Background Handling Keep calls alive when users navigate away from your app on mobile devices. **How It Works:** Background handling uses platform-specific APIs to keep the call active when the user switches to another app or locks their device. On Android, this is achieved through `CometChatOngoingCallService` - a foreground service. **Android Features:** * `CometChatOngoingCallService.launch()` - Start foreground service * `CometChatOngoingCallService.abort()` - Stop service * Ongoing notification in status bar * Tap notification to return to call * Customizable notification appearance **iOS Features:** * Audio continues in background (requires Background Modes capability) * CallKit integration for lock screen controls * Background task handling **Required Permissions (Android):** ```xml theme={null}

``` **Platform Availability:** iOS, Android, React Native **Use Cases:** Multitasking during calls, checking messages mid-call, hands-free calling *** ### In-Call Chat Enable text messaging during calls by integrating the chat button with your messaging solution. **How It Works:** The SDK provides a chat button in the control panel and events to help you build a custom chat experience. The actual messaging functionality should be implemented using the CometChat Chat SDK or your own messaging solution. **Features:** * Chat button visibility control (`hideChatButton`) * Chat button click events (`onChatButtonClicked`) * Unread message badge (`setChatButtonUnreadCount`) **Integration:** The Calls SDK provides UI hooks, but messaging is handled separately: 1. Show/hide chat button in call UI 2. Listen for chat button clicks 3. Open your chat interface (using CometChat Chat SDK or custom) 4. Update unread badge count **Platform Availability:** All platforms **Use Cases:** Sharing meeting links, posting questions, sharing code snippets, silent communication *** **Platform Availability:** Not all features are available on every platform. See the [Compatibility](/docs/calls/platform/compatibility) page for a detailed feature comparison matrix. ## Next Steps > [card] [Compatibility](/docs/calls/platform/compatibility) > > Check platform and browser support > [card] [User Sync](/docs/calls/platform/user-sync) > > Set up user authentication # What is CometChat Calls? Source: https://www.cometchat.com/docs/calls/platform/overview Learn what CometChat Calls provides for in-app voice and video calling, including call sessions, participants, layouts, and platform support. CometChat Calls SDK provides a complete voice and video calling solution built on WebRTC. It delivers enterprise-grade real-time communication with pre-built UI components, allowing you to add calling functionality to your app in minutes rather than months. ## Why CometChat Calls? Building real-time voice and video calling from scratch requires expertise in WebRTC, media servers, network optimization, and cross-platform development. CometChat handles all this complexity so you can focus on your core product. | Benefit | Description | | - | - | | **Built-in UI** | Pre-built call screens, controls, and participant views—no UI work required | | **WebRTC Powered** | Enterprise-grade media infrastructure handles all the complexity | | **Cross-Platform** | Web, iOS, Android, React Native, and Flutter with consistent APIs | | **Scalable Infrastructure** | Global media servers with automatic scaling and low latency | ## How It Works 1. **Initialize** — Set up the SDK with your App ID and Region 2. **Authenticate** — Log in users with their CometChat auth token 3. **Join Call** — Generate a session token and join the call 4. **Ready** — The SDK renders a complete call UI automatically > [!NOTE] > > **Already using CometChat UI Kits?** Voice and video calling is already integrated with ready-to-use components. Use the Calls SDK directly only if you need custom call UI or advanced control. ## Use Cases CometChat Calls powers real-time communication across industries: | Industry | Use Cases | | - | - | | **Healthcare** | Telehealth consultations, patient check-ins, specialist referrals | | **Education** | Virtual classrooms, tutoring sessions, parent-teacher meetings | | **Marketplace** | Buyer-seller negotiations, customer support, expert consultations | | **Social** | Video dating, group hangouts, live streaming | | **Enterprise** | Team meetings, remote interviews, client calls | | **Gaming** | Voice chat, team coordination, live commentary | ## What's Included > [card] Voice & Video Calls > > 1-to-1 and group calls with HD audio/video, adaptive bitrate, and noise cancellation > [card] Rich Call Controls > > Mute, screen share, recording, layouts, participant management, and more > [card] Pre-built UI > > Complete call screens with controls, participant grid, and responsive layouts > [card] Platform SDKs > > Native SDKs for JavaScript, iOS, Android, React Native, and Flutter ## How Calling Minutes Are Counted Calling usage is measured in **user-minutes**: ```text theme={null} user-minutes = call duration (minutes) × number of participants ``` | Call duration | Participants | User-minutes | | - | - | - | | 50 minutes | 2 | 50 × 2 = **100** | | 50 minutes | 10 | 50 × 10 = **500** | > [!NOTE] > > Voice and video minutes are counted from a **single combined pool**. The 10,000 minutes on the free plan cover voice and video calls together — not 10,000 minutes of each. **No fixed maximum call duration:** A call session has no built-in time limit. It runs until participants leave, or until the idle timeout ends it after a user has been left alone in the call. Idle timeout periods are configurable and their defaults differ by SDK — see [Idle Timeout](/docs/calls/platform/features#idle-timeout) and the platform guides for [JavaScript](/docs/calls/javascript/idle-timeout), [React Native](/docs/calls/react-native/idle-timeout), [iOS](/docs/calls/ios/idle-timeout), [Android](/docs/calls/android/idle-timeout), and [Flutter](/docs/calls/flutter/idle-timeout). To inspect minutes for individual calls, use the [Calls APIs](/docs/rest-api/calls-apis/overview), which return `totalAudioMinutes` and `totalVideoMinutes` for each call and each participant. ## Next Steps > [card] [Key Features](/docs/calls/platform/features) > > Explore all available features in detail > [card] [Compatibility](/docs/calls/platform/compatibility) > > Check platform and browser support # User Sync Source: https://www.cometchat.com/docs/calls/platform/user-sync Sync users with CometChat Calls so app users can authenticate, join sessions, appear in participants, and use calling features. Users must exist in CometChat before they can make or receive calls. This page explains how to create and authenticate users for the Calls SDK. ## Why User Sync? CometChat needs to know about your users to: * **Route calls** — Connect callers to the right recipients * **Identify participants** — Display names and avatars in calls * **Track history** — Associate call logs with specific users * **Manage permissions** — Control who can call whom ## Creating Users Choose the method that best fits your workflow: > [card] [Dashboard](https://app.cometchat.com/) > > Add users manually via the CometChat Dashboard. Ideal for quick testing or small teams. > [card] [SDK](/docs/sdk/javascript/user-management) > > Create users programmatically via SDK methods. Perfect for auto-provisioning during sign-up. > [card] [REST API](/docs/rest-api/users/create) > > Create users using the REST API. Best for batch imports or backend workflows. ## User Requirements ### Required Fields | Field | Type | Description | | :- | :- | :- | | `uid` | String | Unique user identifier. Alphanumeric, max 100 characters. Must be unique across your app. | ### Optional Fields | Field | Type | Description | | :- | :- | :- | | `name` | String | Display name shown in calls and participant lists | | `avatar` | String | URL to profile image | | `metadata` | Object | Custom JSON data for your application | | `role` | String | User role (default, admin, etc.) | | `tags` | Array | Tags for categorization and filtering | ### Example User Object ```json theme={null} { "uid": "user_123", "name": "John Doe", "avatar": "https://example.com/avatars/john.png", "metadata": { "department": "Engineering", "location": "San Francisco" } } ``` ## Authentication Flow **1. Create User (One-time)** Create the user in CometChat when they sign up for your app. This only needs to happen once per user. **Server-side (recommended):** ```bash theme={null} curl -X POST "https://api-{region}.cometchat.io/v3/users" \ -H "apiKey: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"uid": "user_123", "name": "John Doe"}' ``` **2. Generate Auth Token** Generate an authentication token for the user on your server. This token is used to log in the user on the client. **Server-side:** ```bash theme={null} curl -X POST "https://api-{region}.cometchat.io/v3/users/{uid}/auth_tokens" \ -H "apiKey: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json theme={null} { "data": { "uid": "user_123", "authToken": "user_123_abc123xyz..." } } ``` **3. Login User (Client-side)** Use the auth token to log in the user via the SDK. This establishes a session for making calls. **JavaScript:** ```javascript theme={null} CometChatCalls.login(authToken).then( user => console.log("Login successful:", user), error => console.log("Login failed:", error) ); ``` **4. Ready for Calls** Once logged in, the user can initiate and receive calls. The SDK handles all session management automatically. ## Authentication Methods ### Auth Token (Recommended for Production) Generate tokens server-side using the REST API. This is the secure method for production apps. **Pros:** * Secure — API key never exposed to clients * Controlled — You decide when tokens are issued * Auditable — Token generation can be logged **Flow:** 1. User logs into your app 2. Your server generates a CometChat auth token 3. Token is sent to the client 4. Client uses token to log into CometChat ### Auth Key (Development Only) Use the Auth Key directly in client code for quick testing. **Never use in production.** **JavaScript:** ```javascript theme={null} CometChatCalls.login(uid, authKey).then( user => console.log("Login successful:", user), error => console.log("Login failed:", error) ); ``` > [!WARNING] > > **Security Warning**: Never expose your Auth Key in production client code. Auth Keys have full access to create users and perform admin operations. Always use auth tokens generated server-side for production apps. ## Sync Strategies ### Just-in-Time Provisioning Create CometChat users when they first need calling functionality: ```javascript theme={null} // When user initiates their first call async function ensureUserExists(user) { try { // Try to get auth token (user exists) return await getAuthToken(user.id); } catch (error) { // User doesn't exist, create them first await createCometChatUser(user); return await getAuthToken(user.id); } } ``` **Best for:** Apps where not all users need calling ### Batch Import Import existing users via REST API when integrating CometChat: ```bash theme={null} # Create multiple users curl -X POST "https://api-{region}.cometchat.io/v3/users" \ -H "apiKey: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '[ {"uid": "user_1", "name": "Alice"}, {"uid": "user_2", "name": "Bob"}, {"uid": "user_3", "name": "Charlie"} ]' ``` **Best for:** Migrating existing user bases ### Webhook Sync Use webhooks to keep CometChat users in sync with your database: 1. User signs up → Create CometChat user 2. User updates profile → Update CometChat user 3. User deletes account → Delete CometChat user **Best for:** Apps with frequent user changes ## User Lifecycle ### Creating Users Users can be created via: * REST API (server-side) * SDK `createUser` method * Dashboard (manual) ### Updating Users Update user details when they change in your app: ```bash theme={null} curl -X PUT "https://api-{region}.cometchat.io/v3/users/{uid}" \ -H "apiKey: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "John Smith", "avatar": "https://new-avatar.png"}' ``` ### Deleting Users Remove users when they leave your platform: ```bash theme={null} curl -X DELETE "https://api-{region}.cometchat.io/v3/users/{uid}" \ -H "apiKey: YOUR_API_KEY" ``` > [!NOTE] > > **Soft Delete**: By default, deleted users are soft-deleted and can be restored. Use `permanent=true` query parameter for permanent deletion. ## Best Practices ### Do * Generate auth tokens server-side * Use consistent UIDs across your app * Keep user data in sync * Handle token expiration gracefully ### Don't * Expose API keys in client code * Use Auth Key in production * Create duplicate users * Store auth tokens long-term ## Next Steps > [card] [Compatibility](/docs/calls/platform/compatibility) > > Check platform and browser support > [card] [REST API Reference](/docs/rest-api/users/create) > > Full API documentation for user management # Error Codes Source: https://www.cometchat.com/docs/rest-api/management-apis/error-codes Error Codes for CometChat REST API. Error codes specific to the Management APIs (Multi-Tenancy). ## App Management | Error Code | Description | | - | - | | `ERR_APP_CREATION_FAILED_MAX_LIMIT` | You have reached the maximum number of complimentary apps allowed. Delete an existing app or upgrade to a paid plan, then try again. | | `ERR_APP_ARCHIVED` | The app has been archived and will be permanently deleted after 30 days. | | `ERR_APP_DELETION` | The app is associated with a paid subscription. Contact CometChat support before deleting. | | `ERR_APP_NOT_FOUND` | The App ID does not exist or has been archived. | ## Extensions | Error Code | Description | | - | - | | `ERR_EXTENSION_NOT_FOUND` | The provided extension ID does not correspond to any existing microservice. | | `ERR_EXTENSION_INACTIVE` | The operation failed because the extension is currently inactive. | ## Team Management | Error Code | Description | | - | - | | `ERR_ALREADY_AN_OWNER` | The user is already registered as an owner of the app. | | `ERR_SELF_ACTION_DENIED` | A user cannot add themselves as a collaborator. | | `ERR_NOT_A_COLLABORATOR` | The specified email is not a collaborator for this app. | ## Webhooks | Error Code | Description | | - | - | | `ERR_WEBHOOK_NOT_FOUND` | The webhook does not exist. | | `ERR_BAD_REQUEST` | Validation error in the request. | | `AUTH_ERR_EMPTY_AUTH_HEADER` | The authentication header is missing. | # Chatwoot Delete settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/chatwoot-delete-settings delete /apps/{appId}/extensions/chatwoot/v1/settings Chatwoot : Delete the settings for Chatwoot extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Chatwoot Get settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/chatwoot-get-settings get /apps/{appId}/extensions/chatwoot/v1/settings Chatwoot : Get settings for Chatwoot extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Chatwoot Store settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/chatwoot-store-settings post /apps/{appId}/extensions/chatwoot/v1/settings Chatwoot : Store new settings for Chatwoot extension For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Chatwoot Update settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/chatwoot-update-settings put /apps/{appId}/extensions/chatwoot/v1/settings Chatwoot : Update the settings for Chatwoot extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Data masking Delete settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/data-masking-delete-settings delete /apps/{appId}/extensions/data-masking/v1/settings Data masking : Delete the settings for Data masking extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Data masking Get Settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/data-masking-get-settings get /apps/{appId}/extensions/data-masking/v1/settings Data masking : Get the settings for Data masking extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Data masking Store or update settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/data-masking-store-or-update-settings put /apps/{appId}/extensions/data-masking/v1/settings Data masking : Store or update the settings for Data masking extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Email Notification Delete settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/email-notification-delete-settings delete /apps/{appId}/extensions/email-notification/v1/settings Email Notification : Delete the settings for Email notification extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Email Notification Get settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/email-notification-get-settings get /apps/{appId}/extensions/email-notification/v1/settings Email Notification : Get settings for Email notification extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Email Notification Store settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/email-notification-store-settings post /apps/{appId}/extensions/email-notification/v1/settings Email Notification : Store new settings for Email notification extension For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Email Notification Update settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/email-notification-update-settings put /apps/{appId}/extensions/email-notification/v1/settings Email Notification : Update the settings for Email notification extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Email replies Delete settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/email-replies-delete-settings delete /apps/{appId}/extensions/email-replies/v1/settings Email replies : Delete the settings for Email replies extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Email replies Get settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/email-replies-get-settings get /apps/{appId}/extensions/email-replies/v1/settings Email replies : Get settings for Email replies extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Email replies Store settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/email-replies-store-settings post /apps/{appId}/extensions/email-replies/v1/settings Email replies : Store new settings for Email replies extension For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Email replies Update settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/email-replies-update-settings put /apps/{appId}/extensions/email-replies/v1/settings Email replies : Update the settings for Email replies extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # End-to-end encryption Delete settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/end-to-end-encryption-delete-settings delete /apps/{appId}/extensions/e2ee/v1/settings End-to-end encryption : Delete the settings for End-to-end encryption extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # End-to-end encryption Get settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/end-to-end-encryption-get-settings get /apps/{appId}/extensions/e2ee/v1/settings End-to-end encryption : Get settings for End-to-end encryption extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # End-to-end encryption Store settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/end-to-end-encryption-store-settings post /apps/{appId}/extensions/e2ee/v1/settings End-to-end encryption : Store new settings for End-to-end encryption extension For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # End-to-end encryption Update settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/end-to-end-encryption-update-settings put /apps/{appId}/extensions/e2ee/v1/settings End-to-end encryption : Update the settings for End-to-end encryption extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # In-flight message moderation Delete settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/in-flight-message-moderation-delete-settings delete /apps/{appId}/extensions/human-moderation/v1/settings In-flight message moderation : Delete the settings for In-flight message moderation extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # In-flight message moderation Store settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/in-flight-message-moderation-store-settings post /apps/{appId}/extensions/human-moderation/v1/settings In-flight message moderation : Store new settings for In-flight message moderation extension For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Message Shortcuts Delete settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/message-shortcuts-delete-settings delete /apps/{appId}/extensions/message-shortcuts/v1/settings Message Shortcuts : Delete the settings for Message shortcuts extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Message Shortcuts Get settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/message-shortcuts-get-settings get /apps/{appId}/extensions/message-shortcuts/v1/settings Message Shortcuts : Get settings for Message shortcuts extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Message Shortcuts Store settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/message-shortcuts-store-settings post /apps/{appId}/extensions/message-shortcuts/v1/settings Message Shortcuts : Store new settings for Message shortcuts extension For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Message Shortcuts Update settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/message-shortcuts-update-settings put /apps/{appId}/extensions/message-shortcuts/v1/settings Message Shortcuts : Update the settings for Message shortcuts extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Profanity-filter Adds Settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/profanity-filter-adds-settings post /apps/{appId}/extensions/profanity-filter/v1/settings Profanity-filter : Adds settings an app. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Profanity-filter Delete settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/profanity-filter-delete-settings delete /apps/{appId}/extensions/profanity-filter/v1/settings Profanity-filter : Delete the settings for Profanity-filter extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Profanity-filter Get Settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/profanity-filter-get-settings get /apps/{appId}/extensions/profanity-filter/v1/settings Profanity-filter : Get settings of an app. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Profanity-filter Update settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/profanity-filter-update-settings put /apps/{appId}/extensions/profanity-filter/v1/settings Profanity-filter : Update the settings for Profanity-filter extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Push notification Delete settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/push-notification-delete-settings delete /apps/{appId}/extensions/push-notification/v1/settings Push notification : Delete the settings for Push notifications extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Push notification Get Certificate Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/push-notification-get-certificate get /apps/{appId}/extensions/push-notification/v1/query-certificates Push notification : Get Certificate description For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Push notification Get settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/push-notification-get-settings get /apps/{appId}/extensions/push-notification/v1/settings Push notification : Get settings for Push notifications extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Push notification Store settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/push-notification-store-settings post /apps/{appId}/extensions/push-notification/v1/settings Push notification : Store new settings for Push notifications extension For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Push notification Update settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/push-notification-update-settings put /apps/{appId}/extensions/push-notification/v1/settings Push notification : Update the settings for Push notifications extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Push notification Upload p12 Certificate Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/push-notification-upload-p12-certificate post /apps/{appId}/extensions/push-notification/v1/upload-certificate-p12 Push notification : Upload a p12 Certificate For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Push notification Upload p8 Certificate Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/push-notification-upload-p8-certificate post /apps/{appId}/extensions/push-notification/v1/upload-certificate-p8 Push notification : Upload a p8 Certificate For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # SMS Notification Delete settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/sms-notification-delete-settings delete /apps/{appId}/extensions/sms-notification/v1/settings SMS Notification : Delete the settings for SMS Notification extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # SMS Notification Get settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/sms-notification-get-settings get /apps/{appId}/extensions/sms-notification/v1/settings SMS Notification : Get settings for SMS Notification extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # SMS Notification Store settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/sms-notification-store-settings post /apps/{appId}/extensions/sms-notification/v1/settings SMS Notification : Store new settings for SMS Notification extension For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # SMS Notification Update settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/sms-notification-update-settings put /apps/{appId}/extensions/sms-notification/v1/settings SMS Notification : Update the settings for SMS Notification extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Stickers extension Delete settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/stickers-extension-delete-settings delete /apps/{appId}/extensions/stickers/v1/settings Stickers extension : Delete the settings for Stickers extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Stickers extension Get settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/stickers-extension-get-settings get /apps/{appId}/extensions/stickers/v1/settings Stickers extension : Get settings for Stickers extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Stickers extension Update settings Source: https://www.cometchat.com/docs/rest-api/management-apis/extensions/stickers-extension-update-settings put /apps/{appId}/extensions/stickers/v1/settings Stickers extension : Update the settings for Stickers extension. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Properties and Constraints Source: https://www.cometchat.com/docs/rest-api/management-apis/properties-and-constraints Properties and Constraints for CometChat REST API. Properties and constraints for the Management APIs (Multi-Tenancy). ## App Management | **Property** | **Constraints** | | - | - | | App name | Max 100 characters, UTF8mb4 (supports all languages and emojis) | | App version | `v3` only | | Maximum collaborators per app (team management) | 25 | ## Webhooks | **Property** | **Constraints** | | - | - | | Maximum webhooks per app | 25 | | Webhook URL | Valid URL, max 255 characters | | Webhook ID | Max 50 characters, alphanumeric only, no spaces | | Webhook authentication username | Max 50 characters, alphanumeric only, no spaces | | Webhook authentication password | Max 100 characters, alphanumeric only, no spaces | # List settings Source: https://www.cometchat.com/docs/rest-api/management-apis/settings/list-settings get /apps/{appId}/settings Check which settings are available and how to call each one from the management API, so the integration stays configured correctly. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Maps Settings Source: https://www.cometchat.com/docs/rest-api/management-apis/settings/maps-settings post /apps/{appId}/settings Configure map provider keys and limits for CometChat messaging, then troubleshoot related errors with the linked error guide. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # UnMaps settings Source: https://www.cometchat.com/docs/rest-api/management-apis/settings/unmaps-settings delete /apps/{appId}/settings Manages unmapped settings behavior for CometChat REST API calls, with linked error codes for handling failed requests. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Adds/Remove collaborators Source: https://www.cometchat.com/docs/rest-api/management-apis/team-management/addsremove-collaborators post /apps/{appId}/collaborators Adds or removes collaborators for an app. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # List collaborators Source: https://www.cometchat.com/docs/rest-api/management-apis/team-management/list-collaborators get /apps/{appId}/collaborators Lists all the collaborators of an app. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Add Triggers Source: https://www.cometchat.com/docs/rest-api/management-apis/webhooks/add-triggers post /apps/{appId}/webhooks/{webhookId}/triggers Adds trigger to a webhook in an app. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Create Webhook Source: https://www.cometchat.com/docs/rest-api/management-apis/webhooks/create-webhook post /apps/{appId}/webhooks Set up a webhook, test it against the full error list, and fix failures without digging through separate guides. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Delete Webhook Source: https://www.cometchat.com/docs/rest-api/management-apis/webhooks/delete-webhook delete /apps/{appId}/webhooks/{webhookId} Delete the webhook from an app. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Get Webhook Source: https://www.cometchat.com/docs/rest-api/management-apis/webhooks/get-webhook get /apps/{appId}/webhooks/{webhookId} Gets details of a webhook in an app. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # List Triggers Source: https://www.cometchat.com/docs/rest-api/management-apis/webhooks/list-triggers get /apps/{appId}/webhooks/{webhookId}/triggers List triggers attached to a webhook in an app. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # List Webhooks Source: https://www.cometchat.com/docs/rest-api/management-apis/webhooks/list-webhooks get /apps/{appId}/webhooks Shows how to retrieve every webhook configured for an app, with pagination and error handling details included. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Overview Source: https://www.cometchat.com/docs/rest-api/management-apis/webhooks/overview Review CometChat management webhook properties for event payloads, webhook configuration, and REST API integrations. > [!NOTE] > > 1. The Webhook API documentation provides comprehensive guidance on how to integrate and utilize Webhook functionality for real-time event-driven communication. > 2. Our platform is designed around the concept of event-driven communication. It allows your applications to subscribe to specific events and receive instant notifications when these events occur. ### Please review the following requirements for setting up your webhook endpoint > [!NOTE] > > 1. Your webhook endpoint must be accessible over HTTPS. This is essential to ensure the security and integrity of data transmission. > 2. Provide us with the URL where you'd like to receive webhook payloads. Webhook payloads would be in JSON format. This URL should be publicly accessible from the internet. > 3. Ensure that your endpoint supports the HTTP POST method. Webhook payloads will be delivered via HTTP POST requests. > 4. Configure your endpoint to respond immediately to the CometChat server with a 200 OK response. > 5. We recommend you use Basic Auth while configuring webhook, so as to validate incoming webhook requests. Here is the list of properties associated with Webhook. | Parameters | Type | Description | | - | - | - | | id | string | Unique identifier of the webhook. It can have a maximum of 50 characters. | | name | string | Display name of the webhook. It can have a maximum of 50 characters. | | webhookURL | string | The webhookURL field represents the target URL to which webhook events will be delivered. | | useBasicAuth | boolean | The useBasicAuth field is a boolean flag that indicates whether basic authentication should be applied when sending webhook requests to the specified webhookURL | | username | string | This field should contain the username or identifier associated with the authentication credentials. | | password | string | This field should contain the secret password that corresponds to the provided username. | | enabled | boolean | The enabled field is a boolean flag that determines whether a webhook is currently active and capable of receiving and processing incoming events | ## Constraints | Item | Constraint | Notes | | - | - | - | | Maximum webhooks per app | 25 | Contact support if you need more | | Webhook URL | 255 characters max | Must be a publicly accessible HTTPS endpoint | | Webhook ID | 50 characters, alphanumeric (UTF8mb4, no spaces) | Unique identifier for managing the webhook | | Authentication username | 50 characters, alphanumeric (no spaces) | Used for HTTP Basic Authentication | | Authentication password | 100 characters, alphanumeric (no spaces) | Keep secure; used to verify webhook requests | ### The list of triggers that are supported | triggerId | Description | | - | - | | [`message_sent`](#message_sent) | The hook triggers after the message is sent. | | [`message_edited`](#message_edited) | The hook triggers after the message is edited. | | [`message_deleted`](#message_deleted) | The hook triggers after the message is deleted. | | [`message_reaction_added`](#message_reaction_added) | The hook triggers after reaction is added to a message. | | [`message_reaction_removed`](#message_reaction_removed) | The hook triggers after reaction is removed from a message. | | [`user_blocked`](#user_blocked) | The hook triggers when a user blocks another user. | | [`user_unblocked`](#user_unblocked) | The hook triggers when a user unblocks another user. | | [`group_created`](#group_created) | The hook triggers after the group is created. | | [`group_updated`](#group_updated) | The hook triggers after the group is updated. | | [`group_deleted`](#group_deleted) | The hook triggers after the group is deleted. | | [`group_member_joined`](#group_member_joined) | The hook triggers after a user joins a group. | | [`group_member_left`](#group_member_left) | The hook triggers after a user leaves the group. | | [`group_member_added`](#group_member_added) | The hook triggers after members are added to a group. | | [`group_member_kicked`](#group_member_kicked) | The hook triggers after members are kicked from a group. | | [`group_member_banned`](#group_member_banned) | The hook triggers after members are banned from a group. | | [`group_member_unbanned`](#group_member_unbanned) | The hook triggers after members are unbanned from a group. | | [`group_member_scope_changed`](#group_member_scope_changed) | The hook triggers if the scope of a member changes in a group. | | [`group_owner_transferred`](#group_owner_transferred) | The hook triggers if the owner of the group is changed. | | [`user_connection_status_changed`](#user_connection_status_changed) | The hook triggers after a user connects/disconnects from the websocket server. | | [`message_delivery_receipt`](#message_delivery_receipt) | The hook triggers when the client chat application confirms with Cometchat servers that a message was delivered. | | [`message_read_receipt`](#message_read_receipt) | The hook triggers when the client chat application confirms with Cometchat servers that a message was read. | | [`call_initiated`](#call_initiated) | The hook triggers when the call is initiated. | | [`call_started`](#call_started) | The hook triggers when the call is started. | | [`call_participant_joined`](#call_participant_joined) | The hook triggers when a participant joins the call. | | [`call_participant_left`](#call_participant_left) | The hook triggers when a participant leaves the call. | | [`call_ended`](#call_ended) | The hook triggers when the call is ended. | | [`meeting_started`](#meeting_started) | The hook triggers when a meeting is started. | | [`meeting_participant_joined`](#meeting_participant_joined) | The hook triggers when a participant joins the meeting. | | [`meeting_participant_left`](#meeting_participant_left) | The hook triggers when a participant leaves the meeting. | | [`meeting_ended`](#meeting_ended) | The hook triggers when the meeting is ended. | | [`recording_generated`](#recording_generated) | The hook triggers when the recording is generated. | | [`transcription_generated`](#transcription_generated) | The hook triggers when the transcript is generated. | | [`after_campaign_completed`](#after_campaign_completed) | The hook triggers when a campaign finishes sending to all targets. | | [`after_campaign_failed`](#after_campaign_failed) | The hook triggers when a campaign fails to deliver to its targets. | | [`after_notification_created`](#after_notification_created) | The hook triggers when a notification is created and begins dispatching. | | [`after_feed_item_sent`](#after_feed_item_sent) | The hook triggers when an in-app feed item is sent to a user. | | [`after_feed_item_delivered`](#after_feed_item_delivered) | The hook triggers when a feed item is delivered to the user's device. | | [`after_feed_item_read`](#after_feed_item_read) | The hook triggers when a user reads a feed item. | | [`after_feed_item_interacted`](#after_feed_item_interacted) | The hook triggers when a user interacts with a feed item. | | [`after_push_notification_sent`](#after_push_notification_sent) | The hook triggers when a push notification is sent. | | [`after_push_notification_delivered`](#after_push_notification_delivered) | The hook triggers when a push notification is delivered to the user's device. | | [`after_push_notification_clicked`](#after_push_notification_clicked) | The hook triggers when a user clicks on a push notification. | | [`moderation_engine_approved`](#moderation_engine_approved) | The hook triggers when moderation approves a message. | | [`moderation_engine_blocked`](#moderation_engine_blocked) | The hook triggers when moderation blocks a message. | | [`moderation_manual_approved`](#moderation_manual_approved) | The hook triggers when a moderator manually approves a previously blocked message. | | [`moderation_engine_failed`](#moderation_engine_failed) | The hook triggers when an AI moderation engine could not return a decision. | ### Payload structure of events #### Groups ##### group_created: ```json group_created theme={null} { "trigger":"group_created", "data":{ "group":{ "guid":"cometchat-guid-1", "name":"Hiking Group", "type":"public", "scope":"admin", "membersCount":1, "joinedAt":1696932915, "conversationId":"group_cometchat-guid-1", "hasJoined":true, "createdAt":1696932915, "owner":"cometchat-uid-1" }, "members":{ "cometchat-uid-1":{ "uid":"cometchat-uid-1", "name":"Andrew Joseph", "status":"available", "role":"default", "lastActiveAt":1696932834 } } }, "appId":"", "region":"", "webhook":"" } ``` ##### group_updated: ```json group_updated theme={null} { "trigger": "group_updated", "data": { "group": { "guid": "cometchat-guid-1", "name": "Hiking Group", "type": "public", "membersCount": 2, "conversationId": "group_cometchat-guid-1", "createdAt": 1695728507, "owner": "cometchat-uid-2", "updatedAt": 1696934048, "updatedBy": "cometchat-uid-1", "onlineMembersCount": 2 } }, "appId": "", "region": "", "webhook": "" } ``` ##### group_deleted: ```json group_deleted theme={null} { "trigger": "group_deleted", "data": { "group": { "guid": "cometchat-guid-1", "name": "1234", "type": "public", "membersCount": 1, "conversationId": "group_cometchat-guid-1", "createdAt": 1695722912, "owner": "cometchat-uid-1", "updatedAt": 1695817083, "updatedBy": "cometchat-uid-1", "onlineMembersCount": 1 } }, "appId": "", "region": "", "webhook": "" } ``` ##### group_owner_transferred: ```json group_owner_transferred theme={null} { "trigger": "group_owner_transferred", "data": { "group": { "guid": "cometchat-guid-1", "name": "Hiking Group", "type": "public", "membersCount": 2, "conversationId": "group_cometchat-guid-1", "createdAt": 1695728507, "owner": "cometchat-uid-2", "updatedAt": 1696933737, "updatedBy": "cometchat-uid-1", "onlineMembersCount": 2, "oldOwner": "cometchat-uid-1" } }, "appId": "", "region": "", "webhook": "" } ``` ##### group_member_added: ```json group_member_added theme={null} { "trigger": "group_member_added", "data": { "group": { "guid": "cometchat-guid-1", "name": "Hiking Group", "type": "public", "membersCount": 2, "conversationId": "group_cometchat-guid-1", "createdAt": 1696932915, "owner": "cometchat-uid-1", "onlineMembersCount": 1 }, "members": { "cometchat-uid-2": { "uid": "cometchat-uid-2", "name": "George Alan", "avatar": "https://example.com/avatars/george-alan.png", "status": "offline", "role": "default", "lastActiveAt": 1695751453, "conversationId": "cometchat-uid-1_user_cometchat-uid-2" } }, "by": { "uid": "cometchat-uid-1", "name": "Andrew Joseph", "avatar": "https://example.com/avatars/andrew-joseph.png", "status": "available", "role": "default", "lastActiveAt": 1696932834 } }, "appId": "", "region": "", "webhook": "" } ``` ##### group_member_banned: ```json group_member_banned theme={null} { "trigger": "group_member_banned", "data": { "group": { "guid": "cometchat-guid-1", "name": "Hiking Group", "type": "public", "membersCount": 1, "conversationId": "group_group__1696932914913", "createdAt": 1696932915, "owner": "cometchat-uid-1", "updatedAt": 1696933533, "onlineMembersCount": 1 }, "members": { "cometchat-uid-2": { "uid": "cometchat-uid-2", "name": "George Alan", "avatar": "https://example.com/avatars/george-alan.png", "status": "offline", "role": "default", "lastActiveAt": 1695751453, "conversationId": "cometchat-uid-1_user_cometchat-uid-2" } }, "by": { "uid": "cometchat-uid-1", "name": "Andrew Joseph", "avatar": "https://example.com/avatars/andrew-joseph.png", "status": "available", "role": "default", "lastActiveAt": 1696932834 } }, "appId": "", "region": "", "webhook": "" } ``` ##### group_member_unbanned: ```json group_member_unbanned theme={null} { "trigger": "group_member_unbanned", "data": { "members": { "cometchat-uid-2": { "uid": "cometchat-uid-2", "name": "George Alan", "avatar": "https://example.com/avatars/george-alan.png", "status": "offline", "role": "default", "lastActiveAt": 1695751453, "conversationId": "cometchat-uid-1_user_cometchat-uid-2" } }, "group": { "guid": "cometchat-guid-1", "name": "Hiking Group", "type": "public", "membersCount": 1, "conversationId": "group_cometchat-guid-1", "createdAt": 1696932915, "owner": "cometchat-uid-1", "updatedAt": 1696933533, "onlineMembersCount": 1 }, "by": { "uid": "cometchat-uid-1", "name": "Andrew Joseph", "avatar": "https://example.com/avatars/andrew-joseph.png", "status": "available", "role": "default", "lastActiveAt": 1696932834 } }, "appId": "", "region": "", "webhook": "" } ``` ##### group_member_joined: ```json group_member_joined theme={null} { "trigger": "group_member_joined", "data": { "members": { "cometchat-uid-2": { "uid": "cometchat-uid-2", "name": "George Alan", "avatar": "https://example.com/avatars/george-alan.png", "status": "available", "role": "default", "lastActiveAt": 1696933689 } }, "group": { "guid": "cometchat-guid-1", "name": "Hiking Group", "type": "public", "membersCount": 2, "conversationId": "group_cometchat-guid-1", "createdAt": 1695728507, "owner": "cometchat-uid-1", "updatedAt": 1696933691, "onlineMembersCount": 1 } }, "appId": "", "region": "", "webhook": "" } ``` ##### group_member_left: ```json group_member_left theme={null} { "trigger": "group_member_left", "data": { "members": { "cometchat-uid-2": { "uid": "cometchat-uid-2", "name": "George Alan", "avatar": "https://example.com/avatars/george-alan.png", "status": "available", "role": "default", "lastActiveAt": 1696933689 } }, "group": { "guid": "cometchat-guid-1", "name": "Hiking Group", "type": "public", "membersCount": 1, "conversationId": "group_cometchat-guid-1", "createdAt": 1695722891, "owner": "cometchat-uid-1", "updatedAt": 1696933827, "onlineMembersCount": 1 } }, "appId": "", "region": "", "webhook": "" } ``` ##### group_member_scope_changed: ```json group_member_scope_changed theme={null} { "trigger": "group_member_scope_changed", "data": { "members": { "cometchat-uid-2": { "uid": "cometchat-uid-2", "name": "George Alan", "avatar": "https://example.com/avatars/george-alan.png", "status": "available", "role": "default", "lastActiveAt": 1696933928, "conversationId": "cometchat-uid-1_user_cometchat-uid-2", "scope": "admin", "oldScope": "participant" } }, "group": { "guid": "cometchat-guid-1", "name": "Hiking Group", "type": "public", "membersCount": 2, "conversationId": "group_cometchat-guid-1", "createdAt": 1695722891, "owner": "cometchat-uid-1", "updatedAt": 1696933925, "onlineMembersCount": 2 }, "by": { "uid": "cometchat-uid-1", "name": "Andrew Joseph", "avatar": "https://example.com/avatars/andrew-joseph.png", "status": "available", "role": "default", "lastActiveAt": 1696933934 } }, "appId": "", "region": "", "webhook": "" } ``` ##### group_member_kicked: ```json group_member_kicked theme={null} { "trigger": "group_member_kicked", "data": { "members": { "cometchat-uid-2": { "uid": "cometchat-uid-2", "name": "George Alan", "avatar": "https://example.com/avatars/george-alan.png", "status": "available", "role": "default", "lastActiveAt": 1696933689, "conversationId": "cometchat-uid-1_user_cometchat-uid-2" } }, "group": { "guid": "cometchat-guid-1", "name": "Hiking Group", "type": "public", "membersCount": 1, "conversationId": "group_cometchat-guid-1", "createdAt": 1695722891, "owner": "cometchat-uid-1", "updatedAt": 1696933889, "onlineMembersCount": 8 }, "by": { "uid": "cometchat-uid-1", "name": "Andrew Joseph", "avatar": "https://example.com/avatars/andrew-joseph.png", "status": "available", "role": "default", "lastActiveAt": 1696933881 } }, "appId": "", "region": "", "webhook": "" } ``` #### Messages ##### message_sent: ```json message_sent theme={null} { "trigger": "message_sent", "data": { "message": { "id": "1", "conversationId": "cometchat-uid-1_user_cometchat-uid-2", "sender": "cometchat-uid-1", "receiverType": "user", "receiver": "cometchat-uid-2", "category": "message", "type": "text", "data": { "text": "hi", "entities": { "sender": { "entity": { "uid": "cometchat-uid-1", "name": "Andrew Joseph", "avatar": "https://example.com/avatars/andrew-joseph.png", "status": "available", "role": "default", "lastActiveAt": 1696934440 }, "entityType": "user" }, "receiver": { "entity": { "uid": "cometchat-uid-2", "name": "George Alan", "avatar": "https://example.com/avatars/george-alan.png", "status": "available", "role": "default", "lastActiveAt": 1696934491, "conversationId": "cometchat-uid-1_user_cometchat-uid-2" }, "entityType": "user" } } }, "sentAt": 1696934912, "updatedAt": 1696934912 } }, "appId": "", "region": "", "webhook": "" } ``` ##### message_edited: ```json message_edited theme={null} { "trigger": "message_edited", "data": { "message": { "id": "2", "conversationId": "cometchat-uid-1_user_cometchat-uid-2", "sender": "cometchat-uid-1", "receiverType": "user", "receiver": "cometchat-uid-2", "category": "action", "type": "message", "data": { "action": "edited", "entities": { "by": { "entity": { "uid": "cometchat-uid-1", "name": "Andrew Joseph", "avatar": "https://example.com/avatars/andrew-joseph.png", "status": "available", "role": "default", "lastActiveAt": 1696934440 }, "entityType": "user" }, "on": { "entity": { "id": "1", "conversationId": "cometchat-uid-1_user_cometchat-uid-2", "sender": "cometchat-uid-1", "receiverType": "user", "receiver": "cometchat-uid-2", "category": "message", "type": "text", "data": { "text": "hello" }, "sentAt": 1696934912, "editedAt": 1696934985, "editedBy": "cometchat-uid-1" }, "entityType": "message" } } }, "sentAt": 1696934985, "updatedAt": 1696934985 } }, "appId": "", "region": "", "webhook": "" } ``` ##### message_deleted: ```json message_deleted theme={null} { "trigger": "message_deleted", "data": { "message": { "id": "3", "conversationId": "cometchat-uid-1_user_cometchat-uid-2", "sender": "cometchat-uid-1", "receiverType": "user", "receiver": "cometchat-uid-2", "category": "action", "type": "message", "data": { "action": "deleted", "entities": { "by": { "entity": { "uid": "cometchat-uid-1", "name": "Andrew Joseph" }, "entityType": "user" }, "on": { "entity": { "id": "2", "conversationId": "cometchat-uid-1_user_cometchat-uid-2", "deletedAt": 1696935005, "deletedBy": "cometchat-uid-1" }, "entityType": "message" } } }, "sentAt": 1696935005, "updatedAt": 1696935005 } }, "appId": "", "region": "", "webhook": "" } ``` ##### message_delivery_receipt: ```json message_delivery_receipt theme={null} { "trigger": "message_delivery_receipt", "data": { "receiver": "cometchat-uid-1", "receiverType": "user", "type": "receipts", "sender": "cometchat-uid-2", "messageSender": "cometchat-uid-1", "body": { "action": "delivered", "messageId": "57", "user": { "uid": "cometchat-uid-2", "name": "George Alan", "status": "online" }, "timestamp": 1696934912 } }, "appId": "", "region": "", "webhook": "" } ``` ##### message_read_receipt: ```json message_read_receipt theme={null} { "trigger": "message_read_receipt", "data": { "receiver": "cometchat-uid-1", "receiverType": "user", "type": "receipts", "sender": "cometchat-uid-2", "messageSender": "cometchat-uid-1", "body": { "action": "read", "messageId": "57", "user": { "uid": "cometchat-uid-2", "name": "George Alan", "status": "online" }, "timestamp": 1696934950 } }, "appId": "", "region": "", "webhook": "" } ``` ##### message_reaction_added: ```json message_reaction_added theme={null} { "trigger": "message_reaction_added", "data": { "reaction": { "id": "", "messageId": "", "reaction": "🏒", "uid": "cometchat-uid-1", "reactedAt": 1700655536, "reactedBy": { "uid": "cometchat-uid-1", "name": "Andrew Joseph" } } }, "appId": "", "region": "", "webhook": "" } ``` ##### message_reaction_removed: ```json message_reaction_removed theme={null} { "trigger": "message_reaction_removed", "data": { "reaction": { "id": "", "messageId": "", "reaction": "🏒", "uid": "cometchat-uid-1", "reactedAt": 1700231289, "reactedBy": { "uid": "cometchat-uid-1", "name": "Andrew Joseph" } } }, "appId": "", "region": "", "webhook": "" } ``` #### Users ##### user_connection_status_changed: ```json user_connection_status_changed theme={null} { "trigger": "user_connection_status_changed", "data": { "timestamp": 1696935103114, "user": { "uid": "cometchat-uid-1", "name": "Andrew Joseph", "status": "offline", "role": "default" }, "status": "offline", "currentConnection": { "action": "disconnected", "platform": "javascript", "connectedAt": 1696934440982 }, "userPresenceChanged": true }, "appId": "", "region": "", "webhook": "" } ``` ##### user_blocked: ```json user_blocked theme={null} { "trigger": "user_blocked", "data": { "users": { "cometchat-uid-2": { "uid": "cometchat-uid-2", "name": "George Alan" } }, "by": { "uid": "cometchat-uid-1", "name": "Andrew Joseph" } }, "appId": "", "region": "", "webhook": "" } ``` ##### user_unblocked: ```json user_unblocked theme={null} { "trigger": "user_unblocked", "data": { "users": { "cometchat-uid-2": { "uid": "cometchat-uid-2", "name": "George Alan" } }, "by": { "uid": "cometchat-uid-1", "name": "Andrew Joseph" } }, "appId": "", "region": "", "webhook": "" } ``` ##### user_mentioned: ```json user_mentioned theme={null} { "trigger": "user_mentioned", "data": { "message": { "id": "4", "conversationId": "cometchat-uid-1_user_cometchat-uid-2", "sender": "cometchat-uid-1", "receiverType": "user", "receiver": "cometchat-uid-2", "category": "message", "type": "text", "data": { "text": "Hi <@uid:cometchat-uid-2>", "mentions": { "cometchat-uid-2": { "uid": "cometchat-uid-2", "name": "Andrew Joseph" } } }, "sentAt": 1702028666, "updatedAt": 1702028666 } }, "appId": "", "region": "", "webhook": "" } ``` #### Calls & Meetings ##### call_initiated: ```json call_initiated theme={null} { "trigger": "call_initiated", "data": { "call": { "id": "52", "conversationId": "cometchat-uid-1_user_cometchat-uid-5", "sender": "cometchat-uid-1", "receiverType": "user", "receiver": "cometchat-uid-5", "category": "call", "type": "audio", "data": { "action": "initiated" }, "sentAt": 1696934199, "updatedAt": 1696934199 } }, "appId": "", "region": "", "webhook": "" } ``` ##### call_started: ```json call_started theme={null} { "trigger": "call_started", "data": { "created_at": 1696934572, "sessionId": "" }, "type": "call", "appId": "", "region": "", "webhook": "" } ``` ##### call_ended: ```json call_ended theme={null} { "trigger": "call_ended", "data": { "all_occupants": [ { "joined_at": 1696934501, "audio_call": "true", "left_at": 1696934553, "name": "George Alan" }, { "joined_at": 1696934501, "audio_call": "true", "left_at": 1696934551, "name": "Andrew Joseph" } ], "destroyed_at": 1696934553, "created_at": 1696934501, "sessionId": "" }, "type": "call", "appId": "", "region": "", "webhook": "" } ``` ##### call_participant_joined: ```json call_participant_joined theme={null} { "trigger": "call_participant_joined", "data": { "occupant": { "joined_at": 1696934573, "audio_call": "true", "name": "Andrew Joseph" }, "sessionId": "" }, "type": "call", "appId": "", "region": "", "webhook": "" } ``` ##### call_participant_left: ```json call_participant_left theme={null} { "trigger": "call_participant_left", "data": { "occupant": { "joined_at": 1696934501, "audio_call": "true", "left_at": 1696934553, "name": "George Alan" }, "sessionId": "" }, "type": "call", "appId": "", "region": "", "webhook": "" } ``` ##### meeting_started: ```json meeting_started theme={null} { "trigger": "meeting_started", "data": { "created_at": 1696934692, "sessionId": "" }, "type": "meet", "appId": "", "region": "", "webhook": "" } ``` ##### meeting_participant_joined: ```json meeting_participant_joined theme={null} { "trigger": "meeting_participant_joined", "data": { "occupant": { "joined_at": 1696934692, "audio_call": "false", "name": "Andrew Joseph" }, "sessionId": "" }, "type": "meet", "appId": "", "region": "", "webhook": "" } ``` ##### meeting_participant_left: ```json meeting_participant_left theme={null} { "trigger": "meeting_participant_left", "data": { "occupant": { "joined_at": 1696934692, "audio_call": "false", "left_at": 1696934730, "name": "Andrew Joseph" }, "sessionId": "" }, "type": "meet", "appId": "", "region": "", "webhook": "" } ``` ##### meeting_ended: ```json meeting_ended theme={null} { "trigger": "meeting_ended", "data": { "all_occupants": [ { "joined_at": 1696934692, "audio_call": "false", "left_at": 1696934730, "name": "Andrew Joseph" } ], "destroyed_at": 1696934730, "created_at": 1696934692, "sessionId": "" }, "type": "meet", "appId": "", "region": "", "webhook": "" } ``` ##### recording_generated: ```json recording_generated theme={null} { "trigger": "recording_generated", "data": { "recordingDate": "2023-10-10", "duration": "21.433000", "startTime": "1696937627", "sessionId": "", "recording_url": "" }, "appId": "", "region": "", "webhook": "" } ``` ##### transcription_generated: ```json transcription_generated theme={null} { "trigger": "transcription_generated", "data": { "sessionId": "", "tid": "", "transcriptDate": "2023-10-10", "transcript_url": "", "startTime": 1696937627, "endTime": 1696937648 }, "appId": "", "region": "", "webhook": "" } ``` #### Moderation ##### moderation_engine_approved: ```json moderation_engine_approved theme={null} { "trigger": "moderation_engine_approved", "data": { "message": { "id": "13", "conversationId": "cometchat-uid-1_user_cometchat-uid-2", "sender": "cometchat-uid-1", "receiverType": "user", "receiver": "cometchat-uid-2", "category": "message", "type": "text", "data": { "text": "hello there", "entities": { "sender": { "entity": { "uid": "cometchat-uid-1", "name": "Andrew Joseph", "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp", "status": "offline", "role": "default", "lastActiveAt": 1791272119, "createdAt": 1791272119 }, "entityType": "user" }, "receiver": { "entity": { "uid": "cometchat-uid-2", "name": "George Alan", "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp", "status": "offline", "role": "default", "lastActiveAt": 1791272119, "createdAt": 1791272119, "conversationId": "cometchat-uid-1_user_cometchat-uid-2" }, "entityType": "user" } }, "metadata": { "@injected": { "extensions": { "link-preview": { "links": [] } } } }, "moderation": { "status": "approved" } }, "sentAt": 1791285309, "updatedAt": 1791285309 } }, "appId": "", "region": "", "webhook": "" } ``` ##### moderation_engine_blocked: ```json moderation_engine_blocked theme={null} { "trigger": "moderation_engine_blocked", "data": { "message": { "id": "13", "conversationId": "cometchat-uid-1_user_cometchat-uid-2", "sender": "cometchat-uid-1", "receiverType": "user", "receiver": "cometchat-uid-2", "category": "message", "type": "text", "data": { "text": "message that tripped a rule", "entities": { "sender": { "entity": { "uid": "cometchat-uid-1", "name": "Andrew Joseph", "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-1.webp", "status": "offline", "role": "default", "lastActiveAt": 1791272119, "createdAt": 1791272119 }, "entityType": "user" }, "receiver": { "entity": { "uid": "cometchat-uid-2", "name": "George Alan", "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp", "status": "offline", "role": "default", "lastActiveAt": 1791272119, "createdAt": 1791272119, "conversationId": "cometchat-uid-1_user_cometchat-uid-2" }, "entityType": "user" } }, "metadata": { "@injected": { "extensions": { "link-preview": { "links": [] } } } }, "moderation": { "status": "disapproved" } }, "sentAt": 1791285309, "updatedAt": 1791285309 } }, "appId": "", "region": "", "webhook": "" } ``` ##### moderation_manual_approved: ```json moderation_manual_approved theme={null} { "trigger": "moderation_manual_approved", "data": { "message": { "id": "6", "muid": "_of6zl8yky", "conversationId": "group_cometchat-guid-1", "sender": "cometchat-uid-2", "receiverType": "group", "receiver": "cometchat-guid-1", "category": "message", "type": "text", "data": { "text": "Check out our amazing deal on these new items", "resource": "WEB-4_1_10-e16325bd-1ad5-4dcc-bae2-9d4cb63540ea-1791272204048", "entities": { "sender": { "entity": { "uid": "cometchat-uid-2", "name": "George Alan", "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp", "status": "offline", "role": "default", "lastActiveAt": 1791272119 }, "entityType": "user" }, "receiver": { "entity": { "guid": "cometchat-guid-1", "name": "Hiking Group", "description": "Explore, connect, and chat with fellow outdoor enthusiasts, thanks to our CometChat-enabled community platform.", "icon": "https://assets.cometchat.io/sampleapp/v2/groups/cometchat-guid-1.webp", "type": "private", "scope": "participant", "membersCount": 5, "joinedAt": 1791272119, "conversationId": "group_cometchat-guid-1", "hasJoined": true, "createdAt": 1791272119, "owner": "cometchat-uid-5", "onlineMembersCount": 2 }, "entityType": "group" } }, "metadata": { "@injected": { "extensions": { "link-preview": { "links": [] } } } }, "moderation": { "status": "approved" } }, "sentAt": 1791272621, "updatedAt": 1791272621 }, "moderation": [ { "condition": { "id": 1, "isKeywordsReferencePresent": true, "isMediaPresent": true, "entity": "message", "operand": "text", "category": "sentence-similarity", "operator": "contains", "value": [ "spam-detection_greaterThan_50" ], "message": "Text or Custom message contains keywords from the Spam Detection list", "_id": "6ac4a5978242b9e11a39cbe7", "similarityValue": 50, "disallowedSentences": [ "Get 50% off all products, limited time offer!", "Buy now and receive free shipping!", "Check out our amazing deal on these new items!" ], "basicAuthEnabled": false, "prompts": [], "weight": 0 }, "rule": { "id": "spam-detection", "name": "AI Spam detection", "revisionId": "_spam-detection_14", "action": [ "blockMessage" ], "blockedAt": 1791272621 } } ], "reviewed": true }, "appId": "", "region": "", "webhook": "" } ``` ##### moderation_engine_failed: ```json moderation_engine_failed theme={null} { "trigger": "moderation_engine_failed", "data": { "resource": { "id": "11", "conversationId": "cometchat-uid-1_user_cometchat-uid-2", "sender": "cometchat-uid-1", "receiverType": "user", "receiver": "cometchat-uid-2", "category": "message", "type": "text", "sentAt": 1791285188 }, "contentType": "text", "outcome": "approved", "completedAt": 1791285190, "failures": [ { "timeoutMs": 2000, "failedAt": 1791285190, "category": "http_5xx", "httpStatus": 500, "errorMessage": "Your moderation endpoint returned HTTP 500. CometChat treats any non-2xx response as a moderation failure. To return a decision, respond with HTTP 200 and a JSON body containing isMatchingCondition, confidence and reason.", "responseBody": "{\"statusCode\":500,\"message\":[\"simulated failure from the mock engine\"],\"error\":\"Internal Server Error\"}", "responseBodyTruncated": false, "context": { "engine": "custom_api", "setting": "approve-message", "rule": { "id": "custom-api-check", "name": "Custom API Check", "revisionId": "_custom-api-check_1" }, "condition": { "entity": "message", "operand": "text", "category": "custom-api", "operator": "contains", "message": "Text contains Custom API condition custom-api-check with confidence greater than 80", "listId": "custom-api-check", "threshold": { "comparison": "greaterThan", "percent": 80 } }, "request": { "url": "https://moderation.example.com/check", "method": "POST", "bodyBytes": 1034, "basicAuthSent": false } } } ] }, "appId": "", "region": "", "webhook": "" } ``` #### Campaigns ##### after_campaign_completed: ```json after_campaign_completed theme={null} { "trigger": "after_campaign_completed", "data": { "campaignId": "", "appId": "", "name": "Welcome Campaign", "status": "completed", "templateId": "", "templateVersion": 1, "totalTargets": 100, "sentCount": 100, "failedCount": 0, "tag": "onboarding", "scheduledAt": 1696930000, "sentAt": 1696932000, "completedAt": 1696932060, "createdAt": 1696929000, "updatedAt": 1696932060 }, "appId": "", "region": "", "webhook": "" } ``` ##### after_campaign_failed: ```json after_campaign_failed theme={null} { "trigger": "after_campaign_failed", "data": { "campaignId": "", "appId": "", "name": "Promo Campaign", "status": "failed", "templateId": "", "templateVersion": 1, "totalTargets": 50, "sentCount": 0, "failedCount": 50, "tag": "promo", "scheduledAt": 1696930000, "sentAt": 1696932000, "completedAt": 1696932070, "createdAt": 1696929000, "updatedAt": 1696932070 }, "appId": "", "region": "", "webhook": "" } ``` ##### after_notification_created: ```json after_notification_created theme={null} { "trigger": "after_notification_created", "data": { "notificationId": "", "appId": "", "templateId": "", "templateVersion": 1, "category": "updates", "label": "weekly-digest", "tags": ["digest", "weekly"], "sendMode": "realtime", "campaignId": "", "priority": "normal", "channels": ["in_app"], "dataType": "ui_template", "status": "dispatching", "totalTargets": 3, "sentCount": 0, "failedCount": 0, "createdAt": 1696932000 }, "appId": "", "region": "", "webhook": "" } ``` ##### after_feed_item_sent: ```json after_feed_item_sent theme={null} { "trigger": "after_feed_item_sent", "data": { "id": "", "appId": "", "notificationId": "", "campaignId": "", "receiver": "cometchat-uid-1", "templateId": "", "templateVersion": 1, "channelType": "in_app", "channelId": "", "templateCategory": "promotions", "categoryId": "", "label": "promo", "tags": ["offer", "summer"], "alternativeText": "You have a new offer!", "dataType": "ui_template", "status": "sent", "sentAt": 1696932000, "deliveredAt": null, "readAt": null, "engagedAt": null, "realtimeFanout": ["websocket"], "content": { "version": "1.0", "body": [ {"id": "el_1", "type": "text", "content": "Hello!", "variant": "heading2"}, {"id": "el_2", "type": "divider"}, {"id": "el_3", "type": "text", "content": "Your notification message here.", "variant": "body"} ], "style": { "background": {"light": "#E8E8E8", "dark": "#E8E8E8"}, "borderRadius": 16, "borderColor": {"light": "#DFE6E9", "dark": "#DFE6E9"}, "padding": 12 } } }, "appId": "", "region": "", "webhook": "" } ``` ##### after_feed_item_delivered: ```json after_feed_item_delivered theme={null} { "trigger": "after_feed_item_delivered", "data": { "id": "", "appId": "", "notificationId": "", "campaignId": "", "receiver": "cometchat-uid-1", "templateId": "", "templateVersion": 1, "channelType": "in_app", "channelId": "", "templateCategory": "promotions", "categoryId": "", "label": "promo", "tags": ["offer", "summer"], "alternativeText": "You have a new offer!", "dataType": "ui_template", "status": "delivered", "sentAt": 1696932000, "deliveredAt": 1696932060, "readAt": null, "engagedAt": 1696932055, "realtimeFanout": ["websocket"] }, "appId": "", "region": "", "webhook": "" } ``` ##### after_feed_item_read: ```json after_feed_item_read theme={null} { "trigger": "after_feed_item_read", "data": { "id": "", "appId": "", "notificationId": "", "campaignId": "", "receiver": "cometchat-uid-1", "templateId": "", "templateVersion": 1, "channelType": "in_app", "channelId": "", "templateCategory": "promotions", "categoryId": "", "label": "promo", "tags": ["offer", "summer"], "alternativeText": "You have a new offer!", "dataType": "ui_template", "variables": {}, "status": "read", "sentAt": 1696932000, "deliveredAt": 1696932060, "readAt": 1696932120, "engagedAt": null, "metadata": {}, "realtimeFanout": ["websocket"] }, "appId": "", "region": "", "webhook": "" } ``` ##### after_feed_item_interacted: ```json after_feed_item_interacted theme={null} { "trigger": "after_feed_item_interacted", "data": { "id": "", "appId": "", "notificationId": "", "campaignId": "", "receiver": "cometchat-uid-1", "templateId": "", "templateVersion": 1, "channelType": "in_app", "channelId": "", "templateCategory": "promotions", "categoryId": "", "label": "promo", "tags": ["offer", "summer"], "alternativeText": "You have a new offer!", "dataType": "ui_template", "variables": {}, "status": "read", "sentAt": 1696932000, "deliveredAt": 1696932060, "readAt": 1696932120, "interactedAt": 1696932180, "metadata": {}, "realtimeFanout": ["websocket"] }, "appId": "", "region": "", "webhook": "" } ``` ##### after_push_notification_sent: ```json after_push_notification_sent theme={null} { "trigger": "after_push_notification_sent", "data": { "pushNotificationId": "", "appId": "", "notificationId": "", "campaignId": "", "receiver": "cometchat-uid-1", "templateId": "", "templateVersion": 1, "channelType": "push", "channelId": "", "category": "promotions", "label": "summer-sale", "tags": ["offer", "summer"], "alternativeText": "Check out our summer sale!", "dataType": "ui_template", "variables": {}, "status": "sent", "sentAt": 1696932000, "deliveredAt": null, "clickedAt": null, "engagedAt": null, "failedAt": null, "errorMessage": null, "tag": "promo", "metadata": {} }, "appId": "", "region": "", "webhook": "" } ``` ##### after_push_notification_delivered: ```json after_push_notification_delivered theme={null} { "trigger": "after_push_notification_delivered", "data": { "pushNotificationId": "", "appId": "", "notificationId": "", "campaignId": "", "receiver": "cometchat-uid-1", "templateId": "", "templateVersion": 1, "channelType": "push", "channelId": "", "category": "promotions", "label": "summer-sale", "tags": ["offer", "summer"], "alternativeText": "Check out our summer sale!", "dataType": "ui_template", "variables": {}, "status": "delivered", "sentAt": 1696932000, "deliveredAt": 1696932005, "clickedAt": null, "engagedAt": null, "failedAt": null, "errorMessage": null, "tag": "promo" }, "appId": "", "region": "", "webhook": "" } ``` ##### after_push_notification_clicked: ```json after_push_notification_clicked theme={null} { "trigger": "after_push_notification_clicked", "data": { "pushNotificationId": "", "appId": "", "notificationId": "", "campaignId": "", "receiver": "cometchat-uid-1", "templateId": "", "templateVersion": 1, "channelType": "push", "channelId": "", "category": "promotions", "label": "summer-sale", "tags": ["offer", "summer"], "alternativeText": "Check out our summer sale!", "dataType": "ui_template", "variables": {}, "status": "clicked", "sentAt": 1696932000, "deliveredAt": 1696932005, "clickedAt": 1696932060, "engagedAt": null, "failedAt": null, "errorMessage": null, "tag": "promo", "metadata": {} }, "appId": "", "region": "", "webhook": "" } ``` # Remove Triggers Source: https://www.cometchat.com/docs/rest-api/management-apis/webhooks/remove-triggers delete /apps/{appId}/webhooks/{webhookId}/triggers Removes triggers from a webhook in an app. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Update Webhook Source: https://www.cometchat.com/docs/rest-api/management-apis/webhooks/update-webhook put /apps/{appId}/webhooks/{webhookId} Updates webhook details of an app. For the complete error reference, see [Error Guide](/docs/rest-api/management-apis/error-codes). # Overview Source: https://www.cometchat.com/docs/rest-api/settings Configure conversation behavior — control which message types appear as the last message and increment unread counts. The **Settings** API lets you customize how conversations behave in your CometChat app. You can control which message types appear as the last message in a conversation and which ones increment the unread message count. ### Endpoints | Method | Endpoint | Description | | - | - | - | | GET | [`/apps/{appId}/settings`](/docs/rest-api/management-apis/settings/list-settings) | List all settings for the app | | POST | [`/apps/{appId}/settings`](/docs/rest-api/management-apis/settings/maps-settings) | Map (update) settings for the app | | DELETE | [`/apps/{appId}/settings`](/docs/rest-api/management-apis/settings/unmaps-settings) | Unmap (reset) settings for the app | ### Available settings | Key | Description | Default | | - | - | - | | `core.conversations.updateOnGroupActions` | Whether group actions (member joined, left, banned) appear as the last message and increment unread count. | `true` | | `core.conversations.updateOnReplies` | Whether thread replies appear as the last message. Thread replies do **not** increment the unread count. | `true` | | `core.conversations.updateOnMessageActions` | Whether message actions (edited, deleted) appear as the last message and increment unread count. | `false` | | `core.conversations.updateOnCallActivity` | Whether call activities (initiated, accepted, rejected) appear as the last message and increment unread count. | `false` | | `core.threads.updateOnMessageActions` | Whether thread message actions (edited, deleted) appear as the last message and increment unread count. | `false` | | `core.notifications.push.enabled` | Whether Enhanced Push Notifications are enabled for the app. | `false` | ### How settings connect to other resources * **Conversations** — These settings directly control how [Conversations](/docs/rest-api/conversations) display the last message and calculate unread counts. * **Messages** — Settings determine which [Message](/docs/rest-api/messages) types affect conversation previews. * **Management APIs** — Use the [Map Settings API](/docs/rest-api/management-apis/settings/maps-settings) to toggle these features. ## Error Handling | Error Code | Description | | - | - | | `AUTH_ERR_EMPTY_APIKEY` | The `apikey` header is missing from the request | | `AUTH_ERR_APIKEY_NOT_FOUND` | The provided API key is invalid | | `AUTH_ERR_NO_ACCESS` | The API key doesn't have the required scope | For the complete error reference, see [Error Guide](/docs/articles/error-guide). # Actions Source: https://www.cometchat.com/docs/calls/android/actions Use CometChat Calls SDK v5 actions on Android to control calls, manage audio/video state, share screens, and handle in-call behavior. Use call actions to create your own custom controls or trigger call functionality dynamically based on your use case. All actions are called on the `CallSession` singleton instance during an active call session. ## Get CallSession Instance The `CallSession` is a singleton that manages the active call. All actions are accessed through this instance. > [tab] Kotlin > > ```kotlin theme={null} > val callSession = CallSession.getInstance() > ``` > [tab] Java > > ```java theme={null} > CallSession callSession = CallSession.getInstance(); > ``` > [!NOTE] > > Always check `isSessionActive()` before calling actions to ensure there's an active call. ## Actions ### Mute Audio Mutes your local microphone, stopping audio transmission to other participants. > [tab] Kotlin > > ```kotlin theme={null} > callSession.muteAudio() > ``` > [tab] Java > > ```java theme={null} > callSession.muteAudio(); > ``` ### Unmute Audio Unmutes your local microphone, resuming audio transmission. > [tab] Kotlin > > ```kotlin theme={null} > callSession.unmuteAudio() > ``` > [tab] Java > > ```java theme={null} > callSession.unmuteAudio(); > ``` ### Set Audio Mode Changes the audio output device during a call. > [tab] Kotlin > > ```kotlin theme={null} > callSession.setAudioMode(AudioMode.SPEAKER) > callSession.setAudioMode(AudioMode.EARPIECE) > callSession.setAudioMode(AudioMode.BLUETOOTH) > callSession.setAudioMode(AudioMode.HEADPHONES) > ``` > [tab] Java > > ```java theme={null} > callSession.setAudioMode(AudioMode.SPEAKER); > callSession.setAudioMode(AudioMode.EARPIECE); > callSession.setAudioMode(AudioMode.BLUETOOTH); > callSession.setAudioMode(AudioMode.HEADPHONES); > ``` > [accordion] AudioMode Values > > | Value | Description | > | - | - | > | `SPEAKER` | Routes audio through device loudspeaker | > | `EARPIECE` | Routes audio through phone earpiece | > | `BLUETOOTH` | Routes audio through connected Bluetooth device | > | `HEADPHONES` | Routes audio through wired headphones | ### Pause Video Turns off your local camera, stopping video transmission. Other participants see your avatar. > [tab] Kotlin > > ```kotlin theme={null} > callSession.pauseVideo() > ``` > [tab] Java > > ```java theme={null} > callSession.pauseVideo(); > ``` ### Resume Video Turns on your local camera, resuming video transmission. > [tab] Kotlin > > ```kotlin theme={null} > callSession.resumeVideo() > ``` > [tab] Java > > ```java theme={null} > callSession.resumeVideo(); > ``` ### Switch Camera Toggles between front and back cameras without interrupting the video stream. > [tab] Kotlin > > ```kotlin theme={null} > callSession.switchCamera() > ``` > [tab] Java > > ```java theme={null} > callSession.switchCamera(); > ``` ### Start Recording Begins server-side recording of the call. All participants are notified. > [tab] Kotlin > > ```kotlin theme={null} > callSession.startRecording() > ``` > [tab] Java > > ```java theme={null} > callSession.startRecording(); > ``` > [!WARNING] > > Recording requires the feature to be enabled for your CometChat app. ### Stop Recording Stops the current recording. The recording is saved and accessible via the dashboard. > [tab] Kotlin > > ```kotlin theme={null} > callSession.stopRecording() > ``` > [tab] Java > > ```java theme={null} > callSession.stopRecording(); > ``` ### Start Transcription *Available since v5.0.4* Begins server-side transcription of the call. This also enables the live closed captions overlay. > [tab] Kotlin > > ```kotlin theme={null} > callSession.startTranscription() > ``` > [tab] Java > > ```java theme={null} > callSession.startTranscription(); > ``` > [!WARNING] > > Transcription requires the feature to be enabled for your CometChat app. ### Stop Transcription *Available since v5.0.4* Stops the current transcription and clears any captions currently on screen. The transcript is saved and can be retrieved with [`TranscriptRequest`](/docs/calls/android/transcription#retrieving-transcripts). > [tab] Kotlin > > ```kotlin theme={null} > callSession.stopTranscription() > ``` > [tab] Java > > ```java theme={null} > callSession.stopTranscription(); > ``` ### Mute Participant Mutes a specific participant's audio. This is a moderator action. > [tab] Kotlin > > ```kotlin theme={null} > callSession.muteParticipant(participant.uid) > ``` > [tab] Java > > ```java theme={null} > callSession.muteParticipant(participant.getUid()); > ``` ### Pause Participant Video Pauses a specific participant's video. This is a moderator action. > [tab] Kotlin > > ```kotlin theme={null} > callSession.pauseParticipantVideo(participant.uid) > ``` > [tab] Java > > ```java theme={null} > callSession.pauseParticipantVideo(participant.getUid()); > ``` ### Pin Participant Pins a participant to keep them prominently displayed regardless of who is speaking. > [tab] Kotlin > > ```kotlin theme={null} > callSession.pinParticipant(participant.uid, participant.pid) > ``` > [tab] Java > > ```java theme={null} > callSession.pinParticipant(participant.getUid(), participant.getPid()); > ``` ### Unpin Participant Removes the pin, returning to automatic speaker highlighting. > [tab] Kotlin > > ```kotlin theme={null} > callSession.unpinParticipant() > ``` > [tab] Java > > ```java theme={null} > callSession.unpinParticipant(); > ``` ### Set Layout Changes the call layout. Each participant can choose their own layout independently. > [tab] Kotlin > > ```kotlin theme={null} > callSession.setLayout(LayoutType.TILE) > callSession.setLayout(LayoutType.SPOTLIGHT) > callSession.setLayout(LayoutType.SIDEBAR) > ``` > [tab] Java > > ```java theme={null} > callSession.setLayout(LayoutType.TILE); > callSession.setLayout(LayoutType.SPOTLIGHT); > callSession.setLayout(LayoutType.SIDEBAR); > ``` > [accordion] LayoutType Values > > | Value | Description | > | - | - | > | `TILE` | Grid layout with equally-sized tiles | > | `SPOTLIGHT` | Large view for active speaker, small tiles for others | > | `SIDEBAR` | Main speaker with participants in a sidebar | ### Enable Picture In Picture Layout Enables PiP mode, allowing the call to continue in a floating window. > [tab] Kotlin > > ```kotlin theme={null} > callSession.enablePictureInPictureLayout() > ``` > [tab] Java > > ```java theme={null} > callSession.enablePictureInPictureLayout(); > ``` ### Disable Picture In Picture Layout Disables PiP mode, returning to full-screen call interface. > [tab] Kotlin > > ```kotlin theme={null} > callSession.disablePictureInPictureLayout() > ``` > [tab] Java > > ```java theme={null} > callSession.disablePictureInPictureLayout(); > ``` ### Set Chat Button Unread Count Updates the badge count on the chat button. Pass 0 to hide the badge. > [tab] Kotlin > > ```kotlin theme={null} > callSession.setChatButtonUnreadCount(5) > ``` > [tab] Java > > ```java theme={null} > callSession.setChatButtonUnreadCount(5); > ``` ### Is Session Active Returns `true` if a call session is active, `false` otherwise. > [tab] Kotlin > > ```kotlin theme={null} > val isActive = callSession.isSessionActive() > ``` > [tab] Java > > ```java theme={null} > boolean isActive = callSession.isSessionActive(); > ``` ### Leave Session Ends your participation and disconnects gracefully. In a 1:1 call this is the hang-up: the other side receives `onParticipantLeft` and the backend records the end. In a group call the session continues for the other participants. > [tab] Kotlin > > ```kotlin theme={null} > callSession.leave() > ``` > [tab] Java > > ```java theme={null} > callSession.leave(); > ``` > [!NOTE] > > `leaveSession()` is deprecated since 5.1 and only calls `leave()`. To end a call that is still ringing use `CometChatCalls.endCall(sessionId, status, listener)` with `cancelled` (caller) as described in [Ringing](/docs/calls/android/ringing); `leave()` alone does not tell the other side why. ### Raise Hand Shows a hand-raised indicator to get attention from other participants. > [tab] Kotlin > > ```kotlin theme={null} > callSession.raiseHand() > ``` > [tab] Java > > ```java theme={null} > callSession.raiseHand(); > ``` ### Lower Hand Removes the hand-raised indicator. > [tab] Kotlin > > ```kotlin theme={null} > callSession.lowerHand() > ``` > [tab] Java > > ```java theme={null} > callSession.lowerHand(); > ``` > [accordion] Participant Object Reference > > | Property | Type | Description | > | - | - | - | > | `uid` | `String` | Unique identifier (CometChat user ID) | > | `name` | `String` | Display name | > | `avatar` | `String` | URL of avatar image | > | `pid` | `String` | Participant ID for this call session | > | `role` | `String` | Role in the call | > | `audioMuted` | `Boolean` | Whether audio is muted | > | `videoPaused` | `Boolean` | Whether video is paused | > | `isPinned` | `Boolean` | Whether pinned in layout | > | `isPresenting` | `Boolean` | Whether screen sharing | > | `raisedHandTimestamp` | `Long` | Timestamp when hand was raised | # Authentication Source: https://www.cometchat.com/docs/calls/android/authentication Configure authentication for CometChat Calls SDK v5 on Android with app credentials, logged-in users, and secure call access. Before users can make or receive calls, they must be authenticated with the CometChat Calls SDK. This guide covers the login and logout methods. > [!NOTE] > > **Sample Users** > > CometChat provides 5 test users: `cometchat-uid-1`, `cometchat-uid-2`, `cometchat-uid-3`, `cometchat-uid-4`, and `cometchat-uid-5`. ## Check Login Status Use `getLoggedInUser()` to find out whether — and **which** — user has a persisted session, for example at app launch to decide whether to show your login screen. It returns a `CallUser` object if a user is logged in, or `null` if no session exists. You never need it as a guard before `login()`: calling `login()` is always safe — if the same user is already logged in it returns the existing session without a network round trip, and if a different user is logged in the SDK switches to the new user automatically (see [Switching Users](#switching-users)). > [!WARNING] > > **Check *who* is logged in, not just _whether_** > > On a shared or reused device, the persisted session may belong to a *different* user. If your app skips its own login flow because `getLoggedInUser()` is non-null, compare the returned UID against your app's current account first — otherwise calls are silently placed as the previous user. > [tab] Kotlin > > ```kotlin theme={null} > val myAppsCurrentUserUid = "cometchat-uid-1" // your app's signed-in user ID > val loggedInUser = CometChatCalls.getLoggedInUser() > > if (loggedInUser != null && loggedInUser.uid.equals(myAppsCurrentUserUid, ignoreCase = true)) { > // The right user's session is already active — skip your login flow > Log.d(TAG, "Session restored for: ${loggedInUser.uid}") > } else { > // No session, or the session belongs to someone else — run login() > } > ``` > [tab] Java > > ```java theme={null} > String myAppsCurrentUserUid = "cometchat-uid-1"; // your app's signed-in user ID > CallUser loggedInUser = CometChatCalls.getLoggedInUser(); > > if (loggedInUser != null && loggedInUser.getUid().equalsIgnoreCase(myAppsCurrentUserUid)) { > // The right user's session is already active — skip your login flow > Log.d(TAG, "Session restored for: " + loggedInUser.getUid()); > } else { > // No session, or the session belongs to someone else — run login() > } > ``` ## Login with UID and API Key This method is suitable for development and testing. For production apps, use [Auth Token login](#login-with-auth-token) instead. > [!WARNING] > > **Security Notice** > > Using the API Key directly in client code is not recommended for production. Use Auth Token authentication for enhanced security. > [tab] Kotlin > > ```kotlin theme={null} > val uid = "cometchat-uid-1" // Replace with your user's UID > val apiKey = "API_KEY" // Replace with your API Key > > CometChatCalls.login(uid, apiKey, object : CometChatCalls.CallbackListener() { > override fun onSuccess(user: CallUser) { > Log.d(TAG, "Login successful: ${user.uid}") > } > > override fun onError(e: CometChatException) { > Log.e(TAG, "Login failed: ${e.message}") > } > }) > ``` > [tab] Java > > ```java theme={null} > String uid = "cometchat-uid-1"; // Replace with your user's UID > String apiKey = "API_KEY"; // Replace with your API Key > > CometChatCalls.login(uid, apiKey, new CometChatCalls.CallbackListener() { > @Override > public void onSuccess(CallUser user) { > Log.d(TAG, "Login successful: " + user.getUid()); > } > > @Override > public void onError(CometChatException e) { > Log.e(TAG, "Login failed: " + e.getMessage()); > } > }); > ``` | Parameter | Type | Description | | - | - | - | | `uid` | String | The unique identifier of the user to login | | `apiKey` | String | Your CometChat API Key | | `listener` | CallbackListener | Callback for success/error handling | ## Login with Auth Token This is the recommended authentication method for production applications. The Auth Token is generated server-side, keeping your API Key secure. ### Auth Token Flow 1. User authenticates with your backend 2. Your backend calls the [CometChat Create Auth Token API](https://api-explorer.cometchat.com/reference/create-authtoken) 3. Your backend returns the Auth Token to the client 4. Client uses the Auth Token to login > [tab] Kotlin > > ```kotlin theme={null} > val authToken = "AUTH_TOKEN" // Token received from your backend > > CometChatCalls.login(authToken, object : CometChatCalls.CallbackListener() { > override fun onSuccess(user: CallUser) { > Log.d(TAG, "Login successful: ${user.uid}") > } > > override fun onError(e: CometChatException) { > Log.e(TAG, "Login failed: ${e.message}") > } > }) > ``` > [tab] Java > > ```java theme={null} > String authToken = "AUTH_TOKEN"; // Token received from your backend > > CometChatCalls.login(authToken, new CometChatCalls.CallbackListener() { > @Override > public void onSuccess(CallUser user) { > Log.d(TAG, "Login successful: " + user.getUid()); > } > > @Override > public void onError(CometChatException e) { > Log.e(TAG, "Login failed: " + e.getMessage()); > } > }); > ``` | Parameter | Type | Description | | - | - | - | | `authToken` | String | Auth Token generated via CometChat API | | `listener` | CallbackListener | Callback for success/error handling | ## Switching Users On a shared or reused device, call `login()` with the new user's credentials — there is no need to check or clear the previous session yourself. If a different user is logged in, the SDK logs them out automatically before logging the new user in. Calling `login()` for the user who is already logged in simply returns the existing session. > [tab] Kotlin > > ```kotlin theme={null} > // Logs out the previous user (if any) and logs the new user in > CometChatCalls.login(newUserUid, apiKey, object : CometChatCalls.CallbackListener() { > override fun onSuccess(user: CallUser) { > Log.d(TAG, "Switched to user: ${user.uid}") > } > > override fun onError(e: CometChatException) { > Log.e(TAG, "User switch failed: ${e.message}") > } > }) > ``` > [tab] Java > > ```java theme={null} > // Logs out the previous user (if any) and logs the new user in > CometChatCalls.login(newUserUid, apiKey, new CometChatCalls.CallbackListener() { > @Override > public void onSuccess(CallUser user) { > Log.d(TAG, "Switched to user: " + user.getUid()); > } > > @Override > public void onError(CometChatException e) { > Log.e(TAG, "User switch failed: " + e.getMessage()); > } > }); > ``` ## CallUser Object On successful login, the callback returns a `CallUser` object containing user information: | Property | Type | Description | | - | - | - | | `uid` | String | Unique identifier of the user | | `name` | String | Display name of the user | | `avatar` | String | URL of the user's avatar image | | `status` | String | User's online status | ## Logout Call `logout()` when the user signs out of your application. This clears the local session and disconnects from CometChat services; the SDK stays initialized, so the next user can `login()` directly. > [tab] Kotlin > > ```kotlin theme={null} > CometChatCalls.logout(object : CometChatCalls.CallbackListener() { > override fun onSuccess(message: String) { > Log.d(TAG, "Logout successful") > } > > override fun onError(e: CometChatException) { > Log.e(TAG, "Logout failed: ${e.message}") > } > }) > ``` > [tab] Java > > ```java theme={null} > CometChatCalls.logout(new CometChatCalls.CallbackListener() { > @Override > public void onSuccess(String message) { > Log.d(TAG, "Logout successful"); > } > > @Override > public void onError(CometChatException e) { > Log.e(TAG, "Logout failed: " + e.getMessage()); > } > }); > ``` ## Error Handling Common authentication errors: | Error Code | Description | | - | - | | `ERROR_INVALID_UID` | The provided UID is empty or invalid | | `ERROR_UID_WITH_SPACE` | The UID contains spaces (not allowed) | | `ERROR_API_KEY_NOT_FOUND` | The API Key is missing or invalid | | `ERROR_BLANK_AUTHTOKEN` | The Auth Token is empty | | `ERROR_LOGIN_IN_PROGRESS` | A login operation is already in progress | # Events Source: https://www.cometchat.com/docs/calls/android/events Handle CometChat Calls SDK v5 events on Android for call lifecycle, participants, media state, errors, and real-time updates. Handle call session events to build responsive UIs. The SDK provides five session listener interfaces to monitor session status, participant activities, media changes, button clicks, and layout changes, plus two global listeners for incoming calls and login state. The five session listeners are lifecycle-aware and automatically cleaned up when the Activity or Fragment is destroyed; the two global listeners are not, so remove those yourself. ## Get CallSession Instance The `CallSession` is a singleton that manages the active call. All event listener registrations and session control methods are accessed through this instance. > [tab] Kotlin > > ```kotlin theme={null} > val callSession = CometChatCalls.getActiveSession() // null when no session is prepared or joined > ``` > [tab] Java > > ```java theme={null} > CallSession callSession = CometChatCalls.getActiveSession(); // null when no session is prepared or joined > ``` `getActiveSession()` returns the session as soon as it is **prepared**, which is what `CometChatCalls.initiateCall` does on the caller and what the Push SDK's ring does on the callee, before anyone joins. That is what lets a caller listen for "ringing" and "answered" without joining (see [Ringing](/docs/calls/android/ringing)). Before a session is prepared or joined, `getActiveSession()` returns null, so a listener added through it is skipped; the Kotlin samples below use `callSession?.` for that reason, and in Java check `callSession != null` before adding one. Add listeners once `joinSession` (or a prepare) has succeeded, or register them earlier through `CallSession.getInstance()`, which returns the same object. > [!NOTE] > > All session event listeners are lifecycle-aware and automatically removed when the `LifecycleOwner` (Activity/Fragment) is destroyed. You don't need to manually remove listeners. *** ## Session Events Monitor the call session lifecycle including join/leave events and connection status. > [tab] Kotlin > > ```kotlin theme={null} > callSession?.addSessionStatusListener(this, object : SessionStatusListener() { > override fun onSessionJoined() { > // Successfully connected to the session > } > > override fun onSessionLeft() { > finish() // Navigate away > } > > override fun onSessionTimedOut() { > // Session ended due to inactivity > finish() > } > > override fun onConnectionLost() { > // Network interrupted, attempting reconnection > } > > override fun onConnectionRestored() { > // Connection restored after being lost > } > > override fun onConnectionClosed() { > // Connection permanently closed. On a session that was only prepared > // (an outgoing call still ringing), this means the call ended before anyone joined. > finish() > } > }) > ``` > [tab] Java > > ```java theme={null} > callSession.addSessionStatusListener(this, new SessionStatusListener() { > @Override > public void onSessionJoined() { > // Successfully connected to the session > } > > @Override > public void onSessionLeft() { > finish(); // Navigate away > } > > @Override > public void onSessionTimedOut() { > // Session ended due to inactivity > finish(); > } > > @Override > public void onConnectionLost() { > // Network interrupted, attempting reconnection > } > > @Override > public void onConnectionRestored() { > // Connection restored after being lost > } > > @Override > public void onConnectionClosed() { > // Connection permanently closed > finish(); > } > }); > ``` | Event | Description | | - | - | | `onConnected()` | A prepared session (from `CometChatCalls.initiateCall` or `connect`) is connected and ready to join; not called for a session joined directly | | `onSessionJoined()` | Successfully connected and joined the session | | `onSessionLeft()` | Left the session via `leave()` or was removed | | `onSessionTimedOut()` | Session ended due to inactivity timeout. Not used on a prepared session: one nobody joins within 5 minutes reports `onConnectionClosed` | | `onConnectionLost()` | Network interrupted, SDK attempting reconnection | | `onConnectionRestored()` | Connection restored after being lost | | `onConnectionClosed()` | Connection permanently closed, cannot reconnect. On a prepared session: the call ended before anyone joined (declined, cancelled from another device, the room went away, or nobody joined within 5 minutes); the reason arrives through `onIncomingCallEnded` | *** ## Participant Events Monitor participant activities including join/leave, audio/video state, hand raise, screen sharing, and recording. > [tab] Kotlin > > ```kotlin theme={null} > callSession?.addParticipantEventListener(this, object : ParticipantEventListener() { > override fun onParticipantConnected(participant: Participant) { > // A participant's device prepared the session but has not joined yet. > // On an outgoing call: the callee's phone is ringing. > } > > override fun onParticipantJoined(participant: Participant) { > // A participant joined the call. On an outgoing call: the callee answered. > } > > override fun onParticipantLeft(participant: Participant) { > // A participant left the call > } > > override fun onParticipantListChanged(participants: List) { > // Participant list updated > } > > override fun onParticipantAudioMuted(participant: Participant) {} > override fun onParticipantAudioUnmuted(participant: Participant) {} > override fun onParticipantVideoPaused(participant: Participant) {} > override fun onParticipantVideoResumed(participant: Participant) {} > override fun onParticipantHandRaised(participant: Participant) {} > override fun onParticipantHandLowered(participant: Participant) {} > override fun onParticipantStartedScreenShare(participant: Participant) {} > override fun onParticipantStoppedScreenShare(participant: Participant) {} > override fun onParticipantStartedRecording(participant: Participant) {} > override fun onParticipantStoppedRecording(participant: Participant) {} > override fun onDominantSpeakerChanged(participant: Participant) {} > }) > ``` > [tab] Java > > ```java theme={null} > callSession.addParticipantEventListener(this, new ParticipantEventListener() { > @Override > public void onParticipantConnected(Participant participant) { > // A participant's device prepared the session but has not joined yet. > // On an outgoing call: the callee's phone is ringing. > } > > @Override > public void onParticipantJoined(Participant participant) { > // A participant joined the call. On an outgoing call: the callee answered. > } > > @Override > public void onParticipantLeft(Participant participant) { > // A participant left the call > } > > @Override > public void onParticipantListChanged(List participants) { > // Participant list updated > } > > // Other callbacks... > }); > ``` | Event | Parameter | Description | | - | - | - | | `onParticipantConnected` | `Participant` | A participant's device prepared the session without joining. On the caller's prepared session this is the callee ringing | | `onParticipantJoined` | `Participant` | A participant joined the call. On the caller's prepared session this is the callee answering: join now | | `onParticipantLeft` | `Participant` | A participant disconnected from the call | | `onParticipantListChanged` | `List` | Participant list updated | | `onParticipantAudioMuted` | `Participant` | A participant muted their microphone | | `onParticipantAudioUnmuted` | `Participant` | A participant unmuted their microphone | | `onParticipantVideoPaused` | `Participant` | A participant turned off their camera | | `onParticipantVideoResumed` | `Participant` | A participant turned on their camera | | `onParticipantHandRaised` | `Participant` | A participant raised their hand | | `onParticipantHandLowered` | `Participant` | A participant lowered their hand | | `onParticipantStartedScreenShare` | `Participant` | A participant started screen sharing | | `onParticipantStoppedScreenShare` | `Participant` | A participant stopped screen sharing | | `onParticipantStartedRecording` | `Participant` | A participant started recording | | `onParticipantStoppedRecording` | `Participant` | A participant stopped recording | | `onDominantSpeakerChanged` | `Participant` | The active speaker changed | *** ## Media Events Monitor your local media state changes including audio/video status, recording, and device changes. > [tab] Kotlin > > ```kotlin theme={null} > callSession?.addMediaEventsListener(this, object : MediaEventsListener() { > override fun onAudioMuted() { > // Your microphone was muted > } > > override fun onAudioUnMuted() { > // Your microphone was unmuted > } > > override fun onVideoPaused() { > // Your camera was turned off > } > > override fun onVideoResumed() { > // Your camera was turned on > } > > override fun onRecordingStarted() { > // Call recording started > } > > override fun onRecordingStopped() { > // Call recording stopped > } > > > override fun onAudioModeChanged(audioMode: AudioMode) { > // Audio output device changed > } > > override fun onCameraFacingChanged(facing: CameraFacing) { > // Camera switched between front and back > } > }) > ``` > [tab] Java > > ```java theme={null} > callSession.addMediaEventsListener(this, new MediaEventsListener() { > @Override > public void onAudioMuted() { > // Your microphone was muted > } > > @Override > public void onAudioUnMuted() { > // Your microphone was unmuted > } > > @Override > public void onVideoPaused() { > // Your camera was turned off > } > > @Override > public void onVideoResumed() { > // Your camera was turned on > } > > @Override > public void onRecordingStarted() { > // Call recording started > } > > @Override > public void onRecordingStopped() { > // Call recording stopped > } > > @Override > public void onAudioModeChanged(AudioMode audioMode) { > // Audio output device changed > } > > @Override > public void onCameraFacingChanged(CameraFacing facing) { > // Camera switched between front and back > } > > // Other callbacks... > }); > ``` | Event | Parameter | Description | | - | - | - | | `onAudioMuted` | - | Your microphone was muted | | `onAudioUnMuted` | - | Your microphone was unmuted | | `onVideoPaused` | - | Your camera was turned off | | `onVideoResumed` | - | Your camera was turned on | | `onRecordingStarted` | - | Call recording started | | `onRecordingStopped` | - | Call recording stopped | | `onStreamingStarted` | - | Live streaming started | | `onStreamingStopped` | - | Live streaming stopped | | `onAudioModeChanged` | `AudioMode` | Audio output device changed | | `onAudioModesChanged` | `List` | The set of available audio devices changed | | `onCameraFacingChanged` | `CameraFacing` | Camera switched between front and back | > [!NOTE] > > Screen sharing events are **not** on `MediaEventsListener`. A participant's screen share is reported by > `ParticipantEventListener.onParticipantStartedScreenShare` / `onParticipantStoppedScreenShare` — see > [Screen Sharing](/docs/calls/android/screen-sharing). Starting a screen share from Android is opt-in: the screen share button appears only after your app declares the `mediaProjection` service (see [Enable Screen Sharing](/docs/calls/android/screen-sharing#enable-screen-sharing-opt-in)). > [accordion] AudioMode Values > > | Value | Description | > | - | - | > | `AudioMode.SPEAKER` | Audio routed through device loudspeaker | > | `AudioMode.EARPIECE` | Audio routed through phone earpiece | > | `AudioMode.BLUETOOTH` | Audio routed through connected Bluetooth device | > | `AudioMode.HEADPHONES` | Audio routed through wired headphones | > [accordion] CameraFacing Values > > | Value | Description | > | - | - | > | `CameraFacing.FRONT` | Front-facing (selfie) camera is active | > | `CameraFacing.BACK` | Rear-facing (main) camera is active | *** ## Button Click Events Intercept UI button clicks from the default call interface to add custom behavior or analytics. > [tab] Kotlin > > ```kotlin theme={null} > callSession?.addButtonClickListener(this, object : ButtonClickListener() { > override fun onLeaveSessionButtonClicked() { > // Leave button tapped > } > > override fun onToggleAudioButtonClicked() { > // Mute/unmute button tapped > } > > override fun onToggleVideoButtonClicked() { > // Video on/off button tapped > } > > override fun onSwitchCameraButtonClicked() {} > override fun onRaiseHandButtonClicked() {} > override fun onShareInviteButtonClicked() {} > override fun onChangeLayoutButtonClicked() {} > override fun onParticipantListButtonClicked() {} > override fun onChatButtonClicked() {} > override fun onRecordingToggleButtonClicked() {} > }) > ``` > [tab] Java > > ```java theme={null} > callSession.addButtonClickListener(this, new ButtonClickListener() { > @Override > public void onLeaveSessionButtonClicked() { > // Leave button tapped > } > > @Override > public void onToggleAudioButtonClicked() { > // Mute/unmute button tapped > } > > @Override > public void onToggleVideoButtonClicked() { > // Video on/off button tapped > } > > // Other callbacks... > }); > ``` | Event | Description | | - | - | | `onLeaveSessionButtonClicked` | Leave/end call button was tapped | | `onToggleAudioButtonClicked` | Mute/unmute button was tapped | | `onToggleVideoButtonClicked` | Video on/off button was tapped | | `onSwitchCameraButtonClicked` | Camera switch button was tapped | | `onRaiseHandButtonClicked` | Raise hand button was tapped | | `onShareInviteButtonClicked` | Share/invite button was tapped | | `onChangeLayoutButtonClicked` | Layout change button was tapped | | `onParticipantListButtonClicked` | Participant list button was tapped | | `onChatButtonClicked` | In-call chat button was tapped | | `onRecordingToggleButtonClicked` | Recording toggle button was tapped | > [!NOTE] > > Button click events fire before the SDK's default action executes. Use these to add custom logic alongside default behavior. *** ## Layout Events Monitor layout changes including layout type switches and Picture-in-Picture mode transitions. > [tab] Kotlin > > ```kotlin theme={null} > callSession?.addLayoutListener(this, object : LayoutListener() { > override fun onCallLayoutChanged(layoutType: LayoutType) { > // Layout changed (TILE, SPOTLIGHT) > } > > override fun onParticipantListVisible() { > // Participant list panel opened > } > > override fun onParticipantListHidden() { > // Participant list panel closed > } > > override fun onPictureInPictureLayoutEnabled() { > // Entered PiP mode > } > > override fun onPictureInPictureLayoutDisabled() { > // Exited PiP mode > } > }) > ``` > [tab] Java > > ```java theme={null} > callSession.addLayoutListener(this, new LayoutListener() { > @Override > public void onCallLayoutChanged(LayoutType layoutType) { > // Layout changed (TILE, SPOTLIGHT) > } > > @Override > public void onParticipantListVisible() { > // Participant list panel opened > } > > @Override > public void onParticipantListHidden() { > // Participant list panel closed > } > > @Override > public void onPictureInPictureLayoutEnabled() { > // Entered PiP mode > } > > @Override > public void onPictureInPictureLayoutDisabled() { > // Exited PiP mode > } > }); > ``` | Event | Parameter | Description | | - | - | - | | `onCallLayoutChanged` | `LayoutType` | Call layout changed | | `onParticipantListVisible` | - | Participant list panel was opened | | `onParticipantListHidden` | - | Participant list panel was closed | | `onPictureInPictureLayoutEnabled` | - | Call entered Picture-in-Picture mode | | `onPictureInPictureLayoutDisabled` | - | Call exited Picture-in-Picture mode | > [accordion] LayoutType Values > > | Value | Description | Best For | > | - | - | - | > | `LayoutType.TILE` | Grid layout with equally-sized tiles | Group discussions, team meetings | > | `LayoutType.SPOTLIGHT` | Large view for active speaker, small tiles for others | Presentations, one-on-one calls | *** ## Incoming Call Events `CometChatCalls.addIncomingCallListener` is a global listener, not tied to a session. It reports a call for the logged-in user starting and ending, on both sides of the call, whether the call arrived by push while the app was killed or while it was running. It is how a caller learns why an outgoing call ended, and how your own screens stay in sync with calls the Push SDK rings. > [tab] Kotlin > > ```kotlin theme={null} > CometChatCalls.addIncomingCallListener("my-screen", object : CometChatCalls.IncomingCallListener() { > override fun onIncomingCallReceived(call: InitiatedCall) { > // A call for this user is ringing (the Push SDK already shows it) > } > > override fun onIncomingCallEnded(call: InitiatedCall, reason: String) { > // The ring ended, or your outgoing call ended: "rejected", "busy", "unanswered", "cancelled", "ongoing" > } > }) > > CometChatCalls.removeIncomingCallListener("my-screen") > ``` > [tab] Java > > ```java theme={null} > CometChatCalls.addIncomingCallListener("my-screen", new CometChatCalls.IncomingCallListener() { > @Override > public void onIncomingCallReceived(InitiatedCall call) { > // A call for this user is ringing (the Push SDK already shows it) > } > > @Override > public void onIncomingCallEnded(InitiatedCall call, String reason) { > // The ring ended, or your outgoing call ended: "rejected", "busy", "unanswered", "cancelled", "ongoing" > } > }); > > CometChatCalls.removeIncomingCallListener("my-screen"); > ``` | Event | Parameters | Description | | - | - | - | | `onIncomingCallReceived` | `InitiatedCall` | A call for the logged-in user is ringing | | `onIncomingCallEnded` | `InitiatedCall`, `reason` | The call ended before being answered here. Caller: `rejected`, `busy`, `unanswered`, `cancelled`, when a push delivers them through the Push SDK. Callee still ringing: `cancelled`, `ongoing` (answered elsewhere), `rejected` / `busy` (declined on another device), `unanswered`, `ended` (the prepared session closed before the answer). Treat any other reason as "the ring is over" | `InitiatedCall` carries `sessionId`, `messageId`, `conversationId`, `sender`, `senderName`, `senderAvatar`, `receiver`, `receiverType`, `type`, `status` and `initiatedAt`. > [!NOTE] > > Listener ids are keys: registering the same id twice replaces the earlier listener. This listener is not lifecycle-aware; remove it when the screen is destroyed. *** ## Login Events `CometChatCalls.addLoginListener` reports the Calls SDK login state. The Push SDK uses it to register and unregister the push token and to stop a ring when the user logs out; your app can use it to gate call UI. > [tab] Kotlin > > ```kotlin theme={null} > CometChatCalls.addLoginListener("my-app", object : CometChatCalls.LoginListener() { > override fun loginSuccess(user: CallUser) {} > override fun loginFailure(e: CometChatException) {} > override fun logoutSuccess() {} > override fun logoutFailure(e: CometChatException) {} > }) > > CometChatCalls.removeLoginListener("my-app") > ``` > [tab] Java > > ```java theme={null} > CometChatCalls.addLoginListener("my-app", new CometChatCalls.LoginListener() { > @Override public void loginSuccess(CallUser user) {} > @Override public void loginFailure(CometChatException e) {} > @Override public void logoutSuccess() {} > @Override public void logoutFailure(CometChatException e) {} > }); > > CometChatCalls.removeLoginListener("my-app"); > ``` # Join Session Source: https://www.cometchat.com/docs/calls/android/join-session Join CometChat Calls SDK v5 sessions on Android with session IDs, call tokens, participant setup, and in-call UI launch. Join a call session using one of two approaches: the quick start method with a session ID, or the advanced flow with manual token generation for more control. ## Overview The CometChat Calls SDK provides two ways to join a session: | Approach | Best For | Complexity | | - | - | - | | **Join with Session ID** | Most use cases - simple and straightforward | Low - One method call | | **Join with Token** | Custom token management, pre-generation, caching | Medium - Two-step process | > [!NOTE] > > Both approaches require a container view in your layout and properly configured [SessionSettings](/docs/calls/android/session-settings). ## Container Setup Add a container view to your layout where the call interface will be rendered: ```xml theme={null} ``` The call UI will be dynamically added to this container when you join the session. ## Join with Session ID The simplest way to join a session. Pass a session ID and the SDK automatically generates the token and joins the call. > [tab] Kotlin > > ```kotlin theme={null} > val sessionId = "SESSION_ID" > val callViewContainer = findViewById(R.id.call_view_container) > > val sessionSettings = CometChatCalls.SessionSettingsBuilder() > .setDisplayName("John Doe") > .setSessionType(SessionType.VIDEO) > .build() > > CometChatCalls.joinSession(sessionId, sessionSettings, callViewContainer, > object : CometChatCalls.CallbackListener() { > override fun onSuccess(callSession: CallSession) { > Log.d(TAG, "Joined session successfully") > } > > override fun onError(e: CometChatException) { > Log.e(TAG, "Failed: ${e.message}") > } > } > ) > ``` > [tab] Java > > ```java theme={null} > String sessionId = "SESSION_ID"; > RelativeLayout callViewContainer = findViewById(R.id.call_view_container); > > SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder() > .setDisplayName("John Doe") > .setSessionType(SessionType.VIDEO) > .build(); > > CometChatCalls.joinSession(sessionId, sessionSettings, callViewContainer, > new CometChatCalls.CallbackListener() { > @Override > public void onSuccess(CallSession callSession) { > Log.d(TAG, "Joined session successfully"); > } > > @Override > public void onError(CometChatException e) { > Log.e(TAG, "Failed: " + e.getMessage()); > } > } > ); > ``` | Parameter | Type | Description | | - | - | - | | `sessionId` | String | Unique identifier for the call session | | `sessionSettings` | SessionSettings | Configuration for the session | | `callViewContainer` | RelativeLayout | Container view for the call UI | | `listener` | CallbackListener | Callback for success/error handling | > [!NOTE] > > All participants joining the same call must use the same session ID. ## Join with Token For scenarios requiring more control over token generation, such as pre-generating tokens, implementing custom caching strategies, or managing token lifecycle separately. **Step 1: Generate Token** Generate a call token for the session. Each token is unique to a specific session and user combination. > [tab] Kotlin > > ```kotlin theme={null} > val sessionId = "SESSION_ID" > > CometChatCalls.generateToken(sessionId, object : CometChatCalls.CallbackListener() { > override fun onSuccess(token: GenerateToken) { > Log.d(TAG, "Token generated: ${token.token}") > // Store or use the token > } > > override fun onError(e: CometChatException) { > Log.e(TAG, "Token generation failed: ${e.message}") > } > }) > ``` > [tab] Java > > ```java theme={null} > String sessionId = "SESSION_ID"; > > CometChatCalls.generateToken(sessionId, new CometChatCalls.CallbackListener() { > @Override > public void onSuccess(GenerateToken token) { > Log.d(TAG, "Token generated: " + token.getToken()); > // Store or use the token > } > > @Override > public void onError(CometChatException e) { > Log.e(TAG, "Token generation failed: " + e.getMessage()); > } > }); > ``` | Parameter | Type | Description | | - | - | - | | `sessionId` | String | Unique identifier for the call session | | `listener` | CallbackListener | Callback returning the generated token | **Step 2: Join with Token** Use the generated token to join the session. This gives you control over when and how the token is used. > [tab] Kotlin > > ```kotlin theme={null} > val callViewContainer = findViewById(R.id.call_view_container) > > val sessionSettings = CometChatCalls.SessionSettingsBuilder() > .setDisplayName("John Doe") > .setSessionType(SessionType.VIDEO) > .build() > > // Use the previously generated token > CometChatCalls.joinSession(generatedToken, sessionSettings, callViewContainer, > object : CometChatCalls.CallbackListener() { > override fun onSuccess(callSession: CallSession) { > Log.d(TAG, "Joined session successfully") > } > > override fun onError(e: CometChatException) { > Log.e(TAG, "Failed: ${e.message}") > } > } > ) > ``` > [tab] Java > > ```java theme={null} > RelativeLayout callViewContainer = findViewById(R.id.call_view_container); > > SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder() > .setDisplayName("John Doe") > .setSessionType(SessionType.VIDEO) > .build(); > > // Use the previously generated token > CometChatCalls.joinSession(generatedToken, sessionSettings, callViewContainer, > new CometChatCalls.CallbackListener() { > @Override > public void onSuccess(CallSession callSession) { > Log.d(TAG, "Joined session successfully"); > } > > @Override > public void onError(CometChatException e) { > Log.e(TAG, "Failed: " + e.getMessage()); > } > } > ); > ``` | Parameter | Type | Description | | - | - | - | | `callToken` | GenerateToken | Previously generated token object | | `sessionSettings` | SessionSettings | Configuration for the session | | `callViewContainer` | RelativeLayout | Container view for the call UI | | `listener` | CallbackListener | Callback for success/error handling | **Complete Example** > [tab] Kotlin > > ```kotlin theme={null} > val sessionId = "SESSION_ID" > val callViewContainer = findViewById(R.id.call_view_container) > > // Step 1: Generate token > CometChatCalls.generateToken(sessionId, object : CometChatCalls.CallbackListener() { > override fun onSuccess(token: GenerateToken) { > // Step 2: Join with token > val sessionSettings = CometChatCalls.SessionSettingsBuilder() > .setDisplayName("John Doe") > .setSessionType(SessionType.VIDEO) > .build() > > CometChatCalls.joinSession(token, sessionSettings, callViewContainer, > object : CometChatCalls.CallbackListener() { > override fun onSuccess(callSession: CallSession) { > Log.d(TAG, "Joined session successfully") > } > > override fun onError(e: CometChatException) { > Log.e(TAG, "Failed to join: ${e.message}") > } > } > ) > } > > override fun onError(e: CometChatException) { > Log.e(TAG, "Token generation failed: ${e.message}") > } > }) > ``` > [tab] Java > > ```java theme={null} > String sessionId = "SESSION_ID"; > RelativeLayout callViewContainer = findViewById(R.id.call_view_container); > > // Step 1: Generate token > CometChatCalls.generateToken(sessionId, new CometChatCalls.CallbackListener() { > @Override > public void onSuccess(GenerateToken token) { > // Step 2: Join with token > SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder() > .setDisplayName("John Doe") > .setSessionType(SessionType.VIDEO) > .build(); > > CometChatCalls.joinSession(token, sessionSettings, callViewContainer, > new CometChatCalls.CallbackListener() { > @Override > public void onSuccess(CallSession callSession) { > Log.d(TAG, "Joined session successfully"); > } > > @Override > public void onError(CometChatException e) { > Log.e(TAG, "Failed to join: " + e.getMessage()); > } > } > ); > } > > @Override > public void onError(CometChatException e) { > Log.e(TAG, "Token generation failed: " + e.getMessage()); > } > }); > ``` ## Error Handling Common errors when joining a session: | Error Code | Description | | - | - | | `ERROR_COMETCHAT_CALLS_SDK_INIT` | SDK not initialized - call `init()` first | | `ERROR_AUTH_TOKEN` | User not logged in or auth token invalid | | `ERROR_CALL_SESSION_ID` | Session ID is null or empty | | `ERROR_CALL_TOKEN` | Invalid or missing call token | | `ERROR_CALLING_VIEW_REF_NULL` | Container view is null | | `ERROR_JSON_EXCEPTION` | Invalid session settings or response parsing error | # Calls SDK Source: https://www.cometchat.com/docs/calls/android/overview Use CometChat Calls SDK v5 for Android to add voice and video calling, call sessions, participants, layouts, and in-call features. The CometChat Calls SDK enables real-time voice and video calling capabilities in your Android application. Built on top of WebRTC, it provides a complete calling solution with built-in UI components and extensive customization options. ## Prerequisites Before integrating the Calls SDK, ensure you have: 1. **CometChat Account**: [Sign up](https://app.cometchat.com/signup) and create an app to get your App ID, Region, and API Key 2. **CometChat Users**: Users must exist in CometChat to use calling features. For testing, create users via the [Dashboard](https://app.cometchat.com) or [REST API](/docs/rest-api/users/create). Authentication is handled by the Calls SDK - see [Authentication](/docs/calls/android/authentication) 3. **Android Requirements**: * Minimum SDK: **API Level 26 (Android 8.0)** — the Calls SDK 5.1 declares `minSdk 26`, so a lower `minSdkVersion` fails the manifest merger * AndroidX compatibility 4. **Permissions**: Camera and microphone permissions for video/audio calls ## Call Flow ```mermaid theme={null} sequenceDiagram participant App participant CometChatCalls participant CallSession App->>CometChatCalls: init() App->>CometChatCalls: login() App->>CometChatCalls: joinSession(sessionId) CometChatCalls-->>App: CallSession App->>CallSession: Actions (mute, pause, etc.) CallSession-->>App: Event callbacks App->>CallSession: leave() ``` Every call is a session joined by id. Where the id comes from depends on the kind of call: * **Direct call**: your app shares a session id (for example in a message) and each participant calls `joinSession` with it. Group calls and meetings work this way. * **Ringing call**: the caller starts it with `CometChatCalls.initiateCall`, the Push Notifications SDK rings the callee, and both sides join the session once the callee answers. See [Ringing](/docs/calls/android/ringing) and [Push Ringing](/docs/calls/android/voip-calling). ## Features > [card] [Ringing](/docs/calls/android/ringing) > > Start a call, ring the callee through push, show "Ringing…", answer, decline, cancel and end > [card] [Call Layouts](/docs/calls/android/call-layouts) > > Tile and Spotlight view modes for different call scenarios > [card] [Audio Modes](/docs/calls/android/audio-modes) > > Switch between speaker, earpiece, Bluetooth, and headphones > [card] [Recording](/docs/calls/android/recording) > > Record call sessions for later playback > [card] [Transcription](/docs/calls/android/transcription) > > Transcribe calls, show live closed captions, and retrieve transcripts > [card] [Call Logs](/docs/calls/android/call-logs) > > Retrieve call history and details > [card] [Participant Management](/docs/calls/android/participant-management) > > Mute, pin, and manage call participants > [card] [Screen Sharing](/docs/calls/android/screen-sharing) > > Share your screen (opt-in) and view shared screens > [card] [Picture-in-Picture](/docs/calls/android/picture-in-picture) > > Continue calls while using other apps > [card] [Raise Hand](/docs/calls/android/raise-hand) > > Signal to get attention during calls > [card] [Idle Timeout](/docs/calls/android/idle-timeout) > > Automatic session termination when alone in a call ## Architecture The SDK is organized around these core components: | Component | Description | | - | - | | `CometChatCalls` | Main entry point for SDK initialization, authentication, and session management | | `CallAppSettings` | Configuration for SDK initialization (App ID, Region) | | `SessionSettings` | Configuration for individual call sessions | | `CallSession` | Singleton that manages the active call and provides control methods | | `Listeners` | Event interfaces for session, participant, media, and UI events | ## Sample App > [card] [Sample App](https://github.com/cometchat/calls-sdk-android/tree/v5/samples/sample-app) > > Explore the Android Calls SDK sample app on GitHub > [card] [Changelog](https://github.com/cometchat/calls-sdk-android/releases) > > View the latest releases and changes # SessionSettingsBuilder Source: https://www.cometchat.com/docs/calls/android/session-settings Configure CometChat Calls SDK v5 session settings on Android for call behavior, UI options, participant controls, and features. The `SessionSettingsBuilder` is a powerful configuration tool that allows you to customize every aspect of your call session before participants join. From controlling the initial audio/video state to customizing the UI layout and hiding specific controls, this builder gives you complete control over the call experience. Proper session configuration is crucial for creating a seamless user experience tailored to your application's specific needs. > [!NOTE] > > These are pre-session configurations that must be set before joining a call. Once configured, pass the `SessionSettings` object to the `joinSession()` method. Settings cannot be changed after the session has started, though many features can be controlled dynamically during the call using call actions. > [tab] Kotlin > > ```kotlin theme={null} > val sessionSettings = CometChatCalls.SessionSettingsBuilder() > .setTitle("Team Meeting") > .setDisplayName("John Doe") > .setSessionType(SessionType.VIDEO) > .setLayout(LayoutType.TILE) > .startAudioMuted(false) > .startVideoPaused(false) > .build() > ``` > [tab] Java > > ```java theme={null} > SessionSettings sessionSettings = new CometChatCalls.SessionSettingsBuilder() > .setTitle("Team Meeting") > .setDisplayName("John Doe") > .setSessionType(SessionType.VIDEO) > .setLayout(LayoutType.TILE) > .startAudioMuted(false) > .startVideoPaused(false) > .build(); > ``` ## Session Settings ### Title **Method:** `setTitle(String)` Sets the title that appears in the call header. This helps participants identify the purpose or name of the call session. The title is displayed prominently at the top of the call interface. > [tab] Kotlin > > ```kotlin theme={null} > .setTitle("Team Meeting") > ``` > [tab] Java > > ```java theme={null} > .setTitle("Team Meeting") > ``` | Parameter | Type | Default | | - | - | - | | `title` | String | null | ### Display Name **Method:** `setDisplayName(String)` Sets the display name that will be shown to other participants in the call. This name appears on your video tile and in the participant list, helping others identify you during the session. > [tab] Kotlin > > ```kotlin theme={null} > .setDisplayName("John Doe") > ``` > [tab] Java > > ```java theme={null} > .setDisplayName("John Doe") > ``` | Parameter | Type | Default | | - | - | - | | `displayName` | String | null | ### Session Type **Method:** `setSessionType(SessionType)` Defines the type of call session. Choose `VIDEO` for video calls with camera enabled, or `AUDIO` for audio-only calls. This setting determines whether video streaming is enabled by default. > [tab] Kotlin > > ```kotlin theme={null} > .setSessionType(SessionType.VIDEO) > ``` > [tab] Java > > ```java theme={null} > .setSessionType(SessionType.VIDEO) > ``` | Parameter | Type | Default | | - | - | - | | `type` | SessionType | VIDEO | > [accordion] SessionType Values > > | Value | Description | > | - | - | > | `VIDEO` | Video call with camera enabled | > | `AUDIO` | Audio-only call | ### Layout Mode **Method:** `setLayout(LayoutType)` Sets the initial layout mode for displaying participants. `TILE` shows all participants in a grid, `SPOTLIGHT` focuses on the active speaker with others in a sidebar, and `SIDEBAR` displays the main speaker with participants in a side panel. > [tab] Kotlin > > ```kotlin theme={null} > .setLayout(LayoutType.TILE) > ``` > [tab] Java > > ```java theme={null} > .setLayout(LayoutType.TILE) > ``` | Parameter | Type | Default | | - | - | - | | `layout` | LayoutType | TILE | > [accordion] LayoutType Values > > | Value | Description | > | - | - | > | `TILE` | Grid layout showing all participants equally | > | `SPOTLIGHT` | Focus on active speaker with others in sidebar | > | `SIDEBAR` | Main speaker with participants in a sidebar | ### Idle Timeout Period **Method:** `setIdleTimeoutPeriod(int)` Configures the timeout duration in seconds before automatically ending the session when you're the only participant. This prevents sessions from running indefinitely when others have left. > [tab] Kotlin > > ```kotlin theme={null} > .setIdleTimeoutPeriod(300) > ``` > [tab] Java > > ```java theme={null} > .setIdleTimeoutPeriod(300) > ``` | Parameter | Type | Default | | - | - | - | | `seconds` | int | 300 | ### Start Audio Muted **Method:** `startAudioMuted(boolean)` Determines whether the microphone is muted when joining the session. Set to `true` to join with audio muted, requiring users to manually unmute. Useful for large meetings to prevent background noise. > [tab] Kotlin > > ```kotlin theme={null} > .startAudioMuted(true) > ``` > [tab] Java > > ```java theme={null} > .startAudioMuted(true) > ``` | Parameter | Type | Default | | - | - | - | | `muted` | boolean | false | ### Start Video Paused **Method:** `startVideoPaused(boolean)` Controls whether the camera is turned off when joining the session. Set to `true` to join with video disabled, allowing users to enable it when ready. Helpful for privacy or bandwidth considerations. > [tab] Kotlin > > ```kotlin theme={null} > .startVideoPaused(true) > ``` > [tab] Java > > ```java theme={null} > .startVideoPaused(true) > ``` | Parameter | Type | Default | | - | - | - | | `paused` | boolean | false | ### Audio Mode **Method:** `setAudioMode(AudioMode)` Sets the initial audio output device for the call. Options include `SPEAKER` for loudspeaker, `EARPIECE` for phone earpiece, `BLUETOOTH` for connected Bluetooth devices, or `HEADPHONES` for wired headphones. > [tab] Kotlin > > ```kotlin theme={null} > .setAudioMode(AudioMode.SPEAKER) > ``` > [tab] Java > > ```java theme={null} > .setAudioMode(AudioMode.SPEAKER) > ``` | Parameter | Type | Default | | - | - | - | | `audioMode` | AudioMode | SPEAKER | > [accordion] AudioMode Values > > | Value | Description | > | - | - | > | `SPEAKER` | Device loudspeaker | > | `EARPIECE` | Phone earpiece | > | `BLUETOOTH` | Connected Bluetooth device | > | `HEADPHONES` | Wired headphones | ### Initial Camera Facing **Method:** `setInitialCameraFacing(CameraFacing)` Specifies which camera to use when starting the session. Choose `FRONT` for the front-facing camera (selfie mode) or `BACK` for the rear camera. Users can switch cameras during the call. > [tab] Kotlin > > ```kotlin theme={null} > .setInitialCameraFacing(CameraFacing.FRONT) > ``` > [tab] Java > > ```java theme={null} > .setInitialCameraFacing(CameraFacing.FRONT) > ``` | Parameter | Type | Default | | - | - | - | | `cameraFacing` | CameraFacing | FRONT | > [accordion] CameraFacing Values > > | Value | Description | > | - | - | > | `FRONT` | Front-facing camera | > | `BACK` | Rear camera | ### Low Bandwidth Mode **Method:** `enableLowBandwidthMode(boolean)` Enables optimization for poor network conditions. When enabled, the SDK reduces video quality and adjusts streaming parameters to maintain call stability on slow or unstable connections. > [tab] Kotlin > > ```kotlin theme={null} > .enableLowBandwidthMode(true) > ``` > [tab] Java > > ```java theme={null} > .enableLowBandwidthMode(true) > ``` | Parameter | Type | Default | | - | - | - | | `enabled` | boolean | false | ### Auto Start Recording **Method:** `enableAutoStartRecording(boolean)` Automatically starts recording the session as soon as it begins. When enabled, recording starts without manual intervention, ensuring the entire session is captured from the start. > [tab] Kotlin > > ```kotlin theme={null} > .enableAutoStartRecording(true) > ``` > [tab] Java > > ```java theme={null} > .enableAutoStartRecording(true) > ``` | Parameter | Type | Default | | - | - | - | | `enabled` | boolean | false | ### Auto Start Transcription *Available since v5.0.4* **Method:** `enableAutoStartTranscription(boolean)` Automatically starts transcribing the session as soon as it begins. See [Transcription](/docs/calls/android/transcription) for details. > [tab] Kotlin > > ```kotlin theme={null} > .enableAutoStartTranscription(true) > ``` > [tab] Java > > ```java theme={null} > .enableAutoStartTranscription(true) > ``` | Parameter | Type | Default | | - | - | - | | `enabled` | boolean | false | ### Caption Language *Available since v5.0.4* **Method:** `setCaptionLanguage(String)` Sets the language used for transcription and closed captions. See [Transcription](/docs/calls/android/transcription) for the full list of supported codes. > [tab] Kotlin > > ```kotlin theme={null} > .setCaptionLanguage("en-US") > ``` > [tab] Java > > ```java theme={null} > .setCaptionLanguage("en-US") > ``` | Parameter | Type | Default | | - | - | - | | `captionLanguage` | String | "en-US" | ### Hide Control Panel **Method:** `hideControlPanel(boolean)` Hides the bottom control bar that contains call action buttons. Set to `true` to remove the control panel entirely, useful for custom UI implementations or view-only modes. > [tab] Kotlin > > ```kotlin theme={null} > .hideControlPanel(true) > ``` > [tab] Java > > ```java theme={null} > .hideControlPanel(true) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | false | ### Hide Header Panel **Method:** `hideHeaderPanel(boolean)` Hides the top header bar that displays the call title and session information. Set to `true` to maximize the video viewing area or implement a custom header. > [tab] Kotlin > > ```kotlin theme={null} > .hideHeaderPanel(true) > ``` > [tab] Java > > ```java theme={null} > .hideHeaderPanel(true) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | false | ### Hide Session Timer **Method:** `hideSessionTimer(boolean)` Hides the session duration timer that shows how long the call has been active. Set to `true` to remove the timer display from the interface. > [tab] Kotlin > > ```kotlin theme={null} > .hideSessionTimer(true) > ``` > [tab] Java > > ```java theme={null} > .hideSessionTimer(true) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | false | ### Hide Leave Session Button **Method:** `hideLeaveSessionButton(boolean)` Hides the button that allows users to leave or end the call. Set to `true` to remove this button, requiring an alternative method to exit the session. > [tab] Kotlin > > ```kotlin theme={null} > .hideLeaveSessionButton(true) > ``` > [tab] Java > > ```java theme={null} > .hideLeaveSessionButton(true) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | false | ### Hide Toggle Audio Button **Method:** `hideToggleAudioButton(boolean)` Hides the microphone mute/unmute button from the control panel. Set to `true` to remove audio controls, useful when audio control should be managed programmatically. > [tab] Kotlin > > ```kotlin theme={null} > .hideToggleAudioButton(true) > ``` > [tab] Java > > ```java theme={null} > .hideToggleAudioButton(true) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | false | ### Hide Toggle Video Button **Method:** `hideToggleVideoButton(boolean)` Hides the camera on/off button from the control panel. Set to `true` to remove video controls, useful for audio-only calls or custom video control implementations. > [tab] Kotlin > > ```kotlin theme={null} > .hideToggleVideoButton(true) > ``` > [tab] Java > > ```java theme={null} > .hideToggleVideoButton(true) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | false | ### Hide Switch Camera Button **Method:** `hideSwitchCameraButton(boolean)` Hides the button that allows switching between front and rear cameras. Set to `true` to remove this control, useful for devices with single cameras or fixed camera requirements. > [tab] Kotlin > > ```kotlin theme={null} > .hideSwitchCameraButton(true) > ``` > [tab] Java > > ```java theme={null} > .hideSwitchCameraButton(true) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | false | ### Hide Recording Button **Method:** `hideRecordingButton(boolean)` Hides the recording start/stop button from the control panel. Set to `false` to show the recording button, allowing users to manually control session recording. > [tab] Kotlin > > ```kotlin theme={null} > .hideRecordingButton(false) > ``` > [tab] Java > > ```java theme={null} > .hideRecordingButton(false) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | true | ### Hide Transcription Button *Available since v5.0.4* **Method:** `hideTranscriptionButton(boolean)` Hides the transcription start/stop item from the control panel's **More** menu. Set to `false` to show it, allowing users to manually control session transcription. > [tab] Kotlin > > ```kotlin theme={null} > .hideTranscriptionButton(false) > ``` > [tab] Java > > ```java theme={null} > .hideTranscriptionButton(false) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | true | ### Hide Closed Caption Button *Available since v5.0.4* **Method:** `hideClosedCaptionButton(boolean)` Hides the closed-caption (Show/Hide Captions) item from the control panel's **More** menu. Set to `false` to show it, allowing users to toggle the live captions overlay. Even when set to `false`, the item only appears while transcription is running. > [tab] Kotlin > > ```kotlin theme={null} > .hideClosedCaptionButton(false) > ``` > [tab] Java > > ```java theme={null} > .hideClosedCaptionButton(false) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | true | ### Hide Screen Sharing Button **Method:** `hideScreenSharingButton(boolean)` Hides the screen sharing button from the control panel. Set to `true` to remove screen sharing controls, useful when screen sharing is not needed or managed separately. > [tab] Kotlin > > ```kotlin theme={null} > .hideScreenSharingButton(true) > ``` > [tab] Java > > ```java theme={null} > .hideScreenSharingButton(true) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | false | ### Hide Audio Mode Button **Method:** `hideAudioModeButton(boolean)` Hides the button that toggles between speaker, earpiece, and other audio output modes. Set to `true` to remove audio mode controls from the interface. > [tab] Kotlin > > ```kotlin theme={null} > .hideAudioModeButton(true) > ``` > [tab] Java > > ```java theme={null} > .hideAudioModeButton(true) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | false | ### Hide Raise Hand Button **Method:** `hideRaiseHandButton(boolean)` Hides the raise hand button that participants use to signal they want to speak. Set to `true` to remove this feature from the interface. > [tab] Kotlin > > ```kotlin theme={null} > .hideRaiseHandButton(true) > ``` > [tab] Java > > ```java theme={null} > .hideRaiseHandButton(true) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | false | ### Hide Share Invite Button **Method:** `hideShareInviteButton(boolean)` Hides the button that allows sharing session invite links with others. Set to `false` to show the invite button, enabling easy participant invitation. > [tab] Kotlin > > ```kotlin theme={null} > .hideShareInviteButton(false) > ``` > [tab] Java > > ```java theme={null} > .hideShareInviteButton(false) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | true | ### Hide Participant List Button **Method:** `hideParticipantListButton(boolean)` Hides the button that opens the participant list view. Set to `true` to remove access to the participant list, useful for simplified interfaces. > [tab] Kotlin > > ```kotlin theme={null} > .hideParticipantListButton(true) > ``` > [tab] Java > > ```java theme={null} > .hideParticipantListButton(true) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | false | ### Hide Change Layout Button **Method:** `hideChangeLayoutButton(boolean)` Hides the button that allows switching between different layout modes (tile, spotlight, sidebar). Set to `true` to lock the layout to the initial setting. > [tab] Kotlin > > ```kotlin theme={null} > .hideChangeLayoutButton(true) > ``` > [tab] Java > > ```java theme={null} > .hideChangeLayoutButton(true) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | false | ### Hide Chat Button **Method:** `hideChatButton(boolean)` Hides the button that opens the in-call chat interface. Set to `false` to show the chat button, enabling text communication during calls. > [tab] Kotlin > > ```kotlin theme={null} > .hideChatButton(false) > ``` > [tab] Java > > ```java theme={null} > .hideChatButton(false) > ``` | Parameter | Type | Default | | - | - | - | | `hide` | boolean | true | > [accordion] Enum Values > > | Enum | Value | Description | > | - | - | - | > | `SessionType` | `VIDEO` | Video call with camera enabled | > | | `AUDIO` | Audio-only call | > | `LayoutType` | `TILE` | Grid layout showing all participants equally | > | | `SPOTLIGHT` | Focus on active speaker with others in sidebar | > | | `SIDEBAR` | Main speaker with participants in a sidebar | > | `AudioMode` | `SPEAKER` | Device loudspeaker | > | | `EARPIECE` | Phone earpiece | > | | `BLUETOOTH` | Connected Bluetooth device | > | | `HEADPHONES` | Wired headphones | > | `CameraFacing` | `FRONT` | Front-facing camera | > | | `BACK` | Rear camera | # Setup Source: https://www.cometchat.com/docs/calls/android/setup Set up CometChat Calls SDK v5 for Android with installation, app credentials, initialization, authentication, and the push dependencies needed for ringing. > [!NOTE] > > **Faster Integration with UI Kits** > > If you're using CometChat UI Kits, voice and video calling can be quickly integrated: > > * Incoming & outgoing call screens > * Call buttons with one-tap calling > * Call logs with history > > 👉 [Android UI Kit Calling Integration](/docs/ui-kit/android/calling-integration) > > Use this Calls SDK directly only if you need custom call UI or advanced control. This guide walks you through installing the CometChat Calls SDK and initializing it in your Android application. ## Add the CometChat Dependency ### Step 1: Add Repository Add the CometChat repository URL to your **project level** `build.gradle` file in the `repositories` block. Keep `google()` and `mavenCentral()` in the list: the Calls SDK's WebRTC library (`org.jitsi:webrtc`) is resolved from Maven Central. > [tab] Groovy > > ```groovy theme={null} > allprojects { > repositories { > google() > mavenCentral() > maven { > url "https://dl.cloudsmith.io/public/cometchat/cometchat/maven/" > } > } > } > ``` > [tab] Kotlin DSL > > ```kotlin theme={null} > allprojects { > repositories { > google() > mavenCentral() > maven { > url = uri("https://dl.cloudsmith.io/public/cometchat/cometchat/maven/") > } > } > } > ``` > [!NOTE] > > If your project declares repositories in `settings.gradle` (`dependencyResolutionManagement`) instead of > `allprojects`, add the same three entries there. ### Step 2: Add Dependencies Add the Calls SDK dependency to your **app level** `build.gradle` file: > [tab] Groovy > > ```groovy theme={null} > dependencies { > implementation "com.cometchat:calls-sdk-android:5.1.0" > } > ``` > [tab] Kotlin DSL > > ```kotlin theme={null} > dependencies { > implementation("com.cometchat:calls-sdk-android:5.1.0") > } > ``` > [!NOTE] > > **Ringing users?** Incoming calls ring through the Push Notifications SDK's calls module. Add > `com.cometchat:push-notifications-android:2.0.0` and `com.cometchat:push-notifications-calls-android:2.0.0` > as well, and follow [Push Ringing](/docs/calls/android/voip-calling). The Calls SDK alone can start, join and end > calls, but it cannot ring a device that is not running your app. > [!WARNING] > > **Set `minSdkVersion` to 26 or higher.** The Calls SDK 5.1 declares `minSdk 26` (5.0 was 24), so a lower value > fails the build at the manifest merger: > `uses-sdk:minSdkVersion 24 cannot be smaller than version 26 declared in library [...]`. > [!NOTE] > > The Calls SDK carries its own React Native runtime, relocated to the `cometchat.rn.*` namespace so it does not clash > with other React Native code in your app, and it initializes the runtime's native libraries itself. Do not add > `react-android` or `soloader` dependencies or call `SoLoader.init` for the Calls SDK. ### Step 3: Configure Java Version Add Java 17 compatibility to the `android` section of your **app level** `build.gradle` — the Calls SDK is built with Java 17. The `kotlinOptions` block applies only if your module uses Kotlin (Java-only modules should omit it); on Kotlin 2.x, prefer `compilerOptions { jvmTarget.set(JvmTarget.JVM_17) }`: > [tab] Groovy > > ```groovy theme={null} > android { > compileOptions { > sourceCompatibility JavaVersion.VERSION_17 > targetCompatibility JavaVersion.VERSION_17 > } > kotlinOptions { // Only if your module uses Kotlin > jvmTarget = "17" > } > } > ``` > [tab] Kotlin DSL > > ```kotlin theme={null} > android { > compileOptions { > sourceCompatibility = JavaVersion.VERSION_17 > targetCompatibility = JavaVersion.VERSION_17 > } > kotlinOptions { // Only if your module uses Kotlin > jvmTarget = "17" > } > } > ``` ## Add Permissions The Calls SDK's own manifest declares the permissions a call needs (`INTERNET`, `CAMERA`, `RECORD_AUDIO`, `MODIFY_AUDIO_SETTINGS`, `ACCESS_NETWORK_STATE`, the microphone and camera foreground-service types, and others), and Android merges them into your app. There is nothing to add to your `AndroidManifest.xml` for audio and video calls. ### Screen sharing (opt-in) Screen sharing is opt-in. Android needs a foreground service of type `mediaProjection` to share the screen, and Google Play asks every app that declares one to justify it, so the Calls SDK removes that service from the merged manifest. Until your app declares it, the screen share button is hidden in the call UI. To enable screen sharing, add the permission and the service to your `AndroidManifest.xml`: ```xml theme={null}

``` The SDK checks for the service (with the `mediaProjection` type) and, when your app targets Android 14 or later, for the permission. If either is missing, it logs why and keeps the screen share button hidden. > [!NOTE] > > Request camera and microphone permissions at runtime before starting or joining a call. When a call is answered from > the Push SDK's ring, the SDK asks for them before opening your answer activity; a denied microphone joins muted. On > Android 14+ the call's foreground service is blocked while the microphone permission is missing. ## Initialize CometChat Calls The `init()` method initializes the SDK with your app credentials. Call this method once when your application starts, typically in your `Application` class or main `Activity`. ### CallAppSettings The `CallAppSettings` class configures the SDK initialization: | Parameter | Type | Required | Description | | - | - | - | - | | `appId` | String | Yes | Your CometChat App ID | | `region` | String | Yes | Your app region (`us` or `eu`) | > [tab] Kotlin > > ```kotlin theme={null} > import com.cometchat.calls.core.CometChatCalls > import com.cometchat.calls.core.CallAppSettings > > val appId = "APP_ID" // Replace with your App ID > val region = "REGION" // Replace with your Region ("us" or "eu") > > val callAppSettings = CallAppSettings.CallAppSettingBuilder(appId, region).build() > > CometChatCalls.init(this, callAppSettings, object : CometChatCalls.CallbackListener() { > override fun onSuccess(message: String) { > Log.d(TAG, "CometChat Calls SDK initialized successfully") > } > > override fun onError(e: CometChatException) { > Log.e(TAG, "CometChat Calls SDK initialization failed: ${e.message}") > } > }) > ``` > [tab] Java > > ```java theme={null} > import com.cometchat.calls.core.CometChatCalls; > import com.cometchat.calls.core.CallAppSettings; > > String appId = "APP_ID"; // Replace with your App ID > String region = "REGION"; // Replace with your Region ("us" or "eu") > > CallAppSettings callAppSettings = new CallAppSettings.CallAppSettingBuilder(appId, region).build(); > > CometChatCalls.init(this, callAppSettings, new CometChatCalls.CallbackListener() { > @Override > public void onSuccess(String message) { > Log.d(TAG, "CometChat Calls SDK initialized successfully"); > } > > @Override > public void onError(CometChatException e) { > Log.e(TAG, "CometChat Calls SDK initialization failed: " + e.getMessage()); > } > }); > ``` | Parameter | Description | | - | - | | `this` | Android context (Application or Activity context) | | `callAppSettings` | Configuration object with App ID and Region | | `listener` | Callback listener for success/error handling | > [!WARNING] > > **Initialize once.** The SDK keeps the settings from its first `init()`; a later `init()` with the same app ID is > ignored for the rest of the process. A later `init()` with a different app ID logs the user out and re-creates the > SDK with the new settings. If you use the CometChat UI Kit with `enableCalling`, it initializes the Calls SDK for you, so do > not call `init()` again yourself. ## Check Initialization Status You can verify if the SDK has been initialized using the `isInitialized()` method: > [tab] Kotlin > > ```kotlin theme={null} > if (CometChatCalls.isInitialized()) { > // SDK is ready to use > } else { > // Initialize the SDK first > } > ``` > [tab] Java > > ```java theme={null} > if (CometChatCalls.isInitialized()) { > // SDK is ready to use > } else { > // Initialize the SDK first > } > ``` # Actions Source: https://www.cometchat.com/docs/calls/ios/actions Use CometChat Calls SDK v5 actions on iOS to control calls, manage audio/video state, share screens, and handle in-call behavior. Use call actions to create your own custom controls or trigger call functionality dynamically based on your use case. All actions are called on the `CallSession.shared` singleton instance during an active call session. ## Get CallSession Instance The `CallSession` is a singleton that manages the active call. All actions are accessed through this instance. ```swift theme={null} let callSession = CallSession.shared ``` > [!NOTE] > > Always check `isSessionJoined()` before calling in-call actions to ensure you are in a call. ## Actions ### Mute Audio Mutes your local microphone, stopping audio transmission to other participants. ```swift theme={null} CallSession.shared.muteAudio() ``` ### Unmute Audio Unmutes your local microphone, resuming audio transmission. ```swift theme={null} CallSession.shared.unmuteAudio() ``` ### Set Audio Mode Changes the audio output device during a call. ```swift theme={null} CallSession.shared.setAudioMode("SPEAKER") CallSession.shared.setAudioMode("EARPIECE") CallSession.shared.setAudioMode("BLUETOOTH") CallSession.shared.setAudioMode("HEADPHONES") ``` > [accordion] AudioMode Values > > | Value | Description | > | - | - | > | `SPEAKER` | Routes audio through device loudspeaker | > | `EARPIECE` | Routes audio through phone earpiece | > | `BLUETOOTH` | Routes audio through connected Bluetooth device | > | `HEADPHONES` | Routes audio through wired headphones | ### Pause Video Turns off your local camera, stopping video transmission. Other participants see your avatar. ```swift theme={null} CallSession.shared.pauseVideo() ``` ### Resume Video Turns on your local camera, resuming video transmission. ```swift theme={null} CallSession.shared.resumeVideo() ``` ### Switch Camera Toggles between front and back cameras without interrupting the video stream. ```swift theme={null} CallSession.shared.switchCamera() ``` ### Start Recording Begins server-side recording of the call. All participants are notified. ```swift theme={null} CallSession.shared.startRecording() ``` > [!WARNING] > > Recording requires the feature to be enabled for your CometChat app. ### Stop Recording Stops the current recording. The recording is saved and accessible via the dashboard. ```swift theme={null} CallSession.shared.stopRecording() ``` ### Start Transcription *Available since v5.0.4* Begins server-side transcription of the call. This also enables the live closed captions overlay. ```swift theme={null} CallSession.shared.startTranscription() ``` > [!WARNING] > > Transcription requires the feature to be enabled for your CometChat app. ### Stop Transcription *Available since v5.0.4* Stops the current transcription and clears any captions currently on screen. The transcript is saved and can be retrieved with [`TranscriptsRequest`](/docs/calls/ios/transcription#retrieving-transcripts). ```swift theme={null} CallSession.shared.stopTranscription() ``` ### Mute Participant Mutes a specific participant's audio. This is a moderator action. ```swift theme={null} guard let uid = participant.uid else { return } CallSession.shared.muteParticipant(participantId: uid) ``` ### Pause Participant Video Pauses a specific participant's video. This is a moderator action. ```swift theme={null} guard let uid = participant.uid else { return } CallSession.shared.pauseParticipantVideo(participantId: uid) ``` ### Pin Participant Pins a participant to keep them prominently displayed regardless of who is speaking. ```swift theme={null} CallSession.shared.pinParticipant(participantId: "PARTICIPANT_UID", type: "pin") ``` ### Unpin Participant Removes the pin, returning to automatic speaker highlighting. ```swift theme={null} CallSession.shared.unpinParticipant() ``` ### Set Layout Changes the call layout. Each participant can choose their own layout independently. ```swift theme={null} CallSession.shared.setLayout("TILE") CallSession.shared.setLayout("SPOTLIGHT") CallSession.shared.setLayout("SIDEBAR") ``` > [accordion] LayoutType Values > > | Value | Description | > | - | - | > | `TILE` | Grid layout with equally-sized tiles | > | `SPOTLIGHT` | Large view for active speaker, small tiles for others | > | `SIDEBAR` | Main speaker with participants in a sidebar | ### Enable Picture In Picture Layout Enables PiP mode, allowing the call to continue in a floating window. ```swift theme={null} CallSession.shared.enablePictureInPictureLayout() ``` ### Disable Picture In Picture Layout Disables PiP mode, returning to full-screen call interface. ```swift theme={null} CallSession.shared.disablePictureInPictureLayout() ``` ### Set Chat Button Unread Count Updates the badge count on the chat button. Pass 0 to hide the badge. ```swift theme={null} CallSession.shared.setChatButtonUnreadCount(5) ``` ### Is Session Active `isSessionActive()` returns `true` while the SDK owns a session: one being prepared or prepared (for example an outgoing call that is still ringing), one being joined, or a joined one. `isSessionJoined()` is the narrower "in a call" check: `true` only once the media session is joined. ```swift theme={null} let isActive = CallSession.shared.isSessionActive() let isInCall = CallSession.shared.isSessionJoined() ``` > [!NOTE] > > `isCallSessionActive()` is deprecated in 5.1 and renamed `isSessionActive()`. Because it now also covers a prepared session, use `isSessionJoined()` where you meant "in a call". ### Leave Session Ends your participation and disconnects gracefully. In a 1:1 call this is the hang-up: the other side receives `onParticipantLeft` and the backend records the end, and a session joined as a peer call (`setPeerCall(true)`) ends for both. In a group call the session continues for the other participants. Leaving also cancels a session that is only prepared. ```swift theme={null} CallSession.shared.leave() ``` > [!NOTE] > > `leaveSession()` is deprecated in 5.1 and only calls `leave()`. To end a call that is still ringing use `CometChatCalls.endCall(sessionID:status:onSuccess:onError:)` with `EndCallStatus.cancelled` (caller), as described in [Ringing](/docs/calls/ios/ringing); `leave()` alone does not tell the other side why. ### Raise Hand Shows a hand-raised indicator to get attention from other participants. ```swift theme={null} CallSession.shared.raiseHand() ``` ### Lower Hand Removes the hand-raised indicator. ```swift theme={null} CallSession.shared.lowerHand() ``` ### Hide Settings Panel Hides the settings panel if it's currently visible. ```swift theme={null} CallSession.shared.hideSettingsPanel() ``` > [accordion] Participant Object Reference > > | Property | Type | Description | > | - | - | - | > | `uid` | `String?` | CometChat user ID — the identifier every moderator action takes | > | `name` | `String?` | Display name | > | `avatar` | `String?` | URL of avatar image | > | `mid` | `String?` | Media ID for this call session | > | `state` | `String?` | Participant state as reported by the server | > | `isJoined` | `Bool?` | Whether the participant is currently joined | > | `joinedAt` | `Int?` | Join timestamp | > | `leftAt` | `Int?` | Leave timestamp | > | `deviceID` | `String?` | Device identifier | > | `totalAudioMinutes` | `Double?` | Audio minutes consumed | > | `totalVideoMinutes` | `Double?` | Video minutes consumed | > | `totalDurationInMinutes` | `Double?` | Total session minutes | > > > [!NOTE] > > > > **Every property is Optional.** `Participant` carries no mute / video / pin / hand-raise / > > screen-share flags, and the SDK exposes no getter for them — track that state in your own app > > from the [participant events](/docs/calls/ios/events). Because the events fire only on change, a > > client that joins late cannot recover state that was already in effect. # Audio Modes Source: https://www.cometchat.com/docs/calls/ios/audio-modes Configure CometChat Calls SDK v5 audio modes on iOS for speakers, earpiece, Bluetooth, routing, and call audio behavior. Control audio output routing during calls. Switch between speaker, earpiece, Bluetooth, and wired headphones based on user preference or device availability. ## Available Audio Modes | Mode | Description | | - | - | | `.speaker` | Routes audio through the device loudspeaker | | `.earpiece` | Routes audio through the phone earpiece (for private calls) | | `.bluetooth` | Routes audio through a connected Bluetooth device | | `.headphones` | Routes audio through wired headphones | ## Set Initial Audio Mode Configure the audio mode when joining a session: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .setAudioMode(.speaker) .build() CometChatCalls.joinSession( sessionID: sessionId, callSetting: sessionSettings, container: callViewContainer, onSuccess: { message in print("Joined with speaker mode") }, onError: { error in print("Failed: \(error?.errorDescription ?? "")") } ) ``` ## Change Audio Mode During Call Switch audio modes dynamically during an active call: ```swift theme={null} // Switch to speaker CallSession.shared.setAudioMode("SPEAKER") // Switch to earpiece CallSession.shared.setAudioMode("EARPIECE") // Switch to Bluetooth CallSession.shared.setAudioMode("BLUETOOTH") // Switch to wired headphones CallSession.shared.setAudioMode("HEADPHONES") ``` ## Listen for Audio Mode Changes Monitor audio mode changes using `MediaEventsListener`: ```swift theme={null} class CallViewController: UIViewController, MediaEventsListener { override func viewDidLoad() { super.viewDidLoad() CallSession.shared.addMediaEventsListener(self) } deinit { CallSession.shared.removeMediaEventsListener(self) } func onAudioModeChanged(audioMode: AudioMode) { switch audioMode { case .speaker: print("Switched to speaker") case .earpiece: print("Switched to earpiece") case .bluetooth: print("Switched to Bluetooth") case .headphones: print("Switched to headphones") default: break } // Update audio mode button icon updateAudioModeIcon(audioMode) } // Other callbacks... func onAudioMuted() {} func onAudioUnMuted() {} func onVideoPaused() {} func onVideoResumed() {} func onRecordingStarted() {} func onRecordingStopped() {} func onCameraFacingChanged(cameraFacing: CameraFacing) {} } ``` ## Hide Audio Mode Button To prevent users from changing the audio mode, hide the button in the call UI: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .setAudioMode(.speaker) // Fixed audio mode .hideAudioModeButton(true) // Hide toggle button .build() ``` > [!NOTE] > > The SDK automatically detects connected audio devices. If Bluetooth or wired headphones are connected, they become available as audio mode options. # Authentication Source: https://www.cometchat.com/docs/calls/ios/authentication Configure authentication for CometChat Calls SDK v5 on iOS with app credentials, logged-in users, and secure call access. Before users can make or receive calls, they must be authenticated with the CometChat Calls SDK. This guide covers the login and logout methods. > [!NOTE] > > **Sample Users** > > CometChat provides 5 test users: `cometchat-uid-1`, `cometchat-uid-2`, `cometchat-uid-3`, `cometchat-uid-4`, and `cometchat-uid-5`. ## Check Login Status Before calling `login()`, check if a user is already logged in using `getLoggedInUser()`. The SDK maintains the session internally, so you only need to login once per user session. ```swift theme={null} if let loggedInUser = CometChatCalls.getLoggedInUser() { // User is already logged in print("User already logged in: \(loggedInUser.uid ?? "")") } else { // No user logged in, proceed with login } ``` The `getLoggedInUser()` method returns a `CallsUser` object if a user is logged in, or `nil` if no session exists. ## Login with UID and API Key This method is suitable for development and testing. For production apps, use [Auth Token login](#login-with-auth-token) instead. > [!WARNING] > > **Security Notice** > > Using the API Key directly in client code is not recommended for production. Use Auth Token authentication for enhanced security. ```swift theme={null} let uid = "cometchat-uid-1" // Replace with your user's UID let apiKey = "API_KEY" // Replace with your API Key if CometChatCalls.getLoggedInUser() == nil { CometChatCalls.login(UID: uid, apiKey: apiKey, onSuccess: { user in print("Login successful: \(user.uid ?? "")") }, onError: { error in print("Login failed: \(error.errorDescription)") }) } else { // User already logged in } ``` | Parameter | Type | Description | | - | - | - | | `UID` | String | The unique identifier of the user to login | | `apiKey` | String | Your CometChat API Key | | `onSuccess` | Closure | Closure called with `CallsUser` on success | | `onError` | Closure | Closure called with error on failure | ## Login with Auth Token This is the recommended authentication method for production applications. The Auth Token is generated server-side, keeping your API Key secure. ### Auth Token Flow 1. User authenticates with your backend 2. Your backend calls the [CometChat Create Auth Token API](https://api-explorer.cometchat.com/reference/create-authtoken) 3. Your backend returns the Auth Token to the client 4. Client uses the Auth Token to login ```swift theme={null} let authToken = "AUTH_TOKEN" // Token received from your backend CometChatCalls.login(authToken: authToken, onSuccess: { user in print("Login successful: \(user.uid ?? "")") }, onError: { error in print("Login failed: \(error.errorDescription)") }) ``` | Parameter | Type | Description | | - | - | - | | `authToken` | String | Auth Token generated via CometChat API | | `onSuccess` | Closure | Closure called with `CallsUser` on success | | `onError` | Closure | Closure called with error on failure | ## CallsUser Object On successful login, the callback returns a `CallsUser` object containing user information: | Property | Type | Description | | - | - | - | | `uid` | String? | Unique identifier of the user | | `name` | String? | Display name of the user | | `avatar` | String? | URL of the user's avatar image | | `status` | UserStatus | User's online status | ## Logout Call `logout()` when the user signs out of your application. This clears the local session and disconnects from CometChat services. ```swift theme={null} CometChatCalls.logout(onSuccess: { message in print("Logout successful") }, onError: { error in print("Logout failed: \(error.errorDescription)") }) ``` ## Error Handling Common authentication errors: | Error Code | Description | | - | - | | `ERROR_INVALID_UID` | The provided UID is empty or invalid | | `ERROR_UID_WITH_SPACE` | The UID contains spaces (not allowed) | | `ERROR_API_KEY_NOT_FOUND` | The API Key is missing or invalid | | `ERROR_BLANK_AUTHTOKEN` | The Auth Token is empty | | `ERROR_AUTHTOKEN_WITH_SPACE` | The Auth Token contains spaces | # Background Handling Source: https://www.cometchat.com/docs/calls/ios/background-handling Handle iOS background modes in CometChat Calls SDK v5 to keep active calls running when the app moves to the background. Keep calls alive when users navigate away from your app. Background handling ensures the call continues running when users press the home button, switch to another app, or lock their device. ## Overview When a user leaves your call view controller, iOS may suspend it to free resources. Proper background handling: * Keeps the call session active in the background * Maintains audio/video streams * Allows users to return to the call seamlessly ```mermaid theme={null} flowchart LR subgraph "User in Call" A[Call VC] --> B{User Action} end B -->|Stays in app| A B -->|Presses HOME| C[Background Mode] B -->|Opens other app| C B -->|Locks device| C C --> D[Call Continues] D -->|Returns to app| A ``` ## When to Use | Scenario | Solution | | - | - | | User stays in call view | No action needed | | User presses HOME during call | **Use Background Modes** | | User switches to another app | **Use Background Modes** | | User locks device during call | **Use Background Modes** | | Receiving calls when app is killed | [VoIP Calling](/docs/calls/ios/voip-calling) handles this | > [!NOTE] > > Background Handling is different from [VoIP Calling](/docs/calls/ios/voip-calling). VoIP handles **receiving** calls when the app is not running. Background Handling keeps an **active** call alive when the user leaves the app. *** ## Enable Background Modes In Xcode, add the following background modes to your app: **1.** Go to your target's "Signing & Capabilities" tab **2.** Add "Background Modes" capability **3.** Enable the following modes: * Audio, AirPlay, and Picture in Picture * Voice over IP > [!NOTE] > > The Calls SDK automatically handles audio session configuration. You only need to enable the background modes capability. *** ## Related Documentation * [VoIP Calling](/docs/calls/ios/voip-calling) - Receive calls when app is killed * [Events](/docs/calls/ios/events) - Session status events # Call Layouts Source: https://www.cometchat.com/docs/calls/ios/call-layouts Customize CometChat Calls SDK v5 call layouts on iOS with tile, spotlight, sidebar views, layout changes, and layout events. Choose how participants are displayed during a call. The SDK provides multiple layout options to suit different use cases like team meetings, presentations, or one-on-one calls. ## Available Layouts | Layout | Description | Best For | | - | - | - | | `.tile` | Grid layout with equally-sized tiles for all participants | Team meetings, group discussions | | `.spotlight` | Large view for the other participant, small tile for yourself | One-on-one calls, presentations, webinars | | `.sidebar` | Main speaker with participants in a sidebar | Interviews, panel discussions | ## Set Initial Layout Configure the layout when joining a session using `SessionSettingsBuilder`: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .setLayout(.tile) .build() CometChatCalls.joinSession( sessionID: sessionId, callSetting: sessionSettings, container: callViewContainer, onSuccess: { message in print("Joined with TILE layout") }, onError: { error in print("Failed: \(error?.errorDescription ?? "")") } ) ``` ## Change Layout During Call Switch layouts dynamically during an active call using `setLayout()`: ```swift theme={null} // Switch to Spotlight layout CallSession.shared.setLayout("SPOTLIGHT") // Switch to Tile layout CallSession.shared.setLayout("TILE") // Switch to Sidebar layout CallSession.shared.setLayout("SIDEBAR") ``` > [!NOTE] > > Each participant can choose their own layout independently. Changing your layout does not affect other participants. ## Listen for Layout Changes Monitor layout changes using `LayoutListener`: ```swift theme={null} class CallViewController: UIViewController, LayoutListener { override func viewDidLoad() { super.viewDidLoad() CallSession.shared.addLayoutListener(self) } deinit { CallSession.shared.removeLayoutListener(self) } func onCallLayoutChanged(layoutType: LayoutType) { switch layoutType { case .tile: print("Switched to Tile layout") case .spotlight: print("Switched to Spotlight layout") case .sidebar: print("Switched to Sidebar layout") default: break } // Update layout toggle button icon updateLayoutIcon(layoutType) } func onParticipantListVisible() {} func onParticipantListHidden() {} func onPictureInPictureLayoutEnabled() {} func onPictureInPictureLayoutDisabled() {} } ``` ## Hide Layout Toggle Button To prevent users from changing the layout, hide the layout toggle button in the call UI: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .setLayout(.spotlight) // Fixed layout .hideChangeLayoutButton(true) // Hide toggle button .build() ``` # Call Logs Source: https://www.cometchat.com/docs/calls/ios/call-logs Display CometChat Calls SDK v5 call logs on iOS with call history, participants, call type, duration, and status details. Retrieve call history for your application. Call logs provide detailed information about past calls including duration, participants, recordings, and status. ## Fetch Call Logs Use `CallLogsRequest` to fetch call logs with pagination support. The builder pattern allows you to filter results by various criteria. ```swift theme={null} let callLogRequest = CallLogsRequest.CallLogsBuilder() .set(limit: 30) .build() callLogRequest.fetchNext(onSuccess: { callLogs in for callLog in callLogs { print("Session: \(callLog.sessionID)") print("Duration: \(callLog.totalDuration)") print("Status: \(callLog.status.value)") } }, onError: { error in print("Error: \(error?.errorDescription ?? "")") }) ``` ## Check One Call To read the status of one call, for example while an outgoing call rings, use `getCallDetail`. Without `authToken` it uses the logged-in user's token. ```swift theme={null} CometChatCalls.getCallDetail(sessionID: sessionId, onSuccess: { callLogs in guard let status = callLogs.first?.status else { return } if status == .rejected || status == .busy { // Close the outgoing call screen } }, onError: { error in print("Could not read the call: \(error?.errorDescription ?? "")") }) ``` When polling, call it every few seconds and stop when the call is answered, reaches a final status, or the screen closes. ## CallLogsBuilder Configure the request using the builder methods: | Method | Type | Description | | - | - | - | | `set(limit: Int)` | Int | Number of call logs to fetch per request (default: 30, max: 100) | | `set(callType: SessionType)` | SessionType | Filter by call type: `.video` or `.voice` | | `set(callStatus: CallStatus)` | CallStatus | Filter by call status | | `set(hasRecording: Bool)` | Bool | Filter calls that have recordings | | `set(hasTranscriptions: Bool)` | Bool | Filter calls that have transcripts, and attach them to each log | | `set(callCategory: CallCategory)` | CallCategory | Filter by category: `.call`, `.meet`, `.presenter` or `.broadcast` | | `set(callDirection: CallDirection)` | CallDirection | Filter by direction: `.incoming` or `.outgoing` | | `set(uid: String)` | String | Filter calls with a specific user | | `set(guid: String)` | String | Filter calls with a specific group | > [!NOTE] > > In Objective-C these are `setWithLimit:`, `setWithCallType:`, `setWithHasTranscriptions:` and so on, and the builder is instantiated directly as `[[CallLogsBuilder alloc] init]`. ### Filter Examples ```swift theme={null} // Fetch only video calls let videoCallsRequest = CallLogsRequest.CallLogsBuilder() .set(callType: .video) .set(limit: 20) .build() // Fetch calls with recordings let recordedCallsRequest = CallLogsRequest.CallLogsBuilder() .set(hasRecording: true) .build() // Fetch calls with transcripts let transcribedCallsRequest = CallLogsRequest.CallLogsBuilder() .set(hasTranscriptions: true) .build() // Fetch missed incoming calls let missedCallsRequest = CallLogsRequest.CallLogsBuilder() .set(callStatus: .missed) .set(callDirection: .incoming) .build() // Fetch calls with a specific user let userCallsRequest = CallLogsRequest.CallLogsBuilder() .set(uid: "user_id") .build() ``` ## Pagination Use `fetchNext` and `fetchPrevious` for pagination. `fetchPrevious` takes an optional `authToken`; pass `nil` to use the logged-in user's stored token: ```swift theme={null} // Fetch next page callLogRequest.fetchNext(onSuccess: { callLogs in // Handle next page }, onError: { error in print("Error: \(error?.errorDescription ?? "")") }) // Fetch previous page callLogRequest.fetchPrevious(authToken: nil, onSuccess: { callLogs in // Handle previous page }, onError: { error in print("Error: \(error?.errorDescription ?? "")") }) ``` ## CallLog Object Each `CallLog` object contains detailed information about a call: | Property | Type | Description | | - | - | - | | `sessionID` | String | Unique identifier for the call session | | `mid` | String | Meeting identifier | | `initiator` | CallEntity | User who initiated the call | | `receiver` | CallEntity | User or group that received the call | | `receiverType` | CallEntityType | `.callUser` or `.callGroup` | | `type` | SessionType | Call type: `.video` or `.voice` | | `status` | CallStatus | Final status of the call | | `mode` | CallCategory | Category: `.call`, `.meet`, `.presenter` or `.broadcast` | | `initiatedAt` | Int | Timestamp when call was initiated | | `startedAt` | Int? | Timestamp when call started | | `endedAt` | Int? | Timestamp when call ended | | `totalDuration` | String | Human-readable duration (e.g., "5:30") | | `totalDurationInMinutes` | Double | Duration in minutes | | `totalAudioMinutes` | Double | Audio duration in minutes | | `totalVideoMinutes` | Double | Video duration in minutes | | `totalParticipants` | Int | Number of participants | | `participants` | \[Participant] | List of participants who joined | | `hasRecording` | Bool | Whether the call was recorded | | `recordings` | \[Recording] | List of recording objects | | `transcriptions` | \[Transcript] | List of transcript objects. Populated only when the request opted in with `set(hasTranscriptions:)` | ## Access Recordings If a call has recordings, access them through the `recordings` property: ```swift theme={null} callLogRequest.fetchNext(onSuccess: { callLogs in for callLog in callLogs { if callLog.hasRecording { for recording in callLog.recordings { print("Recording ID: \(recording.rid ?? "")") print("Recording URL: \(recording.recordingURL ?? "")") print("Duration: \(recording.duration ?? 0) seconds") } } } }, onError: { error in print("Error: \(error?.errorDescription ?? "")") }) ``` ## Access Transcripts *Available since v5.0.4* Opting in with `set(hasTranscriptions: true)` restricts the list to transcribed calls **and** makes the server attach each call's transcripts to the log: ```swift theme={null} let callLogRequest = CallLogsRequest.CallLogsBuilder() .set(limit: 30) .set(hasTranscriptions: true) .build() callLogRequest.fetchNext(onSuccess: { callLogs in for callLog in callLogs { for transcript in callLog.transcriptions { print("Transcript ID: \(transcript.tid)") print("Transcript URL: \(transcript.transcriptUrl)") } } }, onError: { error in print("Error: \(error?.errorDescription ?? "")") }) ``` `transcriptions` is an empty array when the server omitted transcripts, so it never needs a nil check. To page through a single session's transcripts directly, use [`TranscriptsRequest`](/docs/calls/ios/transcription#retrieving-transcripts). > [accordion] Call Status Values > > | Status | Description | > | - | - | > | `ongoing` | Call is currently in progress | > | `busy` | Receiver was busy | > | `rejected` | Call was rejected | > | `cancelled` | Call was cancelled by initiator | > | `ended` | Call ended normally | > | `missed` | Call was missed | > | `initiated` | Call was initiated but not answered | > | `unanswered` | Call was not answered | > [accordion] Call Category Values > > | Category | Description | > | - | - | > | `call` | Direct call between users | > | `meet` | Meeting/conference call | > [accordion] Call Direction Values > > | Direction | Description | > | - | - | > | `incoming` | Call received by the user | > | `outgoing` | Call initiated by the user | ## Related Documentation * [Transcription](/docs/calls/ios/transcription) * [Recording](/docs/calls/ios/recording) # Custom Control Panel Source: https://www.cometchat.com/docs/calls/ios/custom-control-panel Customize the CometChat Calls SDK v5 control panel on iOS with call buttons, actions, layout, and user controls. Build a fully customized control panel for your call interface by hiding the default controls and implementing your own UI with call actions. This guide walks you through creating a custom control panel with essential call controls. ## Overview Custom control panels allow you to: * Match your app's branding and design language * Simplify the interface by showing only relevant controls * Add custom functionality and workflows * Create unique user experiences This guide demonstrates building a basic custom control panel with: * Mute/Unmute audio button * Pause/Resume video button * Switch camera button * End call button ## Prerequisites * CometChat Calls SDK installed and initialized * Active call session (see [Join Session](/docs/calls/ios/join-session)) * Familiarity with [Actions](/docs/calls/ios/actions) and [Events](/docs/calls/ios/events) *** ## Step 1: Hide Default Controls Configure your session settings to hide the default control panel: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .hideControlPanel(true) .build() ``` > [!NOTE] > > You can also hide individual buttons while keeping the control panel visible. See [SessionSettingsBuilder](/docs/calls/ios/session-settings) for all options. *** ## Step 2: Create Custom Layout Create a custom view for your controls programmatically or in Interface Builder: ```swift theme={null} class CallViewController: UIViewController { // Call container view private let callContainer = UIView() // Custom control panel private let controlPanel = UIStackView() private let btnToggleAudio = UIButton(type: .system) private let btnToggleVideo = UIButton(type: .system) private let btnSwitchCamera = UIButton(type: .system) private let btnEndCall = UIButton(type: .system) override func viewDidLoad() { super.viewDidLoad() setupUI() setupControlListeners() } private func setupUI() { view.backgroundColor = .black // Setup call container callContainer.translatesAutoresizingMaskIntoConstraints = false view.addSubview(callContainer) // Setup control panel controlPanel.axis = .horizontal controlPanel.distribution = .equalSpacing controlPanel.alignment = .center controlPanel.spacing = 20 controlPanel.translatesAutoresizingMaskIntoConstraints = false controlPanel.backgroundColor = UIColor.black.withAlphaComponent(0.8) controlPanel.layoutMargins = UIEdgeInsets(top: 16, left: 32, bottom: 16, right: 32) controlPanel.isLayoutMarginsRelativeArrangement = true view.addSubview(controlPanel) // Configure buttons configureButton(btnToggleAudio, imageName: "mic.fill", backgroundColor: .darkGray) configureButton(btnToggleVideo, imageName: "video.fill", backgroundColor: .darkGray) configureButton(btnSwitchCamera, imageName: "camera.rotate.fill", backgroundColor: .darkGray) configureButton(btnEndCall, imageName: "phone.down.fill", backgroundColor: .systemRed) // Add buttons to control panel controlPanel.addArrangedSubview(btnToggleAudio) controlPanel.addArrangedSubview(btnToggleVideo) controlPanel.addArrangedSubview(btnSwitchCamera) controlPanel.addArrangedSubview(btnEndCall) // Layout constraints NSLayoutConstraint.activate([ callContainer.topAnchor.constraint(equalTo: view.topAnchor), callContainer.leadingAnchor.constraint(equalTo: view.leadingAnchor), callContainer.trailingAnchor.constraint(equalTo: view.trailingAnchor), callContainer.bottomAnchor.constraint(equalTo: view.bottomAnchor), controlPanel.leadingAnchor.constraint(equalTo: view.leadingAnchor), controlPanel.trailingAnchor.constraint(equalTo: view.trailingAnchor), controlPanel.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor), controlPanel.heightAnchor.constraint(equalToConstant: 80) ]) } private func configureButton(_ button: UIButton, imageName: String, backgroundColor: UIColor) { button.setImage(UIImage(systemName: imageName), for: .normal) button.tintColor = .white button.backgroundColor = backgroundColor button.layer.cornerRadius = 28 button.translatesAutoresizingMaskIntoConstraints = false NSLayoutConstraint.activate([ button.widthAnchor.constraint(equalToConstant: 56), button.heightAnchor.constraint(equalToConstant: 56) ]) } } ``` *** ## Step 3: Implement Control Actions Set up button actions and call the appropriate SDK methods: ```swift theme={null} private var isAudioMuted = false private var isVideoPaused = false private func setupControlListeners() { btnToggleAudio.addTarget(self, action: #selector(toggleAudio), for: .touchUpInside) btnToggleVideo.addTarget(self, action: #selector(toggleVideo), for: .touchUpInside) btnSwitchCamera.addTarget(self, action: #selector(switchCamera), for: .touchUpInside) btnEndCall.addTarget(self, action: #selector(endCall), for: .touchUpInside) } @objc private func toggleAudio() { if isAudioMuted { CallSession.shared.unmuteAudio() } else { CallSession.shared.muteAudio() } } @objc private func toggleVideo() { if isVideoPaused { CallSession.shared.resumeVideo() } else { CallSession.shared.pauseVideo() } } @objc private func switchCamera() { CallSession.shared.switchCamera() } @objc private func endCall() { CallSession.shared.leave() navigationController?.popViewController(animated: true) } ``` *** ## Step 4: Handle State Updates Use `MediaEventsListener` to keep your UI synchronized with the actual call state. Register the listener in the `viewDidLoad` of the `CallViewController` from Step 2 (the code below replaces that method), and remove it when the screen goes away (`deinit` in Swift, `dealloc` in Objective-C): ```swift theme={null} // In CallViewController (Step 2): replaces its viewDidLoad. A Swift extension can't override viewDidLoad or declare deinit. override func viewDidLoad() { super.viewDidLoad() setupUI() setupControlListeners() CallSession.shared.addMediaEventsListener(self) } deinit { CallSession.shared.removeMediaEventsListener(self) } ``` ```swift theme={null} extension CallViewController: MediaEventsListener { func onAudioMuted() { DispatchQueue.main.async { self.isAudioMuted = true self.btnToggleAudio.setImage(UIImage(systemName: "mic.slash.fill"), for: .normal) } } func onAudioUnMuted() { DispatchQueue.main.async { self.isAudioMuted = false self.btnToggleAudio.setImage(UIImage(systemName: "mic.fill"), for: .normal) } } func onVideoPaused() { DispatchQueue.main.async { self.isVideoPaused = true self.btnToggleVideo.setImage(UIImage(systemName: "video.slash.fill"), for: .normal) } } func onVideoResumed() { DispatchQueue.main.async { self.isVideoPaused = false self.btnToggleVideo.setImage(UIImage(systemName: "video.fill"), for: .normal) } } // Other MediaEventsListener callbacks func onRecordingStarted() {} func onRecordingStopped() {} func onAudioModeChanged(audioMode: AudioMode) {} func onCameraFacingChanged(cameraFacing: CameraFacing) {} } ``` Use `SessionStatusListener` to handle session end events: ```swift theme={null} extension CallViewController: SessionStatusListener { func onSessionLeft() { DispatchQueue.main.async { self.navigationController?.popViewController(animated: true) } } func onConnectionClosed() { DispatchQueue.main.async { self.navigationController?.popViewController(animated: true) } } func onSessionJoined() {} func onSessionTimedOut() {} func onConnectionLost() {} func onConnectionRestored() {} } ``` # Custom Participant List Source: https://www.cometchat.com/docs/calls/ios/custom-participant-list Customize the CometChat Calls SDK v5 participant list on iOS with participant views, actions, status, and layout. Build a custom participant list UI that displays real-time participant information with full control over layout and interactions. This guide demonstrates how to hide the default participant list and create your own using participant events and actions. ## Overview The SDK provides participant data through events, allowing you to build custom UIs for: * Participant roster with search and filtering * Custom participant cards with role badges or metadata * Moderation dashboards with quick access to controls * Attendance tracking and engagement monitoring ## Prerequisites * CometChat Calls SDK installed and initialized * Active call session (see [Join Session](/docs/calls/ios/join-session)) * Basic understanding of UITableView or UICollectionView *** ## Step 1: Hide Default Participant List Configure session settings to hide the default participant list button: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .hideParticipantListButton(true) .build() ``` *** ## Step 2: Create Participant List Layout Create a custom view controller for displaying participants: ```swift theme={null} class ParticipantListViewController: UIViewController { private let tableView = UITableView() private let searchBar = UISearchBar() private var participants: [Participant] = [] private var filteredParticipants: [Participant] = [] /// Per-participant state the app maintains itself, keyed by `Participant.uid`, because /// `Participant` carries no such flags. Starts empty — anything that happened before this /// client joined is not recoverable. fileprivate var statuses: [String: ParticipantStatus] = [:] override func viewDidLoad() { super.viewDidLoad() setupUI() setupParticipantListener() } private func setupUI() { title = "Participants" view.backgroundColor = .systemBackground // Setup search bar searchBar.placeholder = "Search participants..." searchBar.delegate = self searchBar.translatesAutoresizingMaskIntoConstraints = false view.addSubview(searchBar) // Setup table view tableView.delegate = self tableView.dataSource = self tableView.register(ParticipantCell.self, forCellReuseIdentifier: "ParticipantCell") tableView.translatesAutoresizingMaskIntoConstraints = false view.addSubview(tableView) // Layout constraints NSLayoutConstraint.activate([ searchBar.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor), searchBar.leadingAnchor.constraint(equalTo: view.leadingAnchor), searchBar.trailingAnchor.constraint(equalTo: view.trailingAnchor), tableView.topAnchor.constraint(equalTo: searchBar.bottomAnchor), tableView.leadingAnchor.constraint(equalTo: view.leadingAnchor), tableView.trailingAnchor.constraint(equalTo: view.trailingAnchor), tableView.bottomAnchor.constraint(equalTo: view.bottomAnchor) ]) // Add close button navigationItem.rightBarButtonItem = UIBarButtonItem( barButtonSystemItem: .close, target: self, action: #selector(dismissView) ) } @objc private func dismissView() { dismiss(animated: true) } } ``` *** ## Step 3: Create Participant Cell Build a custom table view cell to display participant information. > [!WARNING] > > `Participant` carries **only** identity and timing fields — `uid`, `name`, `avatar`, `mid`, > `state`, `isJoined`, `joinedAt`, `leftAt`, `deviceID` and the `total*Minutes` counters. It has > **no** mute / video / screen-share / hand-raise / pin flags, and the SDK exposes no getter for > them. Accumulate that state in your own app from the [participant events](/docs/calls/ios/events), > as below. Because those events fire only on change, a client that joins mid-call cannot recover > state that was already in effect. ```swift theme={null} /// Per-participant state the app maintains itself, keyed by `Participant.uid`. struct ParticipantStatus { var isAudioMuted = false var isVideoPaused = false var isPresenting = false var isHandRaised = false var isPinned = false } class ParticipantCell: UITableViewCell { private let avatarImageView = UIImageView() private let nameLabel = UILabel() private let statusLabel = UILabel() private let muteButton = UIButton(type: .system) private let pinButton = UIButton(type: .system) var participant: Participant? var onMuteAction: ((Participant) -> Void)? var onPinAction: ((Participant) -> Void)? override init(style: UITableViewCell.CellStyle, reuseIdentifier: String?) { super.init(style: style, reuseIdentifier: reuseIdentifier) setupUI() } required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") } private func setupUI() { // Avatar avatarImageView.layer.cornerRadius = 20 avatarImageView.clipsToBounds = true avatarImageView.backgroundColor = .systemGray4 avatarImageView.translatesAutoresizingMaskIntoConstraints = false contentView.addSubview(avatarImageView) // Name label nameLabel.font = .systemFont(ofSize: 16, weight: .semibold) nameLabel.translatesAutoresizingMaskIntoConstraints = false contentView.addSubview(nameLabel) // Status label statusLabel.font = .systemFont(ofSize: 12) statusLabel.textColor = .secondaryLabel statusLabel.translatesAutoresizingMaskIntoConstraints = false contentView.addSubview(statusLabel) // Action buttons muteButton.setImage(UIImage(systemName: "mic.slash"), for: .normal) muteButton.addTarget(self, action: #selector(muteButtonTapped), for: .touchUpInside) muteButton.translatesAutoresizingMaskIntoConstraints = false contentView.addSubview(muteButton) pinButton.setImage(UIImage(systemName: "pin"), for: .normal) pinButton.addTarget(self, action: #selector(pinButtonTapped), for: .touchUpInside) pinButton.translatesAutoresizingMaskIntoConstraints = false contentView.addSubview(pinButton) // Layout NSLayoutConstraint.activate([ avatarImageView.leadingAnchor.constraint(equalTo: contentView.leadingAnchor, constant: 16), avatarImageView.centerYAnchor.constraint(equalTo: contentView.centerYAnchor), avatarImageView.widthAnchor.constraint(equalToConstant: 40), avatarImageView.heightAnchor.constraint(equalToConstant: 40), nameLabel.leadingAnchor.constraint(equalTo: avatarImageView.trailingAnchor, constant: 12), nameLabel.topAnchor.constraint(equalTo: contentView.topAnchor, constant: 12), statusLabel.leadingAnchor.constraint(equalTo: nameLabel.leadingAnchor), statusLabel.topAnchor.constraint(equalTo: nameLabel.bottomAnchor, constant: 4), statusLabel.bottomAnchor.constraint(equalTo: contentView.bottomAnchor, constant: -12), pinButton.trailingAnchor.constraint(equalTo: contentView.trailingAnchor, constant: -16), pinButton.centerYAnchor.constraint(equalTo: contentView.centerYAnchor), pinButton.widthAnchor.constraint(equalToConstant: 32), muteButton.trailingAnchor.constraint(equalTo: pinButton.leadingAnchor, constant: -8), muteButton.centerYAnchor.constraint(equalTo: contentView.centerYAnchor), muteButton.widthAnchor.constraint(equalToConstant: 32) ]) } func configure(with participant: Participant, status: ParticipantStatus) { self.participant = participant nameLabel.text = participant.name // Build status text from the app's own state, not from `participant`. var statusParts: [String] = [] if status.isAudioMuted { statusParts.append("🔇 Muted") } if status.isVideoPaused { statusParts.append("📹 Video Off") } if status.isPresenting { statusParts.append("🖥️ Presenting") } if status.isHandRaised { statusParts.append("✋ Hand Raised") } if status.isPinned { statusParts.append("📌 Pinned") } statusLabel.text = statusParts.isEmpty ? "Active" : statusParts.joined(separator: " • ") // Update button states muteButton.alpha = status.isAudioMuted ? 0.5 : 1.0 pinButton.tintColor = status.isPinned ? .systemBlue : .systemGray } @objc private func muteButtonTapped() { guard let participant = participant else { return } onMuteAction?(participant) } @objc private func pinButtonTapped() { guard let participant = participant else { return } onPinAction?(participant) } } ``` *** ## Step 4: Implement Participant Events Listen for participant updates and handle actions: ```swift theme={null} extension ParticipantListViewController: ParticipantEventListener { private func setupParticipantListener() { CallSession.shared.addParticipantEventListener(self) } deinit { CallSession.shared.removeParticipantEventListener(self) } func onParticipantListChanged(participants: [Participant]) { DispatchQueue.main.async { self.participants = participants self.filteredParticipants = participants self.title = "Participants (\(participants.count))" self.tableView.reloadData() } } func onParticipantJoined(participant: Participant) { print("\(participant.name ?? "") joined") } func onParticipantLeft(participant: Participant) { guard let uid = participant.uid else { return } DispatchQueue.main.async { self.statuses.removeValue(forKey: uid) // don't leak state for someone who left self.tableView.reloadData() } } // `onParticipantListChanged` carries no flags, so every status below comes from these // transition events. Each one mutates the app's own `statuses` map and redraws. func onParticipantAudioMuted(participant: Participant) { update(participant) { $0.isAudioMuted = true } } func onParticipantAudioUnmuted(participant: Participant) { update(participant) { $0.isAudioMuted = false } } func onParticipantVideoPaused(participant: Participant) { update(participant) { $0.isVideoPaused = true } } func onParticipantVideoResumed(participant: Participant) { update(participant) { $0.isVideoPaused = false } } func onParticipantHandRaised(participant: Participant) { update(participant) { $0.isHandRaised = true } } func onParticipantHandLowered(participant: Participant) { update(participant) { $0.isHandRaised = false } } func onParticipantStartedScreenShare(participant: Participant) { update(participant) { $0.isPresenting = true } } func onParticipantStoppedScreenShare(participant: Participant) { update(participant) { $0.isPresenting = false } } private func update(_ participant: Participant, _ change: @escaping (inout ParticipantStatus) -> Void) { guard let uid = participant.uid else { return } DispatchQueue.main.async { var status = self.statuses[uid] ?? ParticipantStatus() change(&status) self.statuses[uid] = status self.tableView.reloadData() } } } ``` *** ## Step 5: Implement Table View Data Source ```swift theme={null} extension ParticipantListViewController: UITableViewDelegate, UITableViewDataSource { func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int { return filteredParticipants.count } func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell { let cell = tableView.dequeueReusableCell(withIdentifier: "ParticipantCell", for: indexPath) as! ParticipantCell let participant = filteredParticipants[indexPath.row] let status = participant.uid.flatMap { statuses[$0] } ?? ParticipantStatus() cell.configure(with: participant, status: status) cell.onMuteAction = { participant in guard let uid = participant.uid else { return } CallSession.shared.muteParticipant(participantId: uid) } cell.onPinAction = { [weak self] participant in guard let self, let uid = participant.uid else { return } if self.statuses[uid]?.isPinned == true { CallSession.shared.unpinParticipant() self.statuses[uid]?.isPinned = false } else { // Only one participant can be pinned at a time — `unpinParticipant()` takes no id. for key in Array(self.statuses.keys) { self.statuses[key]?.isPinned = false } CallSession.shared.pinParticipant(participantId: uid, type: "pin") self.statuses[uid, default: ParticipantStatus()].isPinned = true } self.tableView.reloadData() } return cell } } extension ParticipantListViewController: UISearchBarDelegate { func searchBar(_ searchBar: UISearchBar, textDidChange searchText: String) { if searchText.isEmpty { filteredParticipants = participants } else { filteredParticipants = participants.filter { ($0.name ?? "").localizedCaseInsensitiveContains(searchText) } } tableView.reloadData() } } ``` *** ## Step 6: Present Participant List Show the participant list from your call view controller: ```swift theme={null} class CallViewController: UIViewController { private let participantListButton = UIButton(type: .system) private func setupParticipantListButton() { participantListButton.setImage(UIImage(systemName: "person.3"), for: .normal) participantListButton.addTarget(self, action: #selector(showParticipantList), for: .touchUpInside) // Add to your view hierarchy } @objc private func showParticipantList() { let participantListVC = ParticipantListViewController() let navController = UINavigationController(rootViewController: participantListVC) navController.modalPresentationStyle = .pageSheet if let sheet = navController.sheetPresentationController { sheet.detents = [.medium(), .large()] sheet.prefersGrabberVisible = true } present(navController, animated: true) } } ``` *** ## Related Documentation * [Participant Management](/docs/calls/ios/participant-management) - Participant actions and events * [Events](/docs/calls/ios/events) - All available event listeners * [Actions](/docs/calls/ios/actions) - Available call actions # Events Source: https://www.cometchat.com/docs/calls/ios/events Handle CometChat Calls SDK v5 events on iOS for call lifecycle, participants, media state, errors, and real-time updates. Handle call session events to build responsive UIs. The SDK provides five session listener protocols to monitor session status, participant activities, media changes, button clicks, and layout changes, plus two global listeners for incoming calls and login state. The SDK holds every listener weakly and removes none of them for you, so keep a strong reference to each listener object and remove it when your screen goes away. ## Get CallSession Instance The `CallSession` is a singleton that manages the active call. All event listener registrations and session control methods are accessed through this instance. ```swift theme={null} let callSession = CallSession.shared ``` `CallSession.shared` always exists, so listeners registered on it work before any session does. To ask whether there is a session right now, use `CometChatCalls.getActiveSession()`: ```swift theme={null} // nil when no session is prepared or joined if let session = CometChatCalls.getActiveSession() { print("Live session \(session.sessionId ?? "")") } ``` `getActiveSession()` returns `CallSession.shared` as soon as a session is **prepared**, which is what `CometChatCalls.initiateCall` does on the caller and what the Push SDK's ring does on the callee, before anyone joins. That is what lets a caller listen for "ringing" and "answered" without joining (see [Ringing](/docs/calls/ios/ringing)). Before a session is prepared or joined it returns nil, so code that registers through it (`getActiveSession()?.addSessionStatusListener(self)`) registers nothing; register on `CallSession.shared` instead. > [!NOTE] > > `CallSession` holds listeners **weakly**. It does not keep your listener alive, so the object you register must be owned elsewhere, such as the view controller itself (as in the examples below) or a stored property. A listener created inline, like `addSessionStatusListener(MyListener())`, is deallocated right away and never receives an event. A deallocated listener is dropped automatically. Call `removeSessionStatusListener`, `removeParticipantEventListener`, etc. when you want events to stop before the listener goes away. *** ## Session Events Monitor the call session lifecycle including join/leave events and connection status. ```swift theme={null} class CallViewController: UIViewController, SessionStatusListener { override func viewDidLoad() { super.viewDidLoad() CallSession.shared.addSessionStatusListener(self) } deinit { CallSession.shared.removeSessionStatusListener(self) } func onConnected() { // A prepared session is connected (signalling only): the join will be near-instant } func onSessionJoined() { // Successfully connected to the session } func onSessionLeft() { // Left the session navigationController?.popViewController(animated: true) } func onSessionTimedOut() { // Session ended due to inactivity navigationController?.popViewController(animated: true) } func onConnectionLost() { // Network interrupted, attempting reconnection } func onConnectionRestored() { // Connection restored after being lost } func onConnectionClosed() { // Connection permanently closed. On a session that was only prepared // (an outgoing call still ringing), this means the call ended before anyone joined. navigationController?.popViewController(animated: true) } } ``` | Event | Description | | - | - | | `onConnected()` | A prepared session connected: signalling only, no media, and other participants do not see you yet. Fires once per prepare (`initiateCall` on the caller, the Push SDK's ring on the callee); the media join is `onSessionJoined()` | | `onSessionJoined()` | Successfully connected and joined the session | | `onSessionLeft()` | Left the session via `leave()` or was removed | | `onSessionTimedOut()` | Session ended due to inactivity timeout. Not used on a prepared session: one nobody joins within 5 minutes reports `onConnectionClosed()` | | `onConnectionLost()` | Network interrupted, SDK attempting reconnection | | `onConnectionRestored()` | Connection restored after being lost | | `onConnectionClosed()` | Connection permanently closed, cannot reconnect. On a prepared session: it closed before anyone joined (a decline or ring-out when the callee's device had prepared it, a cancel, the room going away, or nobody joining within 5 minutes). A busy decline doesn't close it | *** ## Participant Events Monitor participant activities including join/leave, audio/video state, hand raise, screen sharing, and recording. ```swift theme={null} class CallViewController: UIViewController, ParticipantEventListener { override func viewDidLoad() { super.viewDidLoad() CallSession.shared.addParticipantEventListener(self) } deinit { CallSession.shared.removeParticipantEventListener(self) } func onParticipantConnected(participant: Participant) { // A participant's device prepared the session but has not joined yet. // On an outgoing call: the callee's phone is ringing. } func onParticipantJoined(participant: Participant) { // A participant joined the call. On an outgoing call: the callee answered. } func onParticipantLeft(participant: Participant) { // A participant left the call } func onParticipantListChanged(participants: [Participant]) { // Participant list updated } func onParticipantAudioMuted(participant: Participant) {} func onParticipantAudioUnmuted(participant: Participant) {} func onParticipantVideoPaused(participant: Participant) {} func onParticipantVideoResumed(participant: Participant) {} func onParticipantHandRaised(participant: Participant) {} func onParticipantHandLowered(participant: Participant) {} func onParticipantStartedScreenShare(participant: Participant) {} func onParticipantStoppedScreenShare(participant: Participant) {} func onParticipantStartedRecording(participant: Participant) {} func onParticipantStoppedRecording(participant: Participant) {} func onDominantSpeakerChanged(participant: Participant) {} } ``` | Event | Parameter | Description | | - | - | - | | `onParticipantConnected` | `Participant` | A remote participant's device prepared the session without joining. On the caller's prepared session this is the callee ringing | | `onParticipantJoined` | `Participant` | A participant joined the call. On the caller's prepared session this is the callee answering: join now | | `onParticipantLeft` | `Participant` | A participant disconnected from the call | | `onParticipantListChanged` | `[Participant]` | Participant list updated | | `onParticipantAudioMuted` | `Participant` | A participant muted their microphone | | `onParticipantAudioUnmuted` | `Participant` | A participant unmuted their microphone | | `onParticipantVideoPaused` | `Participant` | A participant turned off their camera | | `onParticipantVideoResumed` | `Participant` | A participant turned on their camera | | `onParticipantHandRaised` | `Participant` | A participant raised their hand | | `onParticipantHandLowered` | `Participant` | A participant lowered their hand | | `onParticipantStartedScreenShare` | `Participant` | A participant started screen sharing | | `onParticipantStoppedScreenShare` | `Participant` | A participant stopped screen sharing | | `onParticipantStartedRecording` | `Participant` | A participant started recording | | `onParticipantStoppedRecording` | `Participant` | A participant stopped recording | | `onDominantSpeakerChanged` | `Participant` | The active speaker changed | *** ## Media Events Monitor your local media state changes including audio/video status, recording, and device changes. ```swift theme={null} class CallViewController: UIViewController, MediaEventsListener { override func viewDidLoad() { super.viewDidLoad() CallSession.shared.addMediaEventsListener(self) } deinit { CallSession.shared.removeMediaEventsListener(self) } func onAudioMuted() { // Your microphone was muted } func onAudioUnMuted() { // Your microphone was unmuted } func onVideoPaused() { // Your camera was turned off } func onVideoResumed() { // Your camera was turned on } func onRecordingStarted() { // Call recording started } func onRecordingStopped() { // Call recording stopped } func onAudioModeChanged(audioMode: AudioMode) { // Audio output device changed } func onCameraFacingChanged(cameraFacing: CameraFacing) { // Camera switched between front and back } } ``` | Event | Parameter | Description | | - | - | - | | `onAudioMuted` | - | Your microphone was muted | | `onAudioUnMuted` | - | Your microphone was unmuted | | `onVideoPaused` | - | Your camera was turned off | | `onVideoResumed` | - | Your camera was turned on | | `onRecordingStarted` | - | Call recording started | | `onRecordingStopped` | - | Call recording stopped | | `onAudioModeChanged` | `AudioMode` | Audio output device changed | | `onCameraFacingChanged` | `CameraFacing` | Camera switched between front and back | > [!NOTE] > > `MediaEventsListener` has **no** screen-share callback. Screen sharing is observed on > [`ParticipantEventListener`](#participant-events) via `onParticipantStartedScreenShare` / > `onParticipantStoppedScreenShare` — and on iOS those are **receive-only**: the SDK reports a share > started from another client, but has no API to start one locally. > [accordion] AudioMode Values > > | Value | Description | > | - | - | > | `.speaker` | Audio routed through device loudspeaker | > | `.earpiece` | Audio routed through phone earpiece | > | `.bluetooth` | Audio routed through connected Bluetooth device | > | `.headphones` | Audio routed through wired headphones | > [accordion] CameraFacing Values > > | Value | Description | > | - | - | > | `.FRONT` | Front-facing (selfie) camera is active | > | `.REAR` | Rear-facing (main) camera is active | *** ## Button Click Events Intercept UI button clicks from the default call interface to add custom behavior or analytics. ```swift theme={null} class CallViewController: UIViewController, ButtonClickListener { override func viewDidLoad() { super.viewDidLoad() CallSession.shared.addButtonClickListener(self) } deinit { CallSession.shared.removeButtonClickListener(self) } func onLeaveSessionButtonClicked() { // Leave button tapped } func onToggleAudioButtonClicked() { // Mute/unmute button tapped } func onToggleVideoButtonClicked() { // Video on/off button tapped } func onSwitchCameraButtonClicked() {} func onRaiseHandButtonClicked() {} func onShareInviteButtonClicked() {} func onChangeLayoutButtonClicked() {} func onParticipantListButtonClicked() {} func onChatButtonClicked() {} func onRecordingToggleButtonClicked() {} } ``` | Event | Description | | - | - | | `onLeaveSessionButtonClicked` | Leave/end call button was tapped | | `onToggleAudioButtonClicked` | Mute/unmute button was tapped | | `onToggleVideoButtonClicked` | Video on/off button was tapped | | `onSwitchCameraButtonClicked` | Camera switch button was tapped | | `onRaiseHandButtonClicked` | Raise hand button was tapped | | `onShareInviteButtonClicked` | Share/invite button was tapped | | `onChangeLayoutButtonClicked` | Layout change button was tapped | | `onParticipantListButtonClicked` | Participant list button was tapped | | `onChatButtonClicked` | In-call chat button was tapped | | `onRecordingToggleButtonClicked` | Recording toggle button was tapped | > [!NOTE] > > Button click events fire before the SDK's default action executes. Use these to add custom logic alongside default behavior. The Leave button is the exception: the SDK leaves the session itself when it is tapped, so only clean up in `onLeaveSessionButtonClicked`. *** ## Layout Events Monitor layout changes including layout type switches and Picture-in-Picture mode transitions. ```swift theme={null} class CallViewController: UIViewController, LayoutListener { override func viewDidLoad() { super.viewDidLoad() CallSession.shared.addLayoutListener(self) } deinit { CallSession.shared.removeLayoutListener(self) } func onCallLayoutChanged(layoutType: LayoutType) { // Layout changed (TILE, SPOTLIGHT) } func onParticipantListVisible() { // Participant list panel opened } func onParticipantListHidden() { // Participant list panel closed } func onPictureInPictureLayoutEnabled() { // Entered PiP mode } func onPictureInPictureLayoutDisabled() { // Exited PiP mode } } ``` | Event | Parameter | Description | | - | - | - | | `onCallLayoutChanged` | `LayoutType` | Call layout changed | | `onParticipantListVisible` | - | Participant list panel was opened | | `onParticipantListHidden` | - | Participant list panel was closed | | `onPictureInPictureLayoutEnabled` | - | Call entered Picture-in-Picture mode | | `onPictureInPictureLayoutDisabled` | - | Call exited Picture-in-Picture mode | > [accordion] LayoutType Values > > | Value | Description | Best For | > | - | - | - | > | `.tile` | Grid layout with equally-sized tiles | Group discussions, team meetings | > | `.spotlight` | Large view for active speaker, small tiles for others | Presentations, one-on-one calls | *** ## Clear All Listeners Remove all registered listeners at once. Useful when cleaning up resources. ```swift theme={null} CallSession.shared.clearAllListeners() ``` *** ## Incoming Call Events `CometChatCalls.addIncomingCallListener` is a global listener, not tied to a session. It reports a call ringing on this device and the end of that ring, whether the call arrived by VoIP push while the app was killed or while it was running. The Push Notifications SDK feeds it; it reports incoming calls only, not the end of your own outgoing call. ```swift theme={null} final class CallEvents: NSObject, CometChatIncomingCallListener { func onIncomingCallReceived(call: CometChatIncomingCall) { // A call for this user is ringing (CallKit already shows it) } func onIncomingCallEnded(call: CometChatIncomingCall, reason: String) { // The ring ended: "cancelled", "ongoing", "unanswered", "rejected", "busy", "ended" } } let callEvents = CallEvents() // held weakly by the SDK: keep this reference CometChatCalls.addIncomingCallListener("my-screen", callEvents) CometChatCalls.removeIncomingCallListener("my-screen") ``` | Event | Parameters | Description | | - | - | - | | `onIncomingCallReceived` | `CometChatIncomingCall` | A call for the logged-in user is ringing on this device | | `onIncomingCallEnded` | `CometChatIncomingCall`, `reason` | The call ended before it was answered here, once per call: `cancelled` (the caller gave up), `ongoing` (answered on another device), `unanswered`, `rejected` / `busy`, or `ended` (the session prepared for it closed before the answer). Treat any other reason as "the ring is over". A decline or ring-out on this device is reported to the Push SDK delegate's `callDidEnd(_:reason:)` instead | `CometChatIncomingCall` carries `sessionId`, `callerUid`, `callerName`, `callerAvatarUrl`, `callType`, `receiverType`, `receiverUid`, `conversationId`, `initiatedAt` (milliseconds), `isVideo` and `isPeerCall`. > [!NOTE] > > Listener ids are keys: registering the same id twice replaces the earlier listener. Do not use the id `cometchat-push-notifications`, which the Push SDK registers under. *** ## Login Events `CometChatCalls.addLoginListener` reports the Calls SDK login state. The Push SDK uses it to register and unregister the push tokens and to stop a ring when the user logs out; your app can use it to gate call UI. ```swift theme={null} import CometChatCallsSDK // Qualify the protocol if your app also imports the Chat SDK, which has its own CometChatLoginDelegate. final class CallsLoginEvents: NSObject, CometChatCallsSDK.CometChatLoginDelegate { func onLoginSuccess(user: CallsUser) {} func onLoginFailed(error: CometChatCallException?) {} func onLogoutSuccess() {} func onLogoutFailed(error: CometChatCallException?) {} } let loginEvents = CallsLoginEvents() // held weakly by the SDK: keep this reference CometChatCalls.addLoginListener("my-app", loginEvents) CometChatCalls.removeLoginListener("my-app") ``` | Event | Description | | - | - | | `onLoginSuccess(user:)` | A user logged in to the Calls SDK | | `onLoginFailed(error:)` | A login failed | | `onLogoutSuccess()` | The user logged out | | `onLogoutFailed(error:)` | A logout failed | > [!NOTE] > > Login listener ids are keys too: registering the same id twice replaces the earlier listener. Do not use the id `cometchat-push-notifications-calls`, which the Push SDK registers under. # Idle Timeout Source: https://www.cometchat.com/docs/calls/ios/idle-timeout Configure CometChat Calls SDK v5 idle timeout on iOS to handle inactive participants and call session cleanup. Configure automatic session termination when a user is alone in a call. Idle timeout helps manage resources by ending sessions that have no active participants. ## How Idle Timeout Works When a user is the only participant in a call session, the idle timeout countdown begins. If no other participant joins before the timeout expires, the session automatically ends and the `onSessionTimedOut` callback is triggered. The timer also restarts when other participants leave and only one user remains in the call. ```mermaid theme={null} flowchart LR A[Alone in call] --> B[Timer starts] B --> C{Participant joins?} C -->|Yes| D[Timer stops] C -->|No, timeout| E[Session ends] D -->|Participant leaves| A ``` This is useful for: * Preventing abandoned call sessions from running indefinitely * Managing server resources efficiently * Providing a better user experience when the other party doesn't join ## Configure Idle Timeout Set the idle timeout period using `setIdleTimeoutPeriod()` in `SessionSettingsBuilder`. The value is in seconds. ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .setIdleTimeoutPeriod(120) // 2 minutes .setSessionType(.video) .build() CometChatCalls.joinSession( sessionID: sessionId, callSetting: sessionSettings, container: callViewContainer, onSuccess: { message in print("Joined session") }, onError: { error in print("Failed: \(error?.errorDescription ?? "")") } ) ``` | Parameter | Type | Default | Description | | - | - | - | - | | `idleTimeoutPeriod` | Int | 300 | Timeout in seconds when alone in the session | ## Handle Session Timeout Listen for the `onSessionTimedOut` callback using `SessionStatusListener` to handle when the session ends due to idle timeout: ```swift theme={null} class CallViewController: UIViewController, SessionStatusListener { override func viewDidLoad() { super.viewDidLoad() CallSession.shared.addSessionStatusListener(self) } deinit { CallSession.shared.removeSessionStatusListener(self) } func onSessionTimedOut() { print("Session ended due to idle timeout") // Show message to user showToast("Call ended - no other participants joined") // Navigate away from call screen navigationController?.popViewController(animated: true) } func onSessionJoined() {} func onSessionLeft() {} func onConnectionLost() {} func onConnectionRestored() {} func onConnectionClosed() {} } ``` ## Disable Idle Timeout To disable idle timeout and allow sessions to run indefinitely, set a value of `0`: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .setIdleTimeoutPeriod(0) // Disable idle timeout .build() ``` > [!WARNING] > > Disabling idle timeout may result in sessions running indefinitely if participants don't join or leave properly. Use with caution. # In-Call Chat Source: https://www.cometchat.com/docs/calls/ios/in-call-chat Enable in-call chat in CometChat Calls SDK v5 on iOS so participants can send messages during active calls. Add real-time messaging to your call experience using CometChat UI Kit. This allows participants to send text messages, share files, and communicate via chat while on a call. ## Overview In-call chat creates a group conversation linked to the call session. When participants tap the chat button, they can: * Send and receive text messages * Share images, files, and media * See message history from the current call * Get unread message notifications via badge count ```mermaid theme={null} flowchart LR subgraph "Call Session" A[Call UI] --> B[Chat Button] B --> C[Chat VC] end subgraph "CometChat" D[Group] --> E[Messages] end C <--> D A -->|Session ID = Group GUID| D ``` ## Prerequisites * CometChat Calls SDK integrated ([Setup](/docs/calls/ios/setup)) * CometChat Chat SDK integrated ([Chat SDK](/docs/sdk/ios/overview)) * CometChat UI Kit integrated ([UI Kit](/docs/ui-kit/ios/overview)) > [!NOTE] > > The Chat SDK and UI Kit are separate from the Calls SDK. You'll need to add both dependencies to your project. *** ## Step 1: Add UI Kit Dependency Add the CometChat UI Kit to your project via Swift Package Manager or CocoaPods: **Swift Package Manager:** ``` https://github.com/cometchat/cometchat-chat-uikit-ios ``` **CocoaPods:** ```ruby theme={null} pod 'CometChatUIKitSwift', '~> 4.0' ``` *** ## Step 2: Enable Chat Button Configure session settings to show the chat button: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .hideChatButton(false) // Show the chat button .build() ``` *** ## Step 3: Create Chat Group Create or join a CometChat group using the session ID as the group GUID. This links the chat to the specific call session. ```swift theme={null} private func setupChatGroup(sessionId: String, meetingName: String) { // Try to get existing group first CometChat.getGroup(GUID: sessionId) { group in if !group.hasJoined { self.joinGroup(guid: sessionId, groupType: group.groupType) } else { print("Already joined group: \(group.name ?? "")") } } onError: { error in if error?.errorCode == "ERR_GUID_NOT_FOUND" { // Group doesn't exist, create it self.createGroup(guid: sessionId, name: meetingName) } else { print("Error getting group: \(error?.errorDescription ?? "")") } } } private func createGroup(guid: String, name: String) { let group = Group(guid: guid, name: name, groupType: .public, password: nil) CometChat.createGroup(group: group) { createdGroup in print("Group created: \(createdGroup.name ?? "")") } onError: { error in print("Group creation failed: \(error?.errorDescription ?? "")") } } private func joinGroup(guid: String, groupType: CometChat.groupType) { CometChat.joinGroup(GUID: guid, groupType: groupType, password: nil) { joinedGroup in print("Joined group: \(joinedGroup.name ?? "")") } onError: { error in print("Join group failed: \(error?.errorDescription ?? "")") } } ``` *** ## Step 4: Handle Chat Button Click Listen for the chat button click and open your chat view controller: ```swift theme={null} private var unreadMessageCount = 0 private func setupChatButtonListener() { CallSession.shared.addButtonClickListener(self) } extension CallViewController: ButtonClickListener { func onChatButtonClicked() { // Reset unread count when opening chat unreadMessageCount = 0 CallSession.shared.setChatButtonUnreadCount(0) // Open chat view controller let chatVC = ChatViewController() chatVC.sessionId = sessionId chatVC.meetingName = meetingName let navController = UINavigationController(rootViewController: chatVC) navController.modalPresentationStyle = .pageSheet if let sheet = navController.sheetPresentationController { sheet.detents = [.medium(), .large()] sheet.prefersGrabberVisible = true } present(navController, animated: true) } } ``` *** ## Step 5: Track Unread Messages Listen for incoming messages and update the badge count on the chat button: ```swift theme={null} private func setupMessageListener() { CometChat.addMessageListener("CallChatListener", self) } extension CallViewController: CometChatMessageDelegate { func onTextMessageReceived(textMessage: TextMessage) { // Check if message is for our call's group if let receiver = textMessage.receiver as? Group, receiver.guid == sessionId { unreadMessageCount += 1 CallSession.shared.setChatButtonUnreadCount(unreadMessageCount) } } func onMediaMessageReceived(mediaMessage: MediaMessage) { if let receiver = mediaMessage.receiver as? Group, receiver.guid == sessionId { unreadMessageCount += 1 CallSession.shared.setChatButtonUnreadCount(unreadMessageCount) } } } deinit { CometChat.removeMessageListener("CallChatListener") } ``` *** ## Step 6: Create Chat View Controller Create a chat view controller using UI Kit components: ```swift theme={null} import CometChatUIKitSwift class ChatViewController: UIViewController { var sessionId: String = "" var meetingName: String = "" private let messageList = CometChatMessageList() private let messageComposer = CometChatMessageComposer() private let activityIndicator = UIActivityIndicatorView(style: .large) override func viewDidLoad() { super.viewDidLoad() setupUI() loadGroup() } private func setupUI() { view.backgroundColor = .systemBackground title = meetingName navigationItem.rightBarButtonItem = UIBarButtonItem( barButtonSystemItem: .close, target: self, action: #selector(dismissView) ) // Setup message list messageList.translatesAutoresizingMaskIntoConstraints = false view.addSubview(messageList) // Setup message composer messageComposer.translatesAutoresizingMaskIntoConstraints = false view.addSubview(messageComposer) // Setup activity indicator activityIndicator.translatesAutoresizingMaskIntoConstraints = false activityIndicator.hidesWhenStopped = true view.addSubview(activityIndicator) NSLayoutConstraint.activate([ messageList.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor), messageList.leadingAnchor.constraint(equalTo: view.leadingAnchor), messageList.trailingAnchor.constraint(equalTo: view.trailingAnchor), messageList.bottomAnchor.constraint(equalTo: messageComposer.topAnchor), messageComposer.leadingAnchor.constraint(equalTo: view.leadingAnchor), messageComposer.trailingAnchor.constraint(equalTo: view.trailingAnchor), messageComposer.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor), activityIndicator.centerXAnchor.constraint(equalTo: view.centerXAnchor), activityIndicator.centerYAnchor.constraint(equalTo: view.centerYAnchor) ]) } @objc private func dismissView() { dismiss(animated: true) } private func loadGroup() { activityIndicator.startAnimating() CometChat.getGroup(GUID: sessionId) { [weak self] group in guard let self = self else { return } if !group.hasJoined { self.joinAndSetGroup(guid: self.sessionId, groupType: group.groupType) } else { self.setGroup(group) } } onError: { [weak self] error in guard let self = self else { return } if error?.errorCode == "ERR_GUID_NOT_FOUND" { self.createAndSetGroup() } else { self.activityIndicator.stopAnimating() print("Error: \(error?.errorDescription ?? "")") } } } private func createAndSetGroup() { let group = Group(guid: sessionId, name: meetingName, groupType: .public, password: nil) CometChat.createGroup(group: group) { [weak self] createdGroup in self?.setGroup(createdGroup) } onError: { [weak self] error in self?.activityIndicator.stopAnimating() } } private func joinAndSetGroup(guid: String, groupType: CometChat.groupType) { CometChat.joinGroup(GUID: guid, groupType: groupType, password: nil) { [weak self] joinedGroup in self?.setGroup(joinedGroup) } onError: { [weak self] error in self?.activityIndicator.stopAnimating() } } private func setGroup(_ group: Group) { activityIndicator.stopAnimating() messageList.set(group: group) messageComposer.set(group: group) } } ``` *** ## Related Documentation * [UI Kit Overview](/docs/ui-kit/ios/overview) - CometChat UI Kit components * [Events](/docs/calls/ios/events) - Button click events * [Session Settings](/docs/calls/ios/session-settings) - Configure chat button visibility # Join Session Source: https://www.cometchat.com/docs/calls/ios/join-session Join CometChat Calls SDK v5 sessions on iOS with session IDs, call tokens, participant setup, and in-call UI launch. Join a call session using one of two approaches: the quick start method with a session ID, or the advanced flow with manual token generation for more control. ## Overview The CometChat Calls SDK provides two ways to join a session: | Approach | Best For | Complexity | | - | - | - | | **Join with Session ID** | Most use cases - simple and straightforward | Low - One method call | | **Join with Token** | Custom token management, pre-generation, caching | Medium - Two-step process | > [!NOTE] > > Both approaches require a container view in your layout and properly configured [SessionSettings](/docs/calls/ios/session-settings). ## Container Setup Create a container view where the call interface will be rendered. This can be done in your storyboard or programmatically: > [tab] Swift > > ```swift theme={null} > // Programmatically > let callViewContainer = UIView() > callViewContainer.translatesAutoresizingMaskIntoConstraints = false > view.addSubview(callViewContainer) > > NSLayoutConstraint.activate([ > callViewContainer.topAnchor.constraint(equalTo: view.topAnchor), > callViewContainer.bottomAnchor.constraint(equalTo: view.bottomAnchor), > callViewContainer.leadingAnchor.constraint(equalTo: view.leadingAnchor), > callViewContainer.trailingAnchor.constraint(equalTo: view.trailingAnchor) > ]) > ``` > [tab] Storyboard > > Add a `UIView` to your view controller and create an `@IBOutlet`: > > ```swift theme={null} > @IBOutlet weak var callViewContainer: UIView! > ``` The call UI will be dynamically added to this container when you join the session. ## Join with Session ID The simplest way to join a session. Pass a session ID and the SDK automatically generates the token and joins the call. ```swift theme={null} let sessionId = "SESSION_ID" let sessionSettings = CometChatCalls.sessionSettingsBuilder .setDisplayName("John Doe") .setSessionType(.video) .build() CometChatCalls.joinSession( sessionID: sessionId, callSetting: sessionSettings, container: callViewContainer, onSuccess: { message in print("Joined session successfully") }, onError: { error in print("Failed: \(error?.errorDescription ?? "")") } ) ``` | Parameter | Type | Description | | - | - | - | | `sessionID` | String | Unique identifier for the call session | | `callSetting` | SessionSettings | Configuration for the session | | `container` | UIView | Container view for the call UI | | `onSuccess` | Closure | Closure called on successful join | | `onError` | Closure | Closure called on failure | > [!NOTE] > > All participants joining the same call must use the same session ID. ## Join with Token For scenarios requiring more control over token generation, such as pre-generating tokens, implementing custom caching strategies, or managing token lifecycle separately. **Step 1: Generate Token** Generate a call token for the session. Each token is unique to a specific session and user combination. ```swift theme={null} let sessionId = "SESSION_ID" CometChatCalls.generateToken(sessionID: sessionId, onSuccess: { token in print("Token generated: \(token ?? "")") // Store or use the token }, onError: { error in print("Token generation failed: \(error?.errorDescription ?? "")") }) ``` | Parameter | Type | Description | | - | - | - | | `sessionID` | String | Unique identifier for the call session | | `onSuccess` | Closure | Closure returning the generated token string | | `onError` | Closure | Closure called on failure | **Step 2: Join with Token** Use the generated token to join the session. This gives you control over when and how the token is used. ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .setDisplayName("John Doe") .setSessionType(.video) .build() // Use the previously generated token CometChatCalls.joinSession( callToken: generatedToken, callSetting: sessionSettings, container: callViewContainer, onSuccess: { message in print("Joined session successfully") }, onError: { error in print("Failed: \(error?.errorDescription ?? "")") } ) ``` | Parameter | Type | Description | | - | - | - | | `callToken` | String | Previously generated token string | | `callSetting` | SessionSettings | Configuration for the session | | `container` | UIView | Container view for the call UI | | `onSuccess` | Closure | Closure called on successful join | | `onError` | Closure | Closure called on failure | **Complete Example** ```swift theme={null} let sessionId = "SESSION_ID" // Step 1: Generate token CometChatCalls.generateToken(sessionID: sessionId, onSuccess: { [weak self] token in guard let self = self, let token = token else { return } // Step 2: Join with token let sessionSettings = CometChatCalls.sessionSettingsBuilder .setDisplayName("John Doe") .setSessionType(.video) .build() CometChatCalls.joinSession( callToken: token, callSetting: sessionSettings, container: self.callViewContainer, onSuccess: { message in print("Joined session successfully") }, onError: { error in print("Failed to join: \(error?.errorDescription ?? "")") } ) }, onError: { error in print("Token generation failed: \(error?.errorDescription ?? "")") }) ``` ## Error Handling Common errors when joining a session: | Error Code | Description | | - | - | | `INIT ERROR` | SDK not initialized - call `init()` first | | `AUTH TOKEN ERROR` | User not logged in or auth token invalid | | `SESSION ID ERROR` | Session ID is null or empty | | `API ERROR` | Invalid call token or API error | # Changelog Source: https://www.cometchat.com/docs/calls/ios/link/changelog Navigate to Changelog documentation. # GitHub Source: https://www.cometchat.com/docs/calls/ios/link/github Navigate to GitHub documentation. # Sample Apps Source: https://www.cometchat.com/docs/calls/ios/link/sample-apps Navigate to Sample Apps documentation. # Migrating from Legacy Ringing Source: https://www.cometchat.com/docs/calls/ios/migrating-from-legacy-ringing Move an iOS app from Chat SDK call signalling and Push Notifications SDK 1.0 or hand-written PushKit and CallKit code to ringing with the Calls SDK 5.1 and the Push Notifications SDK 2.0: what to add, what to delete, and how each method maps. Legacy ringing signalled calls through the Chat SDK: `CometChat.initiateCall` created the call, a `CometChatCallDelegate` on the WebSocket told the callee, `acceptCall` and `rejectCall` answered, and the app rang the device itself, either with its own `PKPushRegistry` and `CXProvider` code or with the Push Notifications SDK 1.0. Ringing now runs on the Calls SDK and the Push Notifications SDK's Calls product. The Chat SDK's calling methods are superseded by the Calls SDK and no longer used; a coming Chat SDK release marks them deprecated. This page is the diff. For the full description of the current flow see [Ringing](/docs/calls/ios/ringing); for the push side see [Push ringing](/docs/calls/ios/voip-calling). ## Before you start Ringing with the Calls SDK is opt-in on the client: moving your app to the Calls SDK 5.1 and Push Notifications SDK 2.0 APIs below is the migration. While some of your users are still on legacy ringing, one dashboard setting lets the two flows call each other; see [While some users are still on legacy ringing](#while-some-users-are-still-on-legacy-ringing). This page is for apps that use the SDKs directly. If you use the CometChat UI Kit, its support for this flow comes with a coming UI Kit release; keep legacy ringing until then. ## Why it changed | Legacy | Now | | - | - | | Incoming calls arrived on the Chat WebSocket, so a backgrounded or killed app needed a separate PushKit + CallKit integration to ring | One path: the VoIP push rings through CallKit in every app state, the app killed and the phone locked included | | Your app wrote the `PKPushRegistryDelegate`, the `CXProviderDelegate`, the incoming UI and the busy check | The Push SDK owns PushKit and CallKit, handles busy, call waiting, the ring timeout and missed calls | | `acceptCall` / `rejectCall` / `endCall` were HTTP calls your app had to sequence with `joinSession` | Answer = join. Decline, ring-out and busy are sent by the Push SDK through a queue that survives the app being suspended | | Caller only knew "accepted" or "rejected" | Caller sees "Ringing…" (the callee's device was reached) and "answered". A decline, busy or ring-out is read from Call Logs while ringing | | Chat SDK required for calling | Chat SDK needed for chat only; a calls-only app works | ## Before and after ```mermaid theme={null} sequenceDiagram participant A as Caller participant Chat as Chat SDK (WebSocket) participant B as Callee rect rgb(240,240,240) Note over A,B: Legacy ringing A->>Chat: CometChat.initiateCall(call:) Chat-->>B: CometChatCallDelegate.onIncomingCallReceived B->>B: App reports to CallKit or shows its own UI B->>Chat: CometChat.acceptCall(sessionID:) Chat-->>A: onOutgoingCallAccepted A->>A: joinSession B->>B: joinSession A->>Chat: CometChat.endCall(sessionID:) Chat-->>B: onCallEndedMessageReceived end ``` ```mermaid theme={null} sequenceDiagram participant A as Caller participant BE as Backend participant P as Callee · Push SDK participant C as Callee · Calls SDK rect rgb(232,244,236) Note over A,C: Ringing now A->>BE: CometChatCalls.initiateCall(receiver:options:) BE-->>P: VoIP push (initiated) P->>P: reports to CallKit, which rings P->>C: connect(sessionID:) C-->>A: onParticipantConnected ("Ringing…") P->>C: Answer → presentCall(_:) → joinSession C-->>A: onParticipantJoined → joinSession A->>A: CallSession.shared.leave() to hang up end ``` ## Step 1: Update dependencies Both SDKs are distributed with Swift Package Manager. In Xcode's package dependencies: | Package | Change | Products | | - | - | - | | `https://github.com/cometchat/calls-sdk-ios` | Up to Next Major from **5.1.0** (was 5.0.x) | `CometChatCallsSDK` | | `https://github.com/cometchat/push-notifications-sdk-ios` | Up to Next Major from **2.0.0** (was 1.0) | `CometChatPushNotificationsSwift` (Core, as in 1.0), **`CometChatPushNotificationsCalls`** (new: the PushKit + CallKit ringer), `CometChatPushNotificationsChat` (only if you show chat notifications) | `CometChatSDK` stays for chat; it is no longer used for calls. If your project added these SDKs with CocoaPods, remove their pods from the `Podfile` and add the packages instead: the Calls SDK 5.1 and Push Notifications SDK 2.0 are not published as pods. A Notification Service Extension links Core and Chat only, never Calls. * Keep the **Push Notifications** capability and **Background Modes → Voice over IP** (and **Remote notifications** for chat pushes). * Keep `NSMicrophoneUsageDescription` and `NSCameraUsageDescription` in `Info.plist`. Linking the Calls product turns ringing on. There is no second initializer. ## Step 2: Replace the push configuration > [tab] Before (Push SDK 1.0) > > ```swift theme={null} > // After CometChat.init(...) > CometChatPushNotifications.shared.initialize(config: .init( > providerId: "YOUR_PROVIDER_ID", > callkitIconName: "CallKitIcon" > )) > CometChatPushNotifications.shared.delegate = self > ``` > [tab] After (Push SDK 2.0) > > ```swift theme={null} > // In application(_:didFinishLaunchingWithOptions:), before anything else > CometChatPushNotifications.shared.delegate = pushDelegate // held weakly: keep it alive > CometChatPushNotifications.shared.initialize(config: PNConfiguration( > appId: "APP_ID", > region: "REGION", > providerId: "YOUR_PROVIDER_ID", > callKit: CallKitBranding(iconTemplateImageName: "CallKitIcon") > )) > ``` `appId` and `region` are required in 2.0: the Push SDK registers tokens and brings the Calls SDK up in a process the push started, before your own code has initialized anything. `initialize` must run in `didFinishLaunching`, because it creates the PushKit registry and iOS only delivers the VoIP push that launched a killed app when that registry exists by the end of launch. ## Step 3: Replace the call delegate > [tab] Before (Push SDK 1.0) > > ```swift theme={null} > func presentCallScreen(for call: Call, sessionId: String) { > // open the call screen, which calls CometChat.acceptCall and joinSession > } > func onCallMissed(call: Call, reason: CometChatMissedCallReason) { } > func onCallCleanupComplete() { } > > // after Calls SDK login: > CometChatPushNotifications.shared.notifyCallsSDKReady() > ``` > [tab] After (Push SDK 2.0) > > ```swift theme={null} > final class CallPushDelegate: NSObject, CometChatPushNotificationsCallsDelegate { > func presentCall(_ call: IncomingCall) -> Bool { > // present the call screen on the root view controller; it calls joinSession at once > return true > } > func callDidEnd(_ call: IncomingCall, reason: CallEndReason) { > // dismiss the call screen for call.sessionId > } > } > // No notifyCallsSDKReady(): the Push SDK waits for the Calls SDK itself. > ``` `presentCall` fires immediately on Answer in every app state, the phone locked included, at most once per session. Return `false` when you cannot show the call, and the Push SDK ends it. ## Step 4: Delete the token code The Push SDK registers the APNs and VoIP tokens on login by itself. Its own unregister at logout can run after the user's auth token is gone, so call `unregisterTokens` and wait for it before you log out ([Step 7](#step-7-change-the-logout)). Remove: * `CometChatNotifications.registerPushToken(...)` after login and `unregisterPushToken(...)` before logout * The VoIP token handling in your own `pushRegistry(_:didUpdate:for:)` Keep forwarding the APNs device token with `CometChatPushNotifications.shared.registerDeviceToken(deviceToken)` in `application(_:didRegisterForRemoteNotificationsWithDeviceToken:)`; the VoIP token is captured by the Calls product. If your app must keep its own `PKPushRegistry`, see [Owning PushKit yourself](/docs/calls/ios/voip-calling#owning-pushkit-yourself). ## Step 5: Delete the app-side ringing Everything in this list is now done by the Push SDK. Remove it, or it will fight the SDK's ring (two CallKit calls, two providers that cannot end each other's calls, a busy reject sent on top of the SDK's). * `CometChat.addCallListener(...)` / `CometChat.calldelegate` and the `onIncomingCallReceived` handler * The incoming-call screen, banner or alert you showed from it, and your own ringtone for incoming calls * Your `PKPushRegistry` and `PKPushRegistryDelegate`, `CXProvider`, `CXProviderDelegate`, `CXCallController` and the `CallManager` that tied them to CometChat (the pattern the earlier VoIP Calling guide described) * Any `AVAudioSession.setActive(true)` in CallKit callbacks: CallKit owns the call's audio session, and activating it yourself causes one-way audio on lock-screen answers * The "already in a call → reject with busy" check * With Push SDK 1.0: `foregroundCallPresentation`, `CometChatIncomingCallView` / `incomingCallStyle`, `notifyCallsSDKReady()` ## Step 6: Rewrite the call code | Legacy | Now | Notes | | - | - | - | | `CometChat.initiateCall(call: Call(receiverId:callType:receiverType:), onSuccess:onError:)` | `CometChatCalls.initiateCall(receiver:options:onSuccess:onError:)` → `InitiatedCall` | Set `options.sessionSettings` with the session type, or an audio call opens the camera | | `CometChat.initiateCall(call:timeout:onSuccess:onError:)` | No client timeout. The callee's device rings for 45 s (or the push's `ringTimeout`) and then ends a 1:1 call as `unanswered` | Run your own 45 s timer on the caller: if the callee's device is never reached, nothing else ends the caller's ringing for 5 minutes | | `CometChatCallDelegate.onIncomingCallReceived(incomingCall:error:)` | Nothing to write; the Push SDK rings through CallKit. For your own state use `CometChatIncomingCallListener.onIncomingCallReceived(call:)` | One listener whether the call came by push to a killed app or a running one | | `onOutgoingCallAccepted(acceptedCall:error:)` | `ParticipantEventListener.onParticipantJoined(participant:)` on `CallSession.shared`, the session `initiateCall` prepared | New in-between event: `onParticipantConnected` = the callee's device is ringing | | `onOutgoingCallRejected(rejectedCall:error:)` | Poll [Call Logs](/docs/calls/ios/call-logs) for the call's status while it rings; `SessionStatusListener.onConnectionClosed()` on the prepared session when it closes | Not reliably pushed to the caller on iOS: a busy decline, or a decline before the callee's device connected, closes nothing | | `onIncomingCallCancelled(canceledCall:error:)` | `CometChatIncomingCallListener.onIncomingCallEnded(call:reason:)` on the callee, with `cancelled` or, once the callee's device had prepared the session, `ended`; CallKit has already stopped the ring | | | `onCallEndedMessageReceived(endedCall:error:)` | `SessionStatusListener.onSessionLeft()` / `onConnectionClosed()` on the joined session | | | `CometChat.acceptCall(sessionID:onSuccess:onError:)` then `joinSession` | `presentCall(_:)` opens your screen, which calls `joinSession(sessionID:...)`. Nothing else to send | The Push SDK asks for the microphone and camera after Answer | | `CometChat.rejectCall(sessionID:status: .rejected, ...)` | CallKit's Decline. Your own button: `CometChatPushNotificationsCalls.decline(sessionId:)` | Sends `busy` automatically when in another call | | `CometChat.rejectCall(sessionID:status: .busy, ...)` | Nothing; the Push SDK decides busy | | | `CometChat.rejectCall(sessionID:status: .cancelled, ...)` | `CometChatCalls.endCall(sessionID:status: EndCallStatus.cancelled, onSuccess:onError:)` | Also tears down the caller's prepared session | | `CallSession.shared.leaveSession()` + `CometChat.endCall(sessionID:)` | `CallSession.shared.leave()` | No status to send on a hang-up; the room tells the other side and the backend logs it | | `CometChat.getActiveCall()` / `clearActiveCall()` | `CometChatCalls.getActiveSession()` (nil when no session is prepared or joined) | | | `CometChat.startCall(...)`, Chat SDK `CallSettings` | `joinSession` + the 5.x listeners (see the [v5 migration guide](/docs/calls/ios/migration-guide-v5)) | | | Push SDK 1.0 `presentCallScreen(for:sessionId:)` | `presentCall(_:) -> Bool` | Takes the push SDK's `IncomingCall`, not a Chat SDK `Call` | | Push SDK 1.0 `onCallMissed(call:reason:)` | `callDidEnd(_:reason:)` | CallKit writes the missed call to Recents | | `CometChat.logout(...)` | `CometChatCalls.logout(...)` as well, after awaiting `unregisterTokens` | Otherwise the Calls SDK stays signed in as the old user | ### Caller screen, before and after > [tab] Before > > ```swift theme={null} > CometChat.addCallListener(listenerId, self) > > func onOutgoingCallAccepted(acceptedCall: Call?, error: CometChatException?) { > joinCallSession(sessionId: acceptedCall?.sessionID ?? "") > } > func onOutgoingCallRejected(rejectedCall: Call?, error: CometChatException?) { > dismiss(animated: true) > } > > @objc func endTapped() { > CometChat.rejectCall(sessionID: sessionId, status: .cancelled, > onSuccess: { _ in }, onError: { _ in }) > } > ``` > [tab] After > > ```swift theme={null} > CallSession.shared.addSessionStatusListener(self) > CallSession.shared.addParticipantEventListener(self) > > func onParticipantConnected(participant: Participant) { statusLabel.text = "Ringing…" } > func onParticipantJoined(participant: Participant) { > joinCallSession(sessionId: sessionId, isVideo: isVideo) > } > func onConnectionClosed() { > dismiss(animated: true) // the prepared session closed; busy and early declines come from Call Logs > } > > @objc func endTapped() { > CometChatCalls.endCall(sessionID: sessionId, status: EndCallStatus.cancelled, > onSuccess: {}, onError: { _ in }) > } > ``` ### Callee screen, before and after > [tab] Before > > ```swift theme={null} > // Called from your CometChatCallDelegate or your CXProviderDelegate's answer action > func answer(sessionId: String) { > CometChat.acceptCall(sessionID: sessionId, onSuccess: { call in > self.joinCallSession(sessionId: call?.sessionID ?? "") > }, onError: { _ in }) > } > func decline(sessionId: String) { > CometChat.rejectCall(sessionID: sessionId, status: .rejected, > onSuccess: { _ in }, onError: { _ in }) > } > ``` > [tab] After > > ```swift theme={null} > // Opened by your delegate's presentCall(_:): the user already answered on CallKit > override func viewDidLoad() { > super.viewDidLoad() > joinCallSession(sessionId: sessionId, isVideo: isVideo) > } > // There is no decline button here: CallKit's Decline sends it through the Push SDK. > ``` ## Step 7: Change the logout ```swift theme={null} // Unregister first: both token DELETEs need the user's auth token. CometChatPushNotifications.shared.unregisterTokens(completion: { _ in CometChat.logout(onSuccess: { _ in }, onError: { _ in }) CometChatCalls.logout(onSuccess: { _ in }, onError: { _ in }) // new: stops a ringing call }) ``` ## While some users are still on legacy ringing Your users don't all update at once, so during the rollout one CometChat app has devices on both flows. A device's flow comes from its push registration: a device on the Calls SDK 5.1 and Push Notifications SDK 2.0 receives only the call-initiated push, and a device still on legacy ringing keeps receiving the legacy call events. To let users on the two flows call each other, turn on **Connect legacy ringing** in the CometChat dashboard under **Voice & Video Calls → Settings**. CometChat then also sends calls made on this flow as legacy call events, so devices on either flow ring for calls from the other. * Turn it on before the first users update, and leave it on while any version of your apps still in use rings the legacy way. * It can't be turned off from the dashboard. * The six legacy call events (ongoing, cancelled, rejected, unanswered, busy and ended) are under **Show legacy** in **Notifications → Settings → Call Preferences**. They only reach devices on legacy ringing. ## What users will notice * Calls ring through CallKit with the app killed and from the lock screen, with no app code on the ring path. * The caller sees "Ringing…" once the callee's phone is reached, and the call screen closes when the call is declined or missed (from the Call Logs status, or the ring timer). * The callee stops ringing after 45 seconds, and the caller's screen closes on its own timer. * Missed calls appear in the Phone app's Recents. * A call during a call is call waiting (End & Accept ends the current call, Decline sends busy), not an automatic reject. * The microphone and camera prompt appears after Answer the first time, on the device that answers; on a locked phone it waits for the unlock. * Outgoing calls appear in Recents too, and survive an incoming cellular call. ## Checklist * [ ] `CometChatCallsSDK` 5.1, Push SDK 2.0 Core + Calls products added; the Notification Service Extension links Core + Chat only * [ ] Push Notifications capability, Background Modes → Voice over IP, microphone and camera usage strings * [ ] `initialize(config:)` runs in `didFinishLaunching` with `appId`, `region` and `providerId` * [ ] The delegate adopts `CometChatPushNotificationsCallsDelegate` and is kept alive; `presentCall(_:)` presents and joins at once * [ ] Manual token registration and `notifyCallsSDKReady()` removed * [ ] `CometChat.addCallListener`, your own PushKit / CallKit code, incoming UI, ringtone, busy check and `setActive` calls removed * [ ] `initiateCall` sets the session type in `sessionSettings`, built with a new `SessionSettingsBuilder()` * [ ] Caller listens on the prepared session and joins only on `onParticipantJoined`; runs a 45 s ring timer * [ ] Hang-up uses `leave()`; no `CometChat.endCall` * [ ] Logout awaits `unregisterTokens`, then logs out of the Calls SDK as well * [ ] `ensureRingReady` runs after sign-in and anything other than `.ready` is shown to the user * [ ] **Connect legacy ringing** is on in the dashboard if some users stay on legacy ringing during the rollout * [ ] Tested on a device: ring with the app killed and the phone locked, decline, cancel, no answer, call during a call, logout while ringing # Migration Guide Source: https://www.cometchat.com/docs/calls/ios/migration-guide-v5 Migrate to CometChat Calls SDK v5 on iOS with updated setup, APIs, call sessions, layouts, and feature changes. This guide covers migrating from Calls SDK v4 to v5 for iOS. ## Drop-in Compatibility Calls SDK v5 is a **drop-in replacement** for v4. All v4 APIs are preserved as deprecated methods that internally delegate to the new v5 implementations. You can update the dependency version and your existing code will compile and run without changes. In Xcode's package dependencies, update `https://github.com/cometchat/calls-sdk-ios` to **Up to Next Major Version** from **5.1.0**. The Calls SDK 5.1 is distributed with Swift Package Manager only: if your project added v4 with CocoaPods, remove `pod 'CometChatCallsSDK'` from the `Podfile`, run `pod install` to take it out, and add the package. > [!NOTE] > > If you're using CometChat UI Kits, simply updating the Calls SDK version is sufficient. The UI Kit will continue to work with v5 through the deprecated compatibility layer. ## Why Migrate to v5 APIs? While v4 APIs will continue to work, migrating to v5 APIs gives you: * **Granular event listeners** — 5 focused listener protocols instead of one monolithic `CallsEventsDelegate` * **`CallSession` singleton** for cleaner session control — all actions on a single object instead of scattered static methods * **Dedicated `login()` method** — the Calls SDK now handles its own authentication instead of depending on the Chat SDK's auth token or REST APIs * **Strongly-typed enums** — `AudioMode`, `SessionType`, `LayoutType`, `CameraFacing` instead of raw strings *** ## Initialization No changes required. The `init` API is the same in v5. ```swift theme={null} let callAppSettings = CallAppSettingsBuilder() .set(appID: "APP_ID") .set(region: "REGION") .build() CometChatCalls(callsAppSettings: callAppSettings, onSuccess: { success in // Initialized }, onError: { error in // Handle error }) ``` *** ## Authentication In v4, the Calls SDK had no dedicated authentication step. It relied on the Chat SDK's auth token (`CometChat.getUserAuthToken()`) or a REST API to obtain an auth token, which you then passed manually to `generateToken(authToken:sessionID:onSuccess:onError:)`. v5 introduces its own `login()` method. After calling `login()`, the SDK caches the auth token internally, so you no longer need to pass it around to other API calls. > [tab] v4 > > ```swift theme={null} > // No dedicated Calls SDK login — relied on Chat SDK for auth token > let authToken = CometChat.getUserAuthToken() > > // Had to pass authToken manually > CometChatCalls.generateToken(authToken: authToken as NSString?, > sessionID: sessionID as NSString?, > onSuccess: { token in > // Use token to start session > }, onError: { error in }) > ``` > [tab] v5 > > ```swift theme={null} > // Login to the Calls SDK once (after your Chat SDK login) > CometChatCalls.login(authToken: authToken, onSuccess: { callsUser in > // Calls SDK is now authenticated — auth token is cached internally > }, onError: { error in }) > ``` > [!NOTE] > > Call `CometChatCalls.login()` once after your user authenticates (e.g., right after `CometChat.login()` succeeds). The SDK stores the auth token internally, so subsequent calls like `generateToken()` and `joinSession()` use it automatically without you having to pass it. *** ## Session Settings `CallSettingsBuilder` and `PresentationSettingsBuilder` are replaced by `SessionSettingsBuilder`. The builder methods have been renamed for clarity. > [tab] v4 > > ```swift theme={null} > let callSettings = CometChatCalls.callSettingsBuilder > .setIsAudioOnly(true) > .setDefaultLayout(true) > .setEndCallButtonDisable(false) > .setMuteAudioButtonDisable(false) > .setPauseVideoButtonDisable(false) > .setSwitchCameraButtonDisable(false) > .setAudioModeButtonDisable(false) > .setShowRecordingButton(true) > .setStartAudioMuted(false) > .setStartVideoMuted(false) > .setDefaultAudioMode("SPEAKER") > .setMode("DEFAULT") > .setStartRecordingOnCallStart(false) > .setDelegate(self) > .build() > ``` > [tab] v5 > > ```swift theme={null} > let sessionSettings = CometChatCalls.sessionSettingsBuilder > .setSessionType(.voice) > .startAudioMuted(false) > .startVideoPaused(false) > .setLayout(.tile) > .setAudioMode(.speaker) > .hideLeaveSessionButton(false) > .hideToggleAudioButton(false) > .hideToggleVideoButton(false) > .hideSwitchCameraButton(false) > .hideAudioModeButton(false) > .hideRecordingButton(false) > .hideControlPanel(false) > .hideHeaderPanel(false) > .enableAutoStartRecording(false) > .build() > ``` ### Builder Method Mapping | v4 Method | v5 Method | Notes | | - | - | - | | `setIsAudioOnly(true)` | `setSessionType(.voice)` | Use `.video` for video calls | | `setDefaultLayout(bool)` | `hideControlPanel(!bool)` + `hideHeaderPanel(!bool)` | Inverted logic | | `setEndCallButtonDisable(bool)` | `hideLeaveSessionButton(bool)` | Same logic | | `setMuteAudioButtonDisable(bool)` | `hideToggleAudioButton(bool)` | Same logic | | `setPauseVideoButtonDisable(bool)` | `hideToggleVideoButton(bool)` | Same logic | | `setSwitchCameraButtonDisable(bool)` | `hideSwitchCameraButton(bool)` | Same logic | | `setAudioModeButtonDisable(bool)` | `hideAudioModeButton(bool)` | Same logic | | `setShowRecordingButton(bool)` | `hideRecordingButton(!bool)` | Inverted logic | | `setStartAudioMuted(bool)` | `startAudioMuted(bool)` | Same logic | | `setStartVideoMuted(bool)` | `startVideoPaused(bool)` | Same logic | | `setDefaultAudioMode("SPEAKER")` | `setAudioMode(.speaker)` | Enum instead of string | | `setMode("DEFAULT")` | `setLayout(.tile)` | Enum instead of string | | `setStartRecordingOnCallStart(bool)` | `enableAutoStartRecording(bool)` | Same logic | | `setAvatarMode(string)` | *Removed* | No longer applicable | | `setEnableVideoTileClick(bool)` | *Removed* | No longer applicable | | `setEnableDraggableVideoTile(bool)` | *Removed* | No longer applicable | | `setDelegate(delegate)` | Use `CallSession` listeners | See [Events](#event-listeners) section | *** ## Joining a Session `startSession()` is replaced by `joinSession()`. > [tab] v4 > > ```swift theme={null} > // Step 1: Generate token with auth token > CometChatCalls.generateToken(authToken: authToken as NSString?, > sessionID: sessionID as NSString?, > onSuccess: { token in > // Step 2: Start session with token string > CometChatCalls.startSession(callToken: token ?? "", > callSetting: callSettings, > view: callView, > onSuccess: { message in > // Session started > }, onError: { error in }) > }, onError: { error in }) > ``` > [tab] v5 > > ```swift theme={null} > // Option A: Two-step with token > CometChatCalls.generateToken(sessionID: sessionID, onSuccess: { token in > CometChatCalls.joinSession(callToken: token ?? "", > callSetting: sessionSettings, > container: callView, > onSuccess: { message in > // Session joined > }, onError: { error in }) > }, onError: { error in }) > > // Option B: One-step with session ID (recommended) > CometChatCalls.joinSession(sessionID: sessionID, > callSetting: sessionSettings, > container: callView, > onSuccess: { message in > // Token generation + join handled internally > }, onError: { error in }) > ``` Key differences: * v5 `generateToken()` no longer requires the `authToken` parameter (uses cached token from `login()`) * v5 offers a convenience overload that takes `sessionID` directly and handles token generation internally * Parameter name changed from `view` to `container` *** ## Session Control (Actions) In v4, session actions were static methods on `CometChatCalls`. In v5, they're instance methods on `CallSession.shared`. > [tab] v4 > > ```swift theme={null} > CometChatCalls.endSession() > CometChatCalls.switchCamera() > CometChatCalls.audioMuted(true) > CometChatCalls.videoPaused(true) > CometChatCalls.setAudioMode(mode: "SPEAKER") > CometChatCalls.enterPIPMode() > CometChatCalls.exitPIPMode() > CometChatCalls.startRecording() > CometChatCalls.stopRecording() > ``` > [tab] v5 > > ```swift theme={null} > let callSession = CallSession.shared > > callSession.leave() > callSession.switchCamera() > callSession.muteAudio() // or callSession.unmuteAudio() > callSession.pauseVideo() // or callSession.resumeVideo() > callSession.setAudioMode("SPEAKER") > callSession.enablePictureInPictureLayout() > callSession.disablePictureInPictureLayout() > callSession.startRecording() > callSession.stopRecording() > ``` ### Action Method Mapping | v4 Static Method | v5 CallSession Method | | - | - | | `CometChatCalls.endSession()` | `callSession.leave()` | | `CometChatCalls.switchCamera()` | `callSession.switchCamera()` | | `CometChatCalls.audioMuted(true)` | `callSession.muteAudio()` | | `CometChatCalls.audioMuted(false)` | `callSession.unmuteAudio()` | | `CometChatCalls.videoPaused(true)` | `callSession.pauseVideo()` | | `CometChatCalls.videoPaused(false)` | `callSession.resumeVideo()` | | `CometChatCalls.setAudioMode(mode:)` | `callSession.setAudioMode(_:)` | | `CometChatCalls.enterPIPMode()` | `callSession.enablePictureInPictureLayout()` | | `CometChatCalls.exitPIPMode()` | `callSession.disablePictureInPictureLayout()` | | `CometChatCalls.startRecording()` | `callSession.startRecording()` | | `CometChatCalls.stopRecording()` | `callSession.stopRecording()` | | `CometChatCalls.switchToVideoCall()` | *Removed* | *** ## Event Listeners This is the biggest improvement in v5. The single `CallsEventsDelegate` protocol is replaced by 5 focused listener protocols. ### v4: Single Monolithic Delegate ```swift theme={null} class MyViewController: UIViewController, CallsEventsDelegate { func setupCallEvents() { // Set via builder CometChatCalls.callSettingsBuilder.setDelegate(self).build() } func onCallEnded() { } func onCallEndButtonPressed() { } func onSessionTimeout() { } func onUserJoined(rtcUser: RTCUser) { } func onUserLeft(rtcUser: RTCUser) { } func onUserListChanged(rtcUsers: [RTCUser]) { } func onAudioModeChanged(mode: [CallAudioMode]) { } func onCallSwitchedToVideo(callSwitchedInfo: CallSwitchRequestInfo) { } func onUserMuted(rtcMutedUser: RTCMutedUser) { } func onRecordingToggled(recordingInfo: RTCRecordingInfo) { } } ``` ### v5: Focused Listener Protocols ```swift theme={null} let callSession = CallSession.shared // Session lifecycle events class MySessionListener: SessionStatusListener { func onSessionJoined() { } func onSessionLeft() { } func onSessionTimedOut() { } func onConnectionLost() { } func onConnectionRestored() { } func onConnectionClosed() { } } callSession.addSessionStatusListener(mySessionListener) // Participant events (replaces onUserJoined, onUserLeft, onUserListChanged, onUserMuted) class MyParticipantListener: ParticipantEventListener { func onParticipantJoined(participant: Participant) { } func onParticipantLeft(participant: Participant) { } func onParticipantListChanged(participants: [Participant]) { } func onParticipantAudioMuted(participant: Participant) { } func onParticipantAudioUnmuted(participant: Participant) { } func onParticipantVideoPaused(participant: Participant) { } func onParticipantVideoResumed(participant: Participant) { } func onParticipantHandRaised(participant: Participant) { } func onParticipantHandLowered(participant: Participant) { } func onParticipantStartedRecording(participant: Participant) { } func onParticipantStoppedRecording(participant: Participant) { } func onDominantSpeakerChanged(participant: Participant) { } } callSession.addParticipantEventListener(myParticipantListener) // Media state events (replaces onAudioModeChanged, onRecordingToggled) class MyMediaListener: MediaEventsListener { func onAudioMuted() { } func onAudioUnMuted() { } func onVideoPaused() { } func onVideoResumed() { } func onRecordingStarted() { } func onRecordingStopped() { } func onAudioModeChanged(audioMode: AudioMode) { } func onCameraFacingChanged(cameraFacing: CameraFacing) { } } callSession.addMediaEventsListener(myMediaListener) // Button click events (replaces onCallEndButtonPressed) class MyButtonListener: ButtonClickListener { func onLeaveSessionButtonClicked() { } func onToggleAudioButtonClicked() { } func onToggleVideoButtonClicked() { } func onSwitchCameraButtonClicked() { } func onRaiseHandButtonClicked() { } func onRecordingToggleButtonClicked() { } } callSession.addButtonClickListener(myButtonListener) // Layout events class MyLayoutListener: LayoutListener { func onCallLayoutChanged(layoutType: LayoutType) { } func onPictureInPictureLayoutEnabled() { } func onPictureInPictureLayoutDisabled() { } } callSession.addLayoutListener(myLayoutListener) ``` > [!NOTE] > > v5 listeners use weak references internally, so they are automatically cleaned up when the listener object is deallocated. This also means the SDK does not keep a listener alive: store `mySessionListener` and the others in a property (or register a view controller that conforms to the protocol). A listener passed in without another owner is deallocated immediately and receives no events. You can also explicitly remove listeners using `removeSessionStatusListener(_:)`, `removeParticipantEventListener(_:)`, etc. ### Event Mapping | v4 Event | v5 Listener | v5 Event | | - | - | - | | `onCallEnded()` | `SessionStatusListener` | `onSessionLeft()` | | `onCallEndButtonPressed()` | `ButtonClickListener` | `onLeaveSessionButtonClicked()` | | `onSessionTimeout()` | `SessionStatusListener` | `onSessionTimedOut()` | | `onUserJoined(rtcUser:)` | `ParticipantEventListener` | `onParticipantJoined(participant:)` | | `onUserLeft(rtcUser:)` | `ParticipantEventListener` | `onParticipantLeft(participant:)` | | `onUserListChanged(rtcUsers:)` | `ParticipantEventListener` | `onParticipantListChanged(participants:)` | | `onAudioModeChanged(mode:)` | `MediaEventsListener` | `onAudioModeChanged(audioMode:)` | | `onCallSwitchedToVideo(callSwitchedInfo:)` | *Removed* | — | | `onUserMuted(rtcMutedUser:)` | `ParticipantEventListener` | `onParticipantAudioMuted(participant:)` | | `onRecordingToggled(recordingInfo:)` | `MediaEventsListener` | `onRecordingStarted()` / `onRecordingStopped()` | ### New Events in v5 These events are only available with the v5 listener APIs: | Listener | Event | Description | | - | - | - | | `SessionStatusListener` | `onConnectionLost()` | Network interrupted | | `SessionStatusListener` | `onConnectionRestored()` | Network restored | | `SessionStatusListener` | `onConnectionClosed()` | Connection permanently closed | | `ParticipantEventListener` | `onParticipantVideoResumed()` | Participant turned camera on | | `ParticipantEventListener` | `onParticipantVideoPaused()` | Participant turned camera off | | `ParticipantEventListener` | `onParticipantHandRaised()` | Participant raised hand | | `ParticipantEventListener` | `onParticipantHandLowered()` | Participant lowered hand | | `ParticipantEventListener` | `onParticipantStartedScreenShare()` | Participant started screen share | | `ParticipantEventListener` | `onParticipantStoppedScreenShare()` | Participant stopped screen share | | `ParticipantEventListener` | `onDominantSpeakerChanged()` | Active speaker changed | | `MediaEventsListener` | `onCameraFacingChanged()` | Camera switched front/back | | `ButtonClickListener` | Various button events | Individual button click tracking | | `LayoutListener` | `onCallLayoutChanged()` | Layout type changed | | `LayoutListener` | `onPictureInPictureLayoutEnabled/Disabled()` | PiP state changed | *** ## Call Logs The `CallLogsRequest` API is unchanged. The only difference is that auth is now handled by `CometChatCalls.login()` instead of passing the auth token manually. *** ## Deprecated Classes Summary These classes still exist in v5 for backward compatibility but are deprecated: | Deprecated Class | Replacement | | - | - | | `CallSettings` | `SessionSettingsBuilder.SessionSettings` | | `CallSettingsBuilder` | `SessionSettingsBuilder` | | `PresentationSettings` | `SessionSettingsBuilder.SessionSettings` | | `PresentationSettingsBuilder` | `SessionSettingsBuilder` | | `CallsEventsDelegate` | 5 focused listeners on `CallSession` | | `RTCRecordingInfo` | `MediaEventsListener` callbacks | | `CallSwitchRequestInfo` | *Removed (no replacement)* | *** ## 5.0 to 5.1 5.1 moves ringing onto the Calls SDK and the Push Notifications SDK, and deprecates two `CallSession` methods: | Deprecated in 5.1 | Replacement | | - | - | | `CallSession.leaveSession()` | `CallSession.leave()` | | `CallSession.isCallSessionActive()` | `CallSession.isSessionActive()`, which is also `true` while a session is only prepared; use `isSessionJoined()` for "in a call" | | Chat SDK calling (superseded; deprecated in a coming Chat SDK release): `CometChat.initiateCall`, `acceptCall`, `rejectCall`, `endCall`, `startCall`, `getActiveCall`, `clearActiveCall`, `addCallListener` / `calldelegate`, `CometChatCallDelegate`, `CallSettings` | `CometChatCalls.initiateCall`, `endCall(sessionID:status:)`, `addIncomingCallListener`, the Push Notifications SDK Calls product, `leave()` | New in 5.1: * `CometChatCalls.initiateCall(receiver:options:onSuccess:onError:)` with `InitiateCallOptions` and `InitiatedCall` * `CometChatCalls.endCall(sessionID:status:onSuccess:onError:)` with `EndCallStatus` * `CometChatCalls.connect(sessionID:callSetting:onSuccess:onError:)`, which prepares a session ahead of `joinSession`, and `CallSession.prepareStatus` / `prepareError` with `PrepareStatus` * `CometChatCalls.getActiveSession()`, `CometChatCalls.getSessionState(onSuccess:)`, `CometChatCalls.getParticipants(onSuccess:)` and `CallSession.getParticipants(onSuccess:)` * `CometChatCalls.addIncomingCallListener` / `removeIncomingCallListener` with `CometChatIncomingCallListener` and `CometChatIncomingCall` * `SessionStatusListener.onConnected()` and `ParticipantEventListener.onParticipantConnected(participant:)` * `CallSession.leave()`, `isSessionActive()`, `isSessionJoined()`, `sessionId` and `callToken` * `SessionSettingsBuilder.setPeerCall(_:)`: a 1:1 session that ends for both participants when either leaves * `CallSessionType` and `CallReceiverType` constants On a session prepared by `connect` or `initiateCall`, `joinSession` ignores the settings it is passed: the ones frozen at prepare apply. The step-by-step move from Chat SDK signalling is on [Migrating from Legacy Ringing](/docs/calls/ios/migrating-from-legacy-ringing). # Calls SDK Source: https://www.cometchat.com/docs/calls/ios/overview Use CometChat Calls SDK v5 for iOS to add voice and video calling, call sessions, participants, layouts, and in-call features. The CometChat Calls SDK enables real-time voice and video calling capabilities in your iOS application. Built on top of WebRTC, it provides a complete calling solution with built-in UI components and extensive customization options. ## Prerequisites Before integrating the Calls SDK, ensure you have: 1. **CometChat Account**: [Sign up](https://app.cometchat.com/signup) and create an app to get your App ID, Region, and API Key 2. **CometChat Users**: Users must exist in CometChat to use calling features. For testing, create users via the [Dashboard](https://app.cometchat.com) or [REST API](/docs/rest-api/users/create). Authentication is handled by the Calls SDK - see [Authentication](/docs/calls/ios/authentication) 3. **iOS Requirements**: * Minimum iOS version: 15.1 * Xcode 16.4 or later * Swift 5.0 or later 4. **Permissions**: Camera and microphone permissions for video/audio calls ## Call Flow ```mermaid theme={null} sequenceDiagram participant App participant CometChatCalls participant CallSession App->>CometChatCalls: init() App->>CometChatCalls: login() App->>CometChatCalls: joinSession(sessionID:) CometChatCalls-->>App: onSuccess (then use CallSession.shared) App->>CallSession: Actions (mute, pause, etc.) CallSession-->>App: Event callbacks App->>CallSession: leave() ``` Every call is a session joined by id. Where the id comes from depends on the kind of call: * **Direct call**: your app shares a session id (for example in a message) and each participant calls `joinSession` with it. Group calls and meetings work this way. * **Ringing call**: the caller starts it with `CometChatCalls.initiateCall`, the Push Notifications SDK rings the callee through CallKit, and both sides join the session once the callee answers. See [Ringing](/docs/calls/ios/ringing) and [Push Ringing](/docs/calls/ios/voip-calling). ## Features > [card] [Ringing](/docs/calls/ios/ringing) > > Start a call, ring the callee through push and CallKit, show "Ringing…", answer, decline, cancel and end > [card] [Call Layouts](/docs/calls/ios/call-layouts) > > Tile and Spotlight view modes for different call scenarios > [card] [Audio Modes](/docs/calls/ios/audio-modes) > > Switch between speaker, earpiece, Bluetooth, and headphones > [card] [Recording](/docs/calls/ios/recording) > > Record call sessions for later playback > [card] [Call Logs](/docs/calls/ios/call-logs) > > Retrieve call history and details > [card] [Participant Management](/docs/calls/ios/participant-management) > > Mute, pin, and manage call participants > [card] [Screen Sharing](/docs/calls/ios/screen-sharing) > > View screen shares from other participants > [card] [Picture-in-Picture](/docs/calls/ios/picture-in-picture) > > Continue calls while using other apps > [card] [Raise Hand](/docs/calls/ios/raise-hand) > > Signal to get attention during calls > [card] [Idle Timeout](/docs/calls/ios/idle-timeout) > > Automatic session termination when alone in a call ## Architecture The SDK is organized around these core components: | Component | Description | | - | - | | `CometChatCalls` | Main entry point for SDK initialization, authentication, and session management | | `CallAppSettings` | Configuration for SDK initialization (App ID, Region) | | `SessionSettings` | Configuration for individual call sessions | | `CallSession` | Singleton that manages the active call and provides control methods | | `Listeners` | Protocol-based event interfaces for session, participant, media, and UI events | ## Sample App > [card] [Sample App](https://github.com/cometchat/calls-sdk-ios/tree/v5/sample-apps/cometchat-calls-sample-app-ios) > > Explore the iOS Calls SDK sample app on GitHub > [card] [Changelog](https://github.com/cometchat/calls-sdk-ios/releases) > > View the latest releases and changes # Participant Management Source: https://www.cometchat.com/docs/calls/ios/participant-management Manage CometChat Calls SDK v5 participants on iOS with mute, pause video, pinning, permissions, and participant events. Manage participants during a call with actions like muting, pausing video, and pinning. These features help maintain order in group calls and highlight important speakers. > [!NOTE] > > By default, all participants who join a call have moderator access and can perform these actions. Implementing role-based moderation (e.g., restricting actions to hosts only) is the responsibility of the app developer based on their use case. ## Mute a Participant Mute a specific participant's audio. This affects the participant for all users in the call. ```swift theme={null} guard let uid = participant.uid else { return } CallSession.shared.muteParticipant(participantId: uid) ``` ## Pause Participant Video Pause a specific participant's video. This affects the participant for all users in the call. ```swift theme={null} guard let uid = participant.uid else { return } CallSession.shared.pauseParticipantVideo(participantId: uid) ``` ## Pin a Participant Pin a participant to keep them prominently displayed regardless of who is speaking. Useful for keeping focus on a presenter or important speaker. ```swift theme={null} // Pin a participant CallSession.shared.pinParticipant(participantId: "PARTICIPANT_UID", type: "pin") // Unpin (returns to automatic speaker highlighting) CallSession.shared.unpinParticipant() ``` > [!NOTE] > > Pinning a participant only affects your local view. Other participants can pin different users independently. ## Listen for Participant Events Monitor participant state changes using `ParticipantEventListener`: ```swift theme={null} class CallViewController: UIViewController, ParticipantEventListener { override func viewDidLoad() { super.viewDidLoad() CallSession.shared.addParticipantEventListener(self) } deinit { CallSession.shared.removeParticipantEventListener(self) } func onParticipantJoined(participant: Participant) { print("\(participant.name ?? "") joined the call") updateParticipantList() } func onParticipantLeft(participant: Participant) { print("\(participant.name ?? "") left the call") updateParticipantList() } func onParticipantListChanged(participants: [Participant]) { print("Participant count: \(participants.count)") refreshParticipantList(participants) } func onParticipantAudioMuted(participant: Participant) { print("\(participant.name ?? "") was muted") updateMuteIndicator(participant, muted: true) } func onParticipantAudioUnmuted(participant: Participant) { print("\(participant.name ?? "") was unmuted") updateMuteIndicator(participant, muted: false) } func onParticipantVideoPaused(participant: Participant) { print("\(participant.name ?? "") video paused") showParticipantAvatar(participant) } func onParticipantVideoResumed(participant: Participant) { print("\(participant.name ?? "") video resumed") showParticipantVideo(participant) } func onDominantSpeakerChanged(participant: Participant) { print("\(participant.name ?? "") is now speaking") highlightActiveSpeaker(participant) } // Other callbacks... func onParticipantHandRaised(participant: Participant) {} func onParticipantHandLowered(participant: Participant) {} func onParticipantStartedScreenShare(participant: Participant) {} func onParticipantStoppedScreenShare(participant: Participant) {} func onParticipantStartedRecording(participant: Participant) {} func onParticipantStoppedRecording(participant: Participant) {} } ``` ## Participant Object The `Participant` object contains information about each call participant: | Property | Type | Description | | - | - | - | | `uid` | `String?` | CometChat user ID — the identifier every moderator action takes | | `name` | `String?` | Display name | | `avatar` | `String?` | URL of avatar image | | `mid` | `String?` | Media ID for this call session | | `state` | `String?` | Participant state as reported by the server | | `isJoined` | `Bool?` | Whether the participant is currently joined | | `joinedAt` | `Int?` | Join timestamp | | `leftAt` | `Int?` | Leave timestamp | | `deviceID` | `String?` | Device identifier | | `totalAudioMinutes` | `Double?` | Audio minutes consumed | | `totalVideoMinutes` | `Double?` | Video minutes consumed | | `totalDurationInMinutes` | `Double?` | Total session minutes | > [!NOTE] > > **Every property is Optional.** `Participant` carries no mute / video / pin / hand-raise / > screen-share flags, and the SDK exposes no getter for them — track that state in your own app > from the [participant events](/docs/calls/ios/events). Because the events fire only on change, a > client that joins late cannot recover state that was already in effect. ## Hide Participant List Button To hide the participant list button in the call UI: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .hideParticipantListButton(true) .build() ``` # Picture-in-Picture Source: https://www.cometchat.com/docs/calls/ios/picture-in-picture Configure picture-in-picture for CometChat Calls SDK v5 on iOS to keep video calls visible while users multitask. Enable Picture-in-Picture (PiP) mode to allow users to continue their call in a floating window while using other apps. PiP provides a seamless multitasking experience during calls. > [!WARNING] > > **`enablePictureInPictureLayout()` alone does nothing visible.** It only tells the call UI to > re-lay-out for a smaller window — it does not create, move or float a window. Something has to > provide the small window, and there are two different ways to do that. Pick one before you write > any code. ## Two kinds of Picture-in-Picture | | In-app PiP | System PiP | | - | - | - | | **What the user sees** | A small draggable call tile floating over **your own app** | A floating window over **other apps** and the Home Screen | | **Who provides the window** | **`PiPViewCoordinator`, shipped in the Calls SDK** | Apple's AVKit — **also implemented inside the Calls SDK**, behind an opt-in flag | | **Setup** | A few lines — see below | `SessionSettingsBuilder.enableIOSPictureInPicture(true)` + Background Modes; or wire `AVPictureInPictureController` yourself | | **Availability** | Any supported iOS version | iPhone iOS 15+, iPad iOS 9+ | In both cases you still call `enablePictureInPictureLayout()` / `disablePictureInPictureLayout()` so the SDK reshapes the call UI to match. > [!NOTE] > > **System PiP is implemented inside the Calls SDK**, not only in Apple's API: the 5.0.4 binary links > `AVKit` and carries the whole path (`AVPictureInPictureController`, > `AVPictureInPictureControllerContentSource`, `AVPictureInPictureVideoCallViewController`), gated > behind `SessionSettingsBuilder.enableIOSPictureInPicture(_:)`. Enable that flag and add the > **Background Modes → Audio, AirPlay, and Picture in Picture** capability. You can still host > `AVPictureInPictureController` yourself if you want full control over the window. ## In-app PiP with `PiPViewCoordinator` `PiPViewCoordinator` ships with the Calls SDK. Give it the same `UIView` you passed to `joinSession(container:)` and it turns that view into a draggable, tappable mini-call. > [tab] Swift > > ```swift theme={null} > import CometChatCallsSDK > > final class PiPCallViewController: UIViewController, PiPViewCoordinatorDelegate { > > private let callContainer = UIView() > private var pipCoordinator: PiPViewCoordinator? > > override func viewDidLoad() { > super.viewDidLoad() > > // The coordinator manages the SAME view the call is rendered into. > let coordinator = PiPViewCoordinator(withView: callContainer) > coordinator.delegate = self > coordinator.initialPositionInSuperView = .lowerRightCorner > coordinator.dragBoundInsets = UIEdgeInsets(top: 25, left: 8, bottom: 8, right: 8) > > // Pass the parent explicitly — with no argument it falls back to the key window. > coordinator.configureAsStickyView(withParentView: view) > coordinator.show() > pipCoordinator = coordinator > > // ...then join the session into `callContainer` as usual. > } > > /// Shrink to the floating tile. > func enterPiP() { > pipCoordinator?.enterPictureInPicture() // resize + enable dragging + exit button > CallSession.shared.enablePictureInPictureLayout() // reshape the call UI to match > } > > /// Called by the coordinator AFTER it has already restored the full-size view — > /// this is a notification that PiP ended, not a request to end it. > func exitPictureInPicture() { > CallSession.shared.disablePictureInPictureLayout() > } > > /// Keep the tile inside the screen on rotation or a size change. > override func viewWillTransition(to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator) { > super.viewWillTransition(to: size, with: coordinator) > coordinator.animate { [weak self] _ in > guard let self else { return } > self.pipCoordinator?.resetBounds(bounds: CGRect(origin: .zero, size: size)) > } > } > } > ``` ### `PiPViewCoordinator` reference | Member | Purpose | | - | - | | `init(withView:)` | The view the call renders into — the same one given to `joinSession(container:)` | | `configureAsStickyView(withParentView:)` | Adds the view above everything in the parent. **Pass the parent explicitly**; with no argument it falls back to the key window | | `show(completion:)` / `hide(completion:)` | Fade in / out. `completion` is `AnimationCompletion` = `(Bool) -> Void` | | `enterPictureInPicture()` | Shrinks the view, enables the drag gesture, and adds a tap-to-reveal exit button | | `exitPictureInPicture()` | Restores full size, removes the drag gesture and exit button, then calls the delegate | | `resetBounds(bounds:)` | Call on rotation or any size change | | `stopDragGesture()` | Pin the tile in place | | `configureExitPiPButton(target:action:)` | Supply your own exit button | | `initialPositionInSuperView` | `.lowerRightCorner` (default) · `.upperRightCorner` · `.lowerLeftCorner` · `.upperLeftCorner` | | `dragBoundInsets` | How far the tile may be dragged toward each edge | | `delegate` | `PiPViewCoordinatorDelegate` — one method, `exitPictureInPicture()` | > [!NOTE] > > The tile size is fixed at 150px. The `c` property that used to set it is deprecated and ignored. ## How the SDK layout hook works 1. Something provides the small window — `PiPViewCoordinator` (in-app) or `AVPictureInPictureController` (system) 2. You notify the Calls SDK by calling `enablePictureInPictureLayout()` 3. The SDK adjusts the call UI to fit the smaller window (hides controls, optimizes layout) 4. When exiting, call `disablePictureInPictureLayout()` to restore the full UI ## Enable Picture-in-Picture Enter PiP mode programmatically using the `enablePictureInPictureLayout()` action: ```swift theme={null} CallSession.shared.enablePictureInPictureLayout() ``` ## Disable Picture-in-Picture Exit PiP mode and return to the full-screen call interface: ```swift theme={null} CallSession.shared.disablePictureInPictureLayout() ``` ## Listen for PiP Events Monitor PiP mode transitions using `LayoutListener` to update your UI accordingly: ```swift theme={null} class CallViewController: UIViewController, LayoutListener { override func viewDidLoad() { super.viewDidLoad() CallSession.shared.addLayoutListener(self) } deinit { CallSession.shared.removeLayoutListener(self) } func onPictureInPictureLayoutEnabled() { print("Entered PiP mode") // Hide custom overlays or controls hideCustomControls() } func onPictureInPictureLayoutDisabled() { print("Exited PiP mode") // Show custom overlays or controls showCustomControls() } func onCallLayoutChanged(layoutType: LayoutType) {} func onParticipantListVisible() {} func onParticipantListHidden() {} } ``` ## System PiP setup (floating over other apps) Only needed for System PiP — In-app PiP via `PiPViewCoordinator` requires none of this. **1. Enable Background Modes** In your project's **Signing & Capabilities**, add the **Background Modes** capability and enable: * Audio, AirPlay, and Picture in Picture **2. Configure AVAudioSession** ```swift theme={null} import AVFoundation func configureAudioSession() { do { try AVAudioSession.sharedInstance().setCategory( .playAndRecord, mode: .videoChat, options: [.allowBluetooth, .defaultToSpeaker] ) try AVAudioSession.sharedInstance().setActive(true) } catch { print("Failed to configure audio session: \(error)") } } ``` > [!NOTE] > > PiP mode is available on iOS 14.0 and later for iPhones, and iOS 9.0 and later for iPads. # Raise Hand Source: https://www.cometchat.com/docs/calls/ios/raise-hand Add raise hand behavior in CometChat Calls SDK v5 on iOS so participants can request attention during group calls. Allow participants to raise their hand to get attention during calls. This feature is useful for large meetings, webinars, or any scenario where participants need to signal they want to speak. ## Raise Hand Signal that you want to speak or get attention: ```swift theme={null} CallSession.shared.raiseHand() ``` ## Lower Hand Remove the raised hand indicator: ```swift theme={null} CallSession.shared.lowerHand() ``` ## Listen for Raise Hand Events Monitor when participants raise or lower their hands using `ParticipantEventListener`: ```swift theme={null} class CallViewController: UIViewController, ParticipantEventListener { override func viewDidLoad() { super.viewDidLoad() CallSession.shared.addParticipantEventListener(self) } deinit { CallSession.shared.removeParticipantEventListener(self) } func onParticipantHandRaised(participant: Participant) { print("\(participant.name ?? "") raised their hand") // Show notification or visual indicator showHandRaisedNotification(participant) } func onParticipantHandLowered(participant: Participant) { print("\(participant.name ?? "") lowered their hand") // Remove notification or visual indicator hideHandRaisedIndicator(participant) } // Other callbacks... func onParticipantJoined(participant: Participant) {} func onParticipantLeft(participant: Participant) {} func onParticipantListChanged(participants: [Participant]) {} func onParticipantAudioMuted(participant: Participant) {} func onParticipantAudioUnmuted(participant: Participant) {} func onParticipantVideoPaused(participant: Participant) {} func onParticipantVideoResumed(participant: Participant) {} func onParticipantStartedScreenShare(participant: Participant) {} func onParticipantStoppedScreenShare(participant: Participant) {} func onParticipantStartedRecording(participant: Participant) {} func onParticipantStoppedRecording(participant: Participant) {} func onDominantSpeakerChanged(participant: Participant) {} } ``` ## Track Raised Hands `Participant` carries **no** raised-hand property, and the SDK exposes no getter for one. Keep an ordered list of your own, driven by the `onParticipantHandRaised` / `onParticipantHandLowered` callbacks. > [!WARNING] > > These callbacks fire only when a hand goes **up or down**. A client that joins mid-call cannot > discover hands that were already raised before it joined. ```swift theme={null} // Raised hands, oldest first. Keyed by uid, because that is the only identifier // `Participant` actually carries. private var raisedHands: [(uid: String, name: String, at: Date)] = [] func onParticipantHandRaised(participant: Participant) { guard let uid = participant.uid else { return } DispatchQueue.main.async { guard !self.raisedHands.contains(where: { $0.uid == uid }) else { return } self.raisedHands.append((uid, participant.name ?? uid, Date())) self.updateRaisedHandsList(self.raisedHands) } } func onParticipantHandLowered(participant: Participant) { guard let uid = participant.uid else { return } DispatchQueue.main.async { self.raisedHands.removeAll { $0.uid == uid } self.updateRaisedHandsList(self.raisedHands) } } // Someone who leaves should not stay in the queue. func onParticipantLeft(participant: Participant) { guard let uid = participant.uid else { return } DispatchQueue.main.async { self.raisedHands.removeAll { $0.uid == uid } self.updateRaisedHandsList(self.raisedHands) } } ``` ## Hide Raise Hand Button To disable the raise hand feature, hide the button in the call UI: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .hideRaiseHandButton(true) .build() ``` # Recording Source: https://www.cometchat.com/docs/calls/ios/recording Use CometChat Calls SDK v5 recording on iOS to start, stop, access, and manage recordings for supported call sessions. Record call sessions for later playback. Recordings are stored server-side and can be accessed through call logs or the CometChat Dashboard. > [!NOTE] > > Recording is enabled by default on all CometChat apps. Start it automatically with `enableAutoStartRecording(true)`, or let users start it from the recording button. Recordings are available in the Dashboard under **Calls → Call Logs**, through [Call Logs](/docs/calls/ios/call-logs), and via the [Call Logs API](/docs/rest-api/calls-apis/list-calls). ## Start Recording Start recording during an active call session: ```swift theme={null} CallSession.shared.startRecording() ``` All participants are notified when recording starts. ## Stop Recording Stop an active recording: ```swift theme={null} CallSession.shared.stopRecording() ``` ## Auto-Start Recording Configure calls to automatically start recording when the session begins: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .enableAutoStartRecording(true) .build() ``` > [!NOTE] > > **A recording runs until it is stopped.** Whether it was started manually or automatically through `enableAutoStartRecording`, it keeps running until someone stops it. If nobody does, it stops on its own when either: > > * Everyone leaves the session — the recording ends about a minute later. > * Everyone in the session stays muted for 10 minutes. ## Hide Recording Button Hide the recording button from the default call UI: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .hideRecordingButton(true) .build() ``` ## Listen for Recording Events Monitor recording state changes using `MediaEventsListener`: ```swift theme={null} class CallViewController: UIViewController, MediaEventsListener { override func viewDidLoad() { super.viewDidLoad() CallSession.shared.addMediaEventsListener(self) } deinit { CallSession.shared.removeMediaEventsListener(self) } func onRecordingStarted() { print("Recording started") showRecordingIndicator() } func onRecordingStopped() { print("Recording stopped") hideRecordingIndicator() } // Other callbacks... func onAudioMuted() {} func onAudioUnMuted() {} func onVideoPaused() {} func onVideoResumed() {} func onAudioModeChanged(audioMode: AudioMode) {} func onCameraFacingChanged(cameraFacing: CameraFacing) {} } ``` ## Track Participant Recording Monitor when other participants start or stop recording using `ParticipantEventListener`: ```swift theme={null} class CallViewController: UIViewController, ParticipantEventListener { override func viewDidLoad() { super.viewDidLoad() CallSession.shared.addParticipantEventListener(self) } func onParticipantStartedRecording(participant: Participant) { print("\(participant.name ?? "") started recording") } func onParticipantStoppedRecording(participant: Participant) { print("\(participant.name ?? "") stopped recording") } // Other callbacks... } ``` ## Access Recordings Recordings are available after the call ends. You can access them in two ways: 1. **CometChat Dashboard**: Navigate to **Calls > Call Logs** in your [CometChat Dashboard](https://app.cometchat.com) to view and download recordings. 2. **Programmatically**: Fetch recordings through [Call Logs](/docs/calls/ios/call-logs). ## Recording Object | Property | Type | Description | | - | - | - | | `rid` | String | Unique recording identifier | | `recordingURL` | String | URL to download/stream the recording | | `startTime` | Int | Timestamp when recording started | | `endTime` | Int | Timestamp when recording ended | | `duration` | Double | Recording duration in seconds | # Ringing Source: https://www.cometchat.com/docs/calls/ios/ringing Ring users on iOS with the CometChat Calls SDK and the Push Notifications SDK: start a call, show it ringing, answer, decline, cancel and end it, with the app in any state. Ringing lets one user call another and lets the callee answer or decline, whether the callee's app is in the foreground, in the background, not running at all, or the phone is locked. Two SDKs do the work: | SDK | Owns | | - | - | | **Calls SDK** (`CometChatCallsSDK` 5.1+) | Creating the call, the media session, answering, declining, cancelling, ending, and the call events your code listens to | | **Push Notifications SDK, Calls product** (`CometChatPushNotificationsCalls` 2.0+) | Ringing the callee's device: the VoIP push (PushKit), the system incoming-call screen (CallKit), the ringtone, the ring timeout, missed calls in Recents, busy and call waiting. It also reports outgoing calls to CallKit; CallKit owns a call's audio while the call is on CallKit | > [!NOTE] > > **Coming from the earlier ringing flow?** The Chat SDK's calling methods (`CometChat.initiateCall`, `acceptCall`, `rejectCall`, `endCall`, `CometChatCallDelegate`) are superseded by the Calls SDK and no longer used; a coming Chat SDK release marks them deprecated. This page describes the replacement. See [Migrating from legacy ringing](/docs/calls/ios/migrating-from-legacy-ringing) for a method-by-method mapping. ## How ringing works The caller creates the call with the Calls SDK. The CometChat backend sends a VoIP push to the callee. The Push SDK reports the call to CallKit, which rings the device, and when the callee answers, your call screen joins the session. The caller's app learns that the callee is ringing and has answered from the Calls SDK, without joining the session first. ```mermaid theme={null} sequenceDiagram participant A as Caller app participant BE as CometChat backend participant P as Callee · Push SDK participant C as Callee · Calls SDK A->>BE: CometChatCalls.initiateCall(receiver:options:) Note over A: Session prepared, not joined ("Calling…") BE-->>P: VoIP push (callAction = initiated) P->>P: Ring: CallKit incoming-call screen, ringtone P->>C: connect(sessionID:) — pre-warms the session C-->>A: onParticipantConnected → "Ringing…" P->>P: Answer (CallKit) → presentCall(_:) on your delegate C->>C: joinSession(sessionID:) C-->>A: onParticipantJoined → caller joins too Note over A,C: In call. Hang up with CallSession.shared.leave() ``` What each side sees: | Stage | Caller | Callee | | - | - | - | | Call created | `initiateCall` succeeds; show "Calling…" | VoIP push arrives; CallKit rings | | Callee's device reached | `onParticipantConnected` → show "Ringing…" | Ringing | | Callee answers | `onParticipantJoined` → `joinSession` | `presentCall(_:)` → your call screen → `joinSession` | | Callee declines / is busy / does not answer | Not reliably reported. `onConnectionClosed` fires only when the callee's device had prepared the session; a busy decline, or a decline before the callee's device connected, closes nothing. Poll the [call's status](/docs/calls/ios/call-logs#check-one-call) while ringing, and keep your [ring timer](#ring-timeout) | Ring stops; `callDidEnd(_:reason:)`; a missed call in Recents if unanswered | | Caller cancels | — (you ended it) | Ring stops; `onIncomingCallEnded` with `cancelled`, or `ended` when the callee's device had prepared the session; a missed call in Recents | | Either side hangs up | `onParticipantLeft` / `onSessionLeft` | same | > [!NOTE] > > On iOS the caller is not told when, or why, the callee ended the call: `onIncomingCallEnded` is not reported for your own outgoing call. A decline or ring-out closes the caller's prepared session (`onConnectionClosed`) only when the callee's device had prepared it. A busy decline never does (the callee is in another call and never joins the room), and neither does a decline made before the callee's device connected. So while the call rings, read its status from [Call Logs](/docs/calls/ios/call-logs) every few seconds and end the screen on `rejected`, `busy` or `unanswered`, as the [ring timer](#ring-timeout) does when nothing arrives. ## Prerequisites * [Calls SDK set up](/docs/calls/ios/setup) and the user [logged in](/docs/calls/ios/authentication). * Push notifications configured with the Push Notifications SDK 2.0 Core and Calls products. The whole push side of ringing is on the [Push ringing](/docs/calls/ios/voip-calling) page; this page assumes it is done. * `NSMicrophoneUsageDescription` and `NSCameraUsageDescription` in your `Info.plist`. Add the camera string even if your app only places audio calls: the Calls SDK links the camera. * The **Push Notifications** capability and **Background Modes → Voice over IP** on your app target. Without them PushKit delivers no VoIP push and a killed app cannot ring. * A physical device. PushKit and CallKit do not work in the Simulator. Add the packages with Swift Package Manager (**File → Add Package Dependencies** in Xcode): | Package | Version | Products | | - | - | - | | `https://github.com/cometchat/calls-sdk-ios` | Up to Next Major from 5.1.0 | `CometChatCallsSDK` | | `https://github.com/cometchat/push-notifications-sdk-ios` | Up to Next Major from 2.0.0 | `CometChatPushNotificationsSwift` (Core), `CometChatPushNotificationsCalls` (the PushKit + CallKit ringer) | > [!WARNING] > > Call `CometChatPushNotifications.shared.initialize(config:)` from `application(_:didFinishLaunchingWithOptions:)`. The Push SDK creates the PushKit registry inside `initialize`, and iOS only delivers the VoIP push that launched a killed app when that registry exists by the end of launch. Initialized any later, the first call after a cold start is lost. ## Start a call `CometChatCalls.initiateCall` creates the call on the backend, which rings the callee, and prepares the caller's media session. The caller does **not** join yet. ```swift theme={null} let options = InitiateCallOptions() options.type = CallSessionType.audio // or CallSessionType.video (the default) options.receiverType = CallReceiverType.user options.sessionSettings = SessionSettingsBuilder() .setSessionType(.voice) // .video for a video call .setPeerCall(true) // 1:1: the call ends for both when either leaves .build() CometChatCalls.initiateCall(receiver: receiverUid, options: options, onSuccess: { call in print("Calling \(call.receiver ?? ""), session \(call.sessionId)") DispatchQueue.main.async { self.showOutgoingScreen(call) self.listenOnPreparedSession(call) } }, onError: { error in print("Could not start the call: \(error?.errorDescription ?? "")") }) ``` | Parameter | Description | | - | - | | `receiver` | UID of the user to call | | `options.type` | `CallSessionType.audio` or `CallSessionType.video` (default) | | `options.receiverType` | `CallReceiverType.user` (default), or `CallReceiverType.group` with the group's GUID as `receiver` (see [Group calls](#group-calls)) | | `options.sessionSettings` | The settings the caller's session is prepared with. See the warning below. | `InitiatedCall` gives you `sessionId`, `messageId` (the id of the call message in the conversation), `conversationId`, `sender`, `receiver`, `receiverType`, `type`, `status`, `initiatedAt` (in seconds) and `session`, the `CallSession` being prepared. `initiateCall` fails with `SESSION_ALREADY_ACTIVE` while the user is joining or in another call; leave that call first. > [!WARNING] > > **Always set the session type in `sessionSettings`.** The Calls SDK freezes the session settings when it prepares the session and its default is video, so an audio call started without `.setSessionType(.voice)` opens the caller's camera. The settings you pass here are the ones the caller later joins with. > > Build them with a new `SessionSettingsBuilder()`. `CometChatCalls.sessionSettingsBuilder` is a single shared builder whose `build()` returns the same object every time, so a setting made for one call carries into the next. > [!NOTE] > > There is no client-side ring timeout. The callee's device stops at the ring window the push carries (`ringTimeout`), or the Push SDK's default of 45 seconds, and ends a 1:1 call as `unanswered`; that closes the caller's prepared session only when the callee's device had prepared it. If the callee's device is never reached, nothing ends the caller's ringing until its prepared session expires after 5 minutes, so run your own timer on the caller and end the call as `unanswered` after the same window, as shown under [Ring timeout](#ring-timeout). ## Show "Ringing…" and detect the answer The caller stays on the session that `initiateCall` prepared and listens to it. Do not call `joinSession` yet: joining only when the callee has joined keeps the caller's media off until there is someone to talk to, and it is what makes the two events below arrive. Register on `CallSession.shared`. It is the session `initiateCall` is preparing (the same object `call.session` and `CometChatCalls.getActiveSession()` return), and registering on it works before the prepare has finished. ```swift theme={null} class OutgoingCallViewController: UIViewController, SessionStatusListener, ParticipantEventListener { var call: InitiatedCall! private var answered = false func listenOnPreparedSession(_ call: InitiatedCall) { self.call = call CallSession.shared.addSessionStatusListener(self) CallSession.shared.addParticipantEventListener(self) } // The callee's device received the push and is ringing. func onParticipantConnected(participant: Participant) { setStatus("Ringing…") } // The callee answered: now the caller joins. func onParticipantJoined(participant: Participant) { guard !answered else { return } answered = true removeListeners() // the call screen registers its own joinCallSession(sessionId: call.sessionId, isVideo: call.type == CallSessionType.video) } // The prepared session closed before anyone joined: the call is over. func onConnectionClosed() { closeOutgoingScreen() } func removeListeners() { CallSession.shared.removeSessionStatusListener(self) CallSession.shared.removeParticipantEventListener(self) } deinit { removeListeners() } } ``` | Event | On the prepared session it means | | - | - | | `onConnected` | Your own prepare finished; the join will be near-instant | | `onParticipantConnected(participant:)` | The callee's phone got the push and prepared the session: it is ringing there | | `onParticipantJoined(participant:)` | The callee answered. Call `joinSession` now | | `onConnectionClosed` | The prepared session closed before anyone joined: a decline or ring-out when the callee's device had prepared it, a cancel, the session dying, or the 5-minute expiry. A busy decline, or a decline before the callee's device connected, doesn't close it. `onSessionTimedOut` is not part of this: it only reports an idle joined session | The SDK holds these listeners weakly and does not remove them for you: remove them when the screen goes away, and when the call screen takes over. ## Listen for calls starting and ending `CometChatCalls.addIncomingCallListener` reports calls ringing on this device and their end. The Push SDK feeds it from the VoIP push, including in a launch the push started, provided you register the listener in `application(_:didFinishLaunchingWithOptions:)`: events are delivered only to listeners registered at that moment and are not replayed. On iOS it reports **incoming** calls only; your own outgoing call ends through the prepared session, as described above. ```swift theme={null} final class CallEvents: NSObject, CometChatIncomingCallListener { func onIncomingCallReceived(call: CometChatIncomingCall) { // A call for this user is ringing. CallKit already shows the ring; // use this for your own state (badge, analytics, refreshing a list). } func onIncomingCallEnded(call: CometChatIncomingCall, reason: String) { // The ring ended before it was answered here: the caller cancelled (often reported // as `ended`), it was answered on another device, it rang out, or the session closed. } } let callEvents = CallEvents() // the SDK holds listeners weakly: keep this reference CometChatCalls.addIncomingCallListener("my-screen", callEvents) // When the screen goes away: CometChatCalls.removeIncomingCallListener("my-screen") ``` | Reason | Meaning | | - | - | | `cancelled` | The caller gave up | | `ongoing` | Answered on another of the user's devices | | `unanswered` | The call rang out | | `rejected`, `busy` | Declined (on another device, or found declined when the session was prepared) | | `ended` | The session prepared for the call closed before the answer. A caller's cancel usually arrives as `ended` once the callee's device had prepared the session (the Push SDK's delegate then gets `callDidEnd` with `.declined`), so don't label it "Declined" in your UI | It fires once per call. Treat any other reason as "the ring is over". Answering on this device is not reported, and neither is a decline or ring-out on this device: those reach the Push SDK delegate's `callDidEnd(_:reason:)`. `CometChatIncomingCall` carries `sessionId`, `callerUid`, `callerName`, `callerAvatarUrl`, `callType` (`audio` / `video`), `receiverType`, `receiverUid`, `conversationId`, `initiatedAt` (milliseconds), `isVideo` and `isPeerCall`. > [!WARNING] > > Listener ids are keys. Registering the same id twice replaces the first listener instead of adding a second one, so give each screen a stable id, and do not use `cometchat-push-notifications`: the Push SDK registers under that id. ## Answer a call CallKit shows the Answer button. When the user answers, the Push SDK calls `presentCall(_:)` on your `CometChatPushNotificationsCallsDelegate`. It fires immediately in every app state, the phone locked included (for End & Accept, once the previous call has left): present your call screen and join at once, so audio connects before the user unlocks. The Push SDK ends an answered call with `.failed` if the session has not joined within 20 seconds. If your UI may come up later than that, for example on an answer from the lock screen after a push started the app, don't wait for a window to join: create your call screen, call `joinSession` with its container view, and present it once a window exists. There is no separate "accept" call to make. > [tab] Swift > > ```swift theme={null} > import UIKit > import CometChatPushNotificationsSwift > import CometChatPushNotificationsCalls > > final class CallPushDelegate: NSObject, CometChatPushNotificationsCallsDelegate { > > private var pending: IncomingCall? > > // The user answered. Called at most once per session. > // Always return true: false ends the call at once. On a lock-screen or cold-launch answer > // the window may not exist yet, so keep the call and present it when the UI comes up. > func presentCall(_ call: IncomingCall) -> Bool { > guard let root = rootViewController() else { pending = call; return true } > present(call, on: root) > return true > } > > /// Call when your UI comes up, for example from sceneDidBecomeActive(_:). > func presentPendingCall() { > guard let call = pending, let root = rootViewController() else { return } > pending = nil > present(call, on: root) > } > > private func present(_ call: IncomingCall, on root: UIViewController) { > let screen = CallViewController(sessionId: call.sessionId, isVideo: call.isVideo) > screen.modalPresentationStyle = .fullScreen > root.present(screen, animated: false) // the screen joins in viewDidLoad > } > > // The call is over (never called for an answer): dismiss your screen. > func callDidEnd(_ call: IncomingCall, reason: CallEndReason) { > if pending?.sessionId == call.sessionId { pending = nil } > dismissCallScreen(for: call.sessionId) > } > } > > // In application(_:didFinishLaunchingWithOptions:), before initialize(config:). > // The Push SDK holds its delegate weakly, so keep this object alive. > CometChatPushNotifications.shared.delegate = pushDelegate > ``` > [tab] Objective-C > > ```objectivec theme={null} > @import CometChatPushNotificationsSwift; > @import CometChatPushNotificationsCalls; > @import CometChatPushNotificationsCallsCore; // IncomingCall, CallEndReason > > @interface CallPushDelegate : NSObject > @property (nonatomic, strong, nullable) IncomingCall *pending; > @end > > @implementation CallPushDelegate > > // The user answered. Called at most once per session. > // Always return YES: NO ends the call at once. On a lock-screen or cold-launch answer > // the window may not exist yet, so keep the call and present it when the UI comes up. > - (BOOL)presentCall:(IncomingCall *)call { > UIViewController *root = [self rootViewController]; > if (root == nil) { self.pending = call; return YES; } > [self present:call on:root]; > return YES; > } > > // Call when your UI comes up, for example from sceneDidBecomeActive:. > - (void)presentPendingCall { > UIViewController *root = [self rootViewController]; > if (self.pending == nil || root == nil) return; > IncomingCall *call = self.pending; > self.pending = nil; > [self present:call on:root]; > } > > - (void)present:(IncomingCall *)call on:(UIViewController *)root { > CallViewController *screen = [[CallViewController alloc] initWithSessionId:call.sessionId > isVideo:call.isVideo]; > screen.modalPresentationStyle = UIModalPresentationFullScreen; > [root presentViewController:screen animated:NO completion:nil]; // joins in viewDidLoad > } > > // The call is over (never called for an answer): dismiss your screen. > - (void)callDidEnd:(IncomingCall *)call reason:(CallEndReason)reason { > if ([self.pending.sessionId isEqualToString:call.sessionId]) self.pending = nil; > [self dismissCallScreenForSessionId:call.sessionId]; > } > > @end > ``` `IncomingCall` carries `sessionId`, `callerUid`, `callerName`, `callerAvatarUrl`, `callType`, `receiverType`, `receiverUid`, `conversationId`, `initiatedAtMs`, `ringTimeoutMs`, `isVideo` and `isPeerCall`. After `presentCall`, the Push SDK asks for the microphone (and the camera for a video call) if the user has not decided yet. On a lock-screen answer the prompt waits until the app is active; a denied microphone joins muted. To ask earlier yourself, turn this off with `requestCallPermissions(false)` on the push configuration. ## Join the session Both sides join the same way: the callee from the screen `presentCall` opened, the caller from `onParticipantJoined`. `joinSession` takes over the session that was prepared earlier, so it connects almost at once. On a prepared session the settings passed to `joinSession` are ignored: the ones frozen when the session was prepared apply. That is the caller's `options.sessionSettings` (if the prepare failed, `joinSession` joins directly with the settings it is given, so build those the same way, `setPeerCall(true)` included for a 1:1 call); the callee's session is prepared by the Push SDK with its own settings (the session type, the camera off for an audio call, the speaker, and peer call for a 1:1 call), so layout or hidden-button settings passed by the callee have no effect. ```swift theme={null} func joinCallSession(sessionId: String, isVideo: Bool) { let settings = SessionSettingsBuilder() .setSessionType(isVideo ? .video : .voice) .build() CometChatCalls.joinSession( sessionID: sessionId, callSetting: settings, container: callViewContainer, onSuccess: { _ in print("Joined \(sessionId)") }, onError: { error in print("Join failed: \(error?.errorDescription ?? "")") DispatchQueue.main.async { self.dismiss(animated: true) } } ) } ``` See [Join Session](/docs/calls/ios/join-session) for the container, [Session Settings](/docs/calls/ios/session-settings) for layouts and controls, and [Events](/docs/calls/ios/events) for everything the joined session reports. ## Decline a call Declining is handled by the Push SDK: CallKit's Decline button sends `endCall(sessionID:status:)` with `rejected`, and with `busy` instead when the user is already in another call. The decline goes through a queue that is replayed when the app next launches, if that is within 90 seconds, in case iOS suspends the app before it is sent. A group call's decline is local: nothing is sent. On the caller, the prepared session closes (`onConnectionClosed`) only if the callee's device had prepared it, and never for `busy`; so [read the status while it rings](/docs/calls/ios/call-logs#check-one-call). You only write decline code when you offer a Decline button of your own, for example on an in-app banner (Swift only): ```swift theme={null} CometChatPushNotificationsCalls.decline(sessionId: sessionId) ``` Without the Push SDK, decline through the Calls SDK directly: `CometChatCalls.endCall(sessionID: sessionId, status: EndCallStatus.rejected, onSuccess:onError:)`. ## Cancel a call The caller ends a call that is still ringing with `endCall` and the `cancelled` status. The SDK tears the caller's prepared session down first (your `onConnectionClosed` fires), then tells the server. The callee's ring stops and a missed call is left in Recents. ```swift theme={null} func cancelOutgoingCall(sessionId: String) { CometChatCalls.endCall(sessionID: sessionId, status: EndCallStatus.cancelled, onSuccess: { print("Cancelled \(sessionId)") }, onError: { error in print("Cancel failed: \(error?.errorDescription ?? "")") }) closeOutgoingScreen() // close locally either way } ``` Disable the End button after the first tap, and ignore an `onParticipantJoined` that arrives after you cancelled: the cancel wins. If the screen goes away before `initiateCall` has returned, cancel the call from its `onSuccess`, or the callee rings for a call nobody is waiting on. ## Ring timeout The callee's Push SDK ends an unanswered 1:1 call as `unanswered` when its ring window closes (45 seconds unless the push carries a `ringTimeout`), which closes the caller's prepared session if the callee's device had prepared it. To close the caller's screen at the same moment even when the callee's device was never reached, run your own timer from `initiateCall` and end the call with the same status. The Push SDK's default window is `RingConstants.defaultRingTimeoutMs` (45 000 ms), public in `CometChatPushNotificationsCalls`, so the caller's timer can use the same value: ```swift theme={null} let ringTimeout = DispatchWorkItem { [weak self] in guard let self = self, !self.answered else { return } CometChatCalls.endCall(sessionID: sessionId, status: EndCallStatus.unanswered, onSuccess: {}, onError: { _ in }) self.closeOutgoingScreen() } DispatchQueue.main.asyncAfter(deadline: .now() + 45, execute: ringTimeout) // On answer, cancel or close: ringTimeout.cancel() ``` ## End a call Hang up by leaving the session. The room tells the other side, which receives `onParticipantLeft` and then `onSessionLeft` or `onConnectionClosed`. No status needs to be sent and the call is logged by the backend. In a peer call (`setPeerCall(true)`), the session ends for both as soon as either leaves. ```swift theme={null} // The default call UI's End button leaves the session itself; only clean up here. func onLeaveSessionButtonClicked() { dismiss(animated: true) } // Your own hang-up control: func hangUp() { CallSession.shared.leave() dismiss(animated: true) } // The other participant (SessionStatusListener): func onSessionLeft() { dismiss(animated: true) } func onConnectionClosed() { dismiss(animated: true) } ``` Ending the call from the lock screen or CallKit's own UI makes the SDK leave the session, which reaches your screen as `onSessionLeft`. > [!NOTE] > > `CallSession.leaveSession()` is deprecated in 5.1; use `leave()`. Leave only the session your screen owns: after answering a second call over a live one, the first screen's clean-up must not leave the new session. ## Outgoing calls and CallKit CallKit owns the Calls SDK's audio only while it has a call: an answered incoming call, or an outgoing call reported to it, until the last one ends. The Push SDK reports an outgoing call to CallKit by itself once the Calls SDK prepares or joins its session, so outgoing calls get CallKit-owned audio too: they keep their audio through a cellular call, appear in Recents and can be ended from the lock screen. A session CallKit has no call for uses WebRTC's normal audio handling. When the Calls product is linked, don't set `CometChatAudioSession.callKitAudioEnabled` yourself; the Push SDK manages it. To show the callee's name and the call type from the start, report it yourself right after `initiateCall` succeeds (Swift only): ```swift theme={null} CometChatPushNotificationsCalls.reportOutgoingCall(sessionId: call.sessionId, calleeName: calleeName, hasVideo: isVideo) ``` See [Push ringing](/docs/calls/ios/voip-calling) for `reportCallConnected` and `reportCallEnded`. ## Second call while in a call Handled by CallKit and the Push SDK, the same way a phone does it. A call that arrives while the user is in another call rings with CallKit's call-waiting buttons. **End & Accept** ends the live call and answers the new one, so `presentCall(_:)` fires again with the new session: open a fresh screen for it. **Decline** sends `busy` and keeps the live call. A call that arrives while another one is still ringing replaces it. ## Group calls To ring a group, call `initiateCall` with the group's GUID as `receiver` and `options.receiverType = CallReceiverType.group`, and leave `setPeerCall` off so the call outlives any one member leaving. Every member's device rings through the push. You can also start a group call without ringing: share a session id (for example in a custom message) and have each member join it with `joinSession`. When a group call rings, declining it or letting it ring out sends nothing: the call carries on for the other members, and the decline is local to that device. ## Logout Log out of the Calls SDK when the user signs out (`CometChatCalls.logout`). On that logout the Push SDK stops a call still ringing for the old user and tries to unregister the push tokens. A Chat SDK logout does the same when the Push SDK's Chat product is linked. Unregistering needs the user's auth token, which may already be gone when the logout is reported, so call `CometChatPushNotifications.shared.unregisterTokens` and wait for it before logging out of either SDK. End or cancel any call of your own before logging out: `endCall` needs a logged-in user. ## Call status values | Status | Meaning | Sent by | | - | - | - | | `initiated` | Created, ringing | Backend, on `initiateCall` | | `ongoing` | Answered | Backend, when the callee joins | | `rejected` | Callee declined | Callee's Push SDK (`EndCallStatus.rejected`) | | `busy` | Callee was in another call | Callee's Push SDK (`EndCallStatus.busy`) | | `cancelled` | Caller ended it before an answer | Caller, `endCall` with `EndCallStatus.cancelled` | | `unanswered` | Nobody answered in the ring window | Callee's Push SDK for a 1:1 call (and optionally the caller's timer, `EndCallStatus.unanswered`) | | `ended` | Hung up after being answered | Backend, when the session ends | | `missed` | How an unanswered or cancelled incoming call appears in call logs | Call logs | ## Related * [Push ringing](/docs/calls/ios/voip-calling): dependencies, capabilities, `PNConfiguration`, PushKit and CallKit, the delegate, outgoing calls on CallKit, readiness checks and what happens when the app is killed. * [Migrating from legacy ringing](/docs/calls/ios/migrating-from-legacy-ringing). * [Events](/docs/calls/ios/events), [Actions](/docs/calls/ios/actions), [Call Logs](/docs/calls/ios/call-logs). # Screen Sharing Source: https://www.cometchat.com/docs/calls/ios/screen-sharing Add screen sharing in CometChat Calls SDK v5 on iOS with presenter controls, permissions, and in-call display behavior. View screen shares from other participants during a call. The iOS SDK can receive and display screen shares initiated from web clients. > [!NOTE] > > The iOS Calls SDK does not support initiating screen sharing. Screen sharing can only be started from web clients. iOS participants can view shared screens. ## How It Works When a web participant starts screen sharing: 1. The SDK receives the screen share stream 2. The call layout automatically adjusts to display the shared screen prominently 3. iOS participants can view the shared content ## Listen for Screen Share Events Monitor when participants start or stop screen sharing: ```swift theme={null} class CallViewController: UIViewController, ParticipantEventListener { override func viewDidLoad() { super.viewDidLoad() CallSession.shared.addParticipantEventListener(self) } deinit { CallSession.shared.removeParticipantEventListener(self) } func onParticipantStartedScreenShare(participant: Participant) { print("\(participant.name ?? "") started screen sharing") // Layout automatically adjusts to show shared screen } func onParticipantStoppedScreenShare(participant: Participant) { print("\(participant.name ?? "") stopped screen sharing") // Layout returns to normal view } // Other callbacks... func onParticipantJoined(participant: Participant) {} func onParticipantLeft(participant: Participant) {} func onParticipantListChanged(participants: [Participant]) {} func onParticipantAudioMuted(participant: Participant) {} func onParticipantAudioUnmuted(participant: Participant) {} func onParticipantVideoPaused(participant: Participant) {} func onParticipantVideoResumed(participant: Participant) {} func onParticipantStartedRecording(participant: Participant) {} func onParticipantStoppedRecording(participant: Participant) {} func onParticipantHandRaised(participant: Participant) {} func onParticipantHandLowered(participant: Participant) {} func onDominantSpeakerChanged(participant: Participant) {} } ``` ## Track Who Is Sharing `Participant` carries **no** screen-share property, and the SDK exposes no getter for one. Track the current presenter yourself from the start/stop callbacks. > [!WARNING] > > These callbacks fire only when a share **starts or stops**. A client that joins mid-call cannot > discover a share that was already in progress before it joined. ```swift theme={null} // uids of participants currently sharing. private var presenterUIDs = Set() func onParticipantStartedScreenShare(participant: Participant) { guard let uid = participant.uid else { return } DispatchQueue.main.async { self.presenterUIDs.insert(uid) print("\(participant.name ?? uid) started sharing their screen") } } func onParticipantStoppedScreenShare(participant: Participant) { guard let uid = participant.uid else { return } DispatchQueue.main.async { self.presenterUIDs.remove(uid) } } // A participant who leaves while sharing never sends a stop event. func onParticipantLeft(participant: Participant) { guard let uid = participant.uid else { return } DispatchQueue.main.async { self.presenterUIDs.remove(uid) } } ``` # SessionSettingsBuilder Source: https://www.cometchat.com/docs/calls/ios/session-settings Configure CometChat Calls SDK v5 session settings on iOS for call behavior, UI options, participant controls, and features. The `SessionSettingsBuilder` is a powerful configuration tool that allows you to customize every aspect of your call session before participants join. From controlling the initial audio/video state to customizing the UI layout and hiding specific controls, this builder gives you complete control over the call experience. Proper session configuration is crucial for creating a seamless user experience tailored to your application's specific needs. > [!NOTE] > > These are pre-session configurations that must be set before joining a call. Once configured, pass the `SessionSettings` object to the `joinSession()` method. Settings cannot be changed after the session has started, though many features can be controlled dynamically during the call using call actions. ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .setTitle("Team Meeting") .setDisplayName("John Doe") .setSessionType(.video) .setLayout(.tile) .startAudioMuted(false) .startVideoPaused(false) .build() ``` ## Session Settings ### Title **Method:** `setTitle(_ title: String)` Sets the title that appears in the call header. This helps participants identify the purpose or name of the call session. The title is displayed prominently at the top of the call interface. ```swift theme={null} .setTitle("Team Meeting") ``` | Parameter | Type | Default | | - | - | - | | `title` | String | nil | ### Display Name **Method:** `setDisplayName(_ name: String)` Sets the display name that will be shown to other participants in the call. This name appears on your video tile and in the participant list, helping others identify you during the session. ```swift theme={null} .setDisplayName("John Doe") ``` | Parameter | Type | Default | | - | - | - | | `name` | String | nil | ### Session Type **Method:** `setSessionType(_ sessionType: SessionType)` Defines the type of call session. Choose `.video` for video calls with camera enabled, or `.voice` for audio-only calls. This setting determines whether video streaming is enabled by default. ```swift theme={null} .setSessionType(.video) ``` | Parameter | Type | Default | | - | - | - | | `sessionType` | SessionType | .video | > [accordion] SessionType Values > > | Value | Description | > | - | - | > | `.video` | Video call with camera enabled | > | `.voice` | Audio-only call | ### Layout Mode **Method:** `setLayout(_ layoutType: LayoutType)` Sets the initial layout mode for displaying participants. `.tile` shows all participants in a grid, `.spotlight` focuses on the active speaker with others in a sidebar, and `.sidebar` displays the main speaker with participants in a side panel. ```swift theme={null} .setLayout(.tile) ``` | Parameter | Type | Default | | - | - | - | | `layoutType` | LayoutType | .tile | > [accordion] LayoutType Values > > | Value | Description | > | - | - | > | `.tile` | Grid layout showing all participants equally | > | `.spotlight` | Focus on active speaker with others in sidebar | > | `.sidebar` | Main speaker with participants in a sidebar | ### Idle Timeout Period **Method:** `setIdleTimeoutPeriod(_ timeoutSeconds: Int)` Configures the timeout duration in seconds before automatically ending the session when you're the only participant. This prevents sessions from running indefinitely when others have left. ```swift theme={null} .setIdleTimeoutPeriod(300) ``` | Parameter | Type | Default | | - | - | - | | `timeoutSeconds` | Int | 300 | ### Start Audio Muted **Method:** `startAudioMuted(_ muted: Bool)` Determines whether the microphone is muted when joining the session. Set to `true` to join with audio muted, requiring users to manually unmute. Useful for large meetings to prevent background noise. ```swift theme={null} .startAudioMuted(true) ``` | Parameter | Type | Default | | - | - | - | | `muted` | Bool | false | ### Start Video Paused **Method:** `startVideoPaused(_ muted: Bool)` Controls whether the camera is turned off when joining the session. Set to `true` to join with video disabled, allowing users to enable it when ready. Helpful for privacy or bandwidth considerations. ```swift theme={null} .startVideoPaused(true) ``` | Parameter | Type | Default | | - | - | - | | `muted` | Bool | false | ### Audio Mode **Method:** `setAudioMode(_ audioMode: AudioMode)` Sets the initial audio output device for the call. Options include `.speaker` for loudspeaker, `.earpiece` for phone earpiece, `.bluetooth` for connected Bluetooth devices, or `.headphones` for wired headphones. ```swift theme={null} .setAudioMode(.speaker) ``` | Parameter | Type | Default | | - | - | - | | `audioMode` | AudioMode | .speaker | > [accordion] AudioMode Values > > | Value | Description | > | - | - | > | `.speaker` | Device loudspeaker | > | `.earpiece` | Phone earpiece | > | `.bluetooth` | Connected Bluetooth device | > | `.headphones` | Wired headphones | ### Initial Camera Facing **Method:** `setInitialCameraFacing(_ initialCameraFacing: CameraFacing)` Specifies which camera to use when starting the session. Choose `.FRONT` for the front-facing camera (selfie mode) or `.REAR` for the rear camera. Users can switch cameras during the call. ```swift theme={null} .setInitialCameraFacing(.FRONT) ``` | Parameter | Type | Default | | - | - | - | | `initialCameraFacing` | CameraFacing | .FRONT | > [accordion] CameraFacing Values > > | Value | Description | > | - | - | > | `.FRONT` | Front-facing camera | > | `.REAR` | Rear camera | ### Auto Start Recording **Method:** `enableAutoStartRecording(_ enabled: Bool)` Automatically starts recording the session as soon as it begins. When enabled, recording starts without manual intervention, ensuring the entire session is captured from the start. ```swift theme={null} .enableAutoStartRecording(true) ``` | Parameter | Type | Default | | - | - | - | | `enabled` | Bool | false | ### Auto Start Transcription *Available since v5.0.4* **Method:** `enableAutoStartTranscription(_ enabled: Bool)` Automatically starts transcribing the session as soon as it begins. See [Transcription](/docs/calls/ios/transcription) for details. ```swift theme={null} .enableAutoStartTranscription(true) ``` | Parameter | Type | Default | | - | - | - | | `enabled` | Bool | false | ### Caption Language *Available since v5.0.4* **Method:** `setCaptionLanguage(_ captionLanguage: String)` Sets the language used for transcription and closed captions. See [Transcription](/docs/calls/ios/transcription#caption-language) for the full list of supported codes. ```swift theme={null} .setCaptionLanguage("en-US") ``` | Parameter | Type | Default | | - | - | - | | `captionLanguage` | String | en-US | ### Hide Control Panel **Method:** `hideControlPanel(_ hidden: Bool)` Hides the bottom control bar that contains call action buttons. Set to `true` to remove the control panel entirely, useful for custom UI implementations or view-only modes. ```swift theme={null} .hideControlPanel(true) ``` | Parameter | Type | Default | | - | - | - | | `hidden` | Bool | false | ### Hide Header Panel **Method:** `hideHeaderPanel(_ hidden: Bool)` Hides the top header bar that displays the call title and session information. Set to `true` to maximize the video viewing area or implement a custom header. ```swift theme={null} .hideHeaderPanel(true) ``` | Parameter | Type | Default | | - | - | - | | `hidden` | Bool | false | ### Hide Session Timer **Method:** `hideSessionTimer(_ hidden: Bool)` Hides the session duration timer that shows how long the call has been active. Set to `true` to remove the timer display from the interface. ```swift theme={null} .hideSessionTimer(true) ``` | Parameter | Type | Default | | - | - | - | | `hidden` | Bool | false | ### Hide Leave Session Button **Method:** `hideLeaveSessionButton(_ hidden: Bool)` Hides the button that allows users to leave or end the call. Set to `true` to remove this button, requiring an alternative method to exit the session. ```swift theme={null} .hideLeaveSessionButton(true) ``` | Parameter | Type | Default | | - | - | - | | `hidden` | Bool | false | ### Hide Toggle Audio Button **Method:** `hideToggleAudioButton(_ hidden: Bool)` Hides the microphone mute/unmute button from the control panel. Set to `true` to remove audio controls, useful when audio control should be managed programmatically. ```swift theme={null} .hideToggleAudioButton(true) ``` | Parameter | Type | Default | | - | - | - | | `hidden` | Bool | false | ### Hide Toggle Video Button **Method:** `hideToggleVideoButton(_ hidden: Bool)` Hides the camera on/off button from the control panel. Set to `true` to remove video controls, useful for audio-only calls or custom video control implementations. ```swift theme={null} .hideToggleVideoButton(true) ``` | Parameter | Type | Default | | - | - | - | | `hidden` | Bool | false | ### Hide Switch Camera Button **Method:** `hideSwitchCameraButton(_ enabled: Bool)` Hides the button that allows switching between front and rear cameras. Set to `true` to remove this control, useful for devices with single cameras or fixed camera requirements. ```swift theme={null} .hideSwitchCameraButton(true) ``` | Parameter | Type | Default | | - | - | - | | `enabled` | Bool | false | ### Hide Recording Button **Method:** `hideRecordingButton(_ enabled: Bool)` Hides the recording start/stop button from the control panel. Set to `false` to show the recording button, allowing users to manually control session recording. ```swift theme={null} .hideRecordingButton(false) ``` | Parameter | Type | Default | | - | - | - | | `enabled` | Bool | true | ### Hide Transcription Button *Available since v5.0.4* **Method:** `hideTranscriptionButton(_ hidden: Bool)` Hides the transcription start/stop item from the control panel's **More** menu. Set to `false` to show it, allowing users to manually control session transcription. ```swift theme={null} .hideTranscriptionButton(false) ``` | Parameter | Type | Default | | - | - | - | | `hidden` | Bool | true | ### Hide Closed Caption Button *Available since v5.0.4* **Method:** `hideClosedCaptionButton(_ hidden: Bool)` Hides the closed-caption item from the control panel's **More** menu. Set to `false` to show it, allowing users to toggle the live captions overlay. Captions only appear while transcription is running. ```swift theme={null} .hideClosedCaptionButton(false) ``` | Parameter | Type | Default | | - | - | - | | `hidden` | Bool | true | ### Hide Audio Mode Button **Method:** `hideAudioModeButton(_ enabled: Bool)` Hides the button that toggles between speaker, earpiece, and other audio output modes. Set to `true` to remove audio mode controls from the interface. ```swift theme={null} .hideAudioModeButton(true) ``` | Parameter | Type | Default | | - | - | - | | `enabled` | Bool | false | ### Hide Raise Hand Button **Method:** `hideRaiseHandButton(_ enabled: Bool)` Hides the raise hand button that participants use to signal they want to speak. Set to `true` to remove this feature from the interface. ```swift theme={null} .hideRaiseHandButton(true) ``` | Parameter | Type | Default | | - | - | - | | `enabled` | Bool | false | ### Hide Share Invite Button **Method:** `hideShareInviteButton(_ enabled: Bool)` Hides the button that allows sharing session invite links with others. Set to `false` to show the invite button, enabling easy participant invitation. ```swift theme={null} .hideShareInviteButton(false) ``` | Parameter | Type | Default | | - | - | - | | `enabled` | Bool | true | ### Hide Participant List Button **Method:** `hideParticipantListButton(_ hidden: Bool)` Hides the button that opens the participant list view. Set to `true` to remove access to the participant list, useful for simplified interfaces. ```swift theme={null} .hideParticipantListButton(true) ``` | Parameter | Type | Default | | - | - | - | | `hidden` | Bool | false | ### Hide Change Layout Button **Method:** `hideChangeLayoutButton(_ hidden: Bool)` Hides the button that allows switching between different layout modes (tile, spotlight, sidebar). Set to `true` to lock the layout to the initial setting. ```swift theme={null} .hideChangeLayoutButton(true) ``` | Parameter | Type | Default | | - | - | - | | `hidden` | Bool | false | ### Hide Chat Button **Method:** `hideChatButton(_ hidden: Bool)` Hides the button that opens the in-call chat interface. Set to `false` to show the chat button, enabling text communication during calls. ```swift theme={null} .hideChatButton(false) ``` | Parameter | Type | Default | | - | - | - | | `hidden` | Bool | true | > [accordion] Enum Values > > | Enum | Value | Description | > | - | - | - | > | `SessionType` | `.video` | Video call with camera enabled | > | | `.voice` | Audio-only call | > | `LayoutType` | `.tile` | Grid layout showing all participants equally | > | | `.spotlight` | Focus on active speaker with others in sidebar | > | | `.sidebar` | Main speaker with participants in a sidebar | > | `AudioMode` | `.speaker` | Device loudspeaker | > | | `.earpiece` | Phone earpiece | > | | `.bluetooth` | Connected Bluetooth device | > | | `.headphones` | Wired headphones | > | `CameraFacing` | `.FRONT` | Front-facing camera | > | | `.REAR` | Rear camera | # Setup Source: https://www.cometchat.com/docs/calls/ios/setup Set up CometChat Calls SDK v5 for iOS with installation, app credentials, initialization, authentication, and the push dependencies needed for ringing. > [!NOTE] > > **Faster Integration with UI Kits** > > If you're using CometChat UI Kits, voice and video calling can be quickly integrated: > > * Incoming & outgoing call screens > * Call buttons with one-tap calling > * Call logs with history > > 👉 [iOS UI Kit Calling Integration](/docs/ui-kit/ios/calling-integration) > > Use this Calls SDK directly only if you need custom call UI or advanced control. This guide walks you through installing the CometChat Calls SDK and initializing it in your iOS application. ## Add the CometChat Dependency The Calls SDK 5.1 is distributed with Swift Package Manager. It needs iOS 15.1 or later. 1. In Xcode, go to **File > Add Package Dependencies** 2. Enter the repository URL: `https://github.com/cometchat/calls-sdk-ios` 3. Select **Up to Next Major Version** from `5.1.0` and add the `CometChatCallsSDK` product to your target > [!NOTE] > > The Calls SDK's API is Swift only: it doesn't ship an Objective-C interface. An Objective-C app calls it from Swift code in the same target. The Push Notifications SDK, which rings calls, supports Objective-C. > [!NOTE] > > **Ringing users?** Incoming calls ring through the Push Notifications SDK 2.0: add its Core and Calls products > (`CometChatPushNotificationsSwift` and `CometChatPushNotificationsCalls`) as well, and follow > [Push Ringing](/docs/calls/ios/voip-calling). The Calls SDK alone can start, join and end calls, but it cannot ring a > device that is not running your app. ## Add Permissions Add the required permissions to your `Info.plist`: ```xml theme={null} NSCameraUsageDescription Camera access is required for video calls NSMicrophoneUsageDescription Microphone access is required for voice and video calls ``` > [!NOTE] > > iOS requires you to provide a description for why your app needs camera and microphone access. These descriptions are shown to users when requesting permissions. Add both strings even if your app only makes audio calls: the Calls SDK links the camera. Request camera and microphone access before starting or joining a call. When a call is answered from the Push SDK's CallKit ring, the Push SDK asks for them after Answer (on a locked phone, once the user unlocks); a denied microphone joins muted. ## Enable Background Modes For calls to continue when the app is in the background, enable the following background modes in your project's **Signing & Capabilities**: 1. Select your target in Xcode 2. Go to **Signing & Capabilities** 3. Click **+ Capability** and add **Background Modes** 4. Enable: * **Audio, AirPlay, and Picture in Picture** * **Voice over IP** (required for ringing: without it PushKit delivers no VoIP push) Ringing also needs the **Push Notifications** capability. PushKit and CallKit only work on a physical device. ## Declare a Window on Your AppDelegate The Calls SDK reads `window` from your app delegate when the device orientation changes. Xcode's default scene-based template puts `window` only on the `SceneDelegate`, so without it the app crashes with `-[AppDelegate window]: unrecognized selector sent to instance` when a call starts, typically right after the camera permission prompt. Declare the property on your `AppDelegate`, even if you set the window up in your `SceneDelegate`: ```swift theme={null} import UIKit @main class AppDelegate: UIResponder, UIApplicationDelegate { var window: UIWindow? // ... } ``` > [!NOTE] > > The property can stay `nil`. The SDK only needs your `AppDelegate` to respond to `window`. ## Initialize CometChat Calls The `init()` method initializes the SDK with your app credentials. Call this method once when your application starts, typically in your `AppDelegate` or app entry point. ### CallAppSettings The `CallAppSettings` class configures the SDK initialization: | Parameter | Type | Required | Description | | - | - | - | - | | `appId` | String | Yes | Your CometChat App ID | | `region` | String | Yes | Your app region — `us`, `eu` or `in` | ```swift theme={null} import CometChatCallsSDK let appId = "APP_ID" // Replace with your App ID let region = "REGION" // Replace with your Region ("us", "eu" or "in") let callAppSettings = CallAppSettingsBuilder() .set(appID: appId) .set(region: region) .build() CometChatCalls(callsAppSettings: callAppSettings, onSuccess: { message in print("CometChat Calls SDK initialized successfully") }, onError: { error in print("CometChat Calls SDK initialization failed: \(error?.errorDescription ?? "")") }) ``` | Parameter | Description | | - | - | | `callsAppSettings` | Configuration object with App ID and Region | | `onSuccess` | Closure called on successful initialization | | `onError` | Closure called if initialization fails | > [!WARNING] > > **Initialize once, at launch.** A later initialization replaces the app ID and region but does not log the user > out: the stored user and auth token stay, and belong to the first app. To switch to another app ID, call > `CometChatCalls.logout` first, then initialize with the new app ID and log in again. When a VoIP push starts your > app, the Push SDK may initialize the Calls SDK with the `appId` and `region` from its own configuration before your > code runs; your own initialization with the same values is harmless. # Share Invite Source: https://www.cometchat.com/docs/calls/ios/share-invite Add invite sharing in CometChat Calls SDK v5 on iOS so users can share call links and bring participants into sessions. Enable participants to invite others to join a call by sharing a meeting link. The share invite button opens the system share sheet, allowing users to send the invite via any messaging app, email, or social media. ## Overview The share invite feature: * Generates a shareable meeting link with session ID * Opens iOS's native share sheet * Works with any app that supports text sharing * Can be triggered from the default button or custom UI ```mermaid theme={null} flowchart LR A[Share Button] --> B[Generate Link] B --> C[Share Sheet] C --> D[Messages] C --> E[Mail] C --> F[AirDrop] C --> G[Other Apps] ``` ## Prerequisites * CometChat Calls SDK integrated ([Setup](/docs/calls/ios/setup)) * Active call session ([Join Session](/docs/calls/ios/join-session)) *** ## Step 1: Enable Share Button Configure session settings to show the share invite button: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .hideShareInviteButton(false) // Show the share button .build() ``` *** ## Step 2: Handle Share Button Click Listen for the share button click using `ButtonClickListener`: ```swift theme={null} private func setupShareButtonListener() { CallSession.shared.addButtonClickListener(self) } extension CallViewController: ButtonClickListener { func onShareInviteButtonClicked() { shareInviteLink() } } ``` *** ## Step 3: Generate and Share Link Create the meeting invite URL and open the share sheet: ```swift theme={null} private func shareInviteLink() { let inviteUrl = generateInviteUrl(sessionId: sessionId, meetingName: meetingName) let activityItems: [Any] = [ "Join my meeting: \(meetingName)", inviteUrl ] let activityVC = UIActivityViewController( activityItems: activityItems, applicationActivities: nil ) // For iPad if let popover = activityVC.popoverPresentationController { popover.sourceView = view popover.sourceRect = CGRect(x: view.bounds.midX, y: view.bounds.midY, width: 0, height: 0) popover.permittedArrowDirections = [] } present(activityVC, animated: true) } private func generateInviteUrl(sessionId: String, meetingName: String) -> URL { let encodedName = meetingName.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? meetingName // Replace with your app's deep link or web URL let urlString = "https://yourapp.com/join?sessionId=\(sessionId)&name=\(encodedName)" return URL(string: urlString)! } ``` *** ## Custom Share Message Customize the share message with more details: ```swift theme={null} private func shareInviteLink() { let inviteUrl = generateInviteUrl(sessionId: sessionId, meetingName: meetingName) let shareMessage = """ 📞 Join my meeting: \(meetingName) Click the link below to join: \(inviteUrl.absoluteString) Meeting ID: \(sessionId) """ let activityItems: [Any] = [shareMessage] let activityVC = UIActivityViewController( activityItems: activityItems, applicationActivities: nil ) // For iPad if let popover = activityVC.popoverPresentationController { popover.sourceView = view popover.sourceRect = CGRect(x: view.bounds.midX, y: view.bounds.midY, width: 0, height: 0) popover.permittedArrowDirections = [] } present(activityVC, animated: true) } ``` *** ## Deep Link Handling To allow users to join directly from the shared link, implement deep link handling in your app. ### Configure Universal Links Add Associated Domains capability in Xcode and configure your `apple-app-site-association` file on your server. ### Handle Deep Link ```swift theme={null} class SceneDelegate: UIResponder, UIWindowSceneDelegate { func scene(_ scene: UIScene, continue userActivity: NSUserActivity) { guard userActivity.activityType == NSUserActivityTypeBrowsingWeb, let url = userActivity.webpageURL else { return } handleDeepLink(url: url) } func scene(_ scene: UIScene, openURLContexts URLContexts: Set) { guard let url = URLContexts.first?.url else { return } handleDeepLink(url: url) } private func handleDeepLink(url: URL) { guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true), components.path == "/join" else { return } let queryItems = components.queryItems ?? [] let sessionId = queryItems.first(where: { $0.name == "sessionId" })?.value let meetingName = queryItems.first(where: { $0.name == "name" })?.value guard let sessionId = sessionId else { return } // Check if user is logged in if CometChat.getLoggedInUser() != nil { joinCall(sessionId: sessionId, meetingName: meetingName ?? "Meeting") } else { // Save params and redirect to login saveJoinParams(sessionId: sessionId, meetingName: meetingName) showLoginScreen() } } private func joinCall(sessionId: String, meetingName: String) { let callVC = CallViewController() callVC.sessionId = sessionId callVC.meetingName = meetingName callVC.modalPresentationStyle = .fullScreen window?.rootViewController?.present(callVC, animated: true) } private func saveJoinParams(sessionId: String, meetingName: String?) { UserDefaults.standard.set(sessionId, forKey: "pendingSessionId") UserDefaults.standard.set(meetingName, forKey: "pendingMeetingName") } private func showLoginScreen() { // Navigate to login } } ``` *** ## Custom Share Button If you want to use a custom share button instead of the default one, hide the default button and implement your own: ```swift theme={null} // Hide default share button let sessionSettings = CometChatCalls.sessionSettingsBuilder .hideShareInviteButton(true) .build() // Add your custom button customShareButton.addTarget(self, action: #selector(shareInviteLink), for: .touchUpInside) ``` *** ## Complete Example ```swift theme={null} class CallViewController: UIViewController { var sessionId: String = "" var meetingName: String = "" private let callContainer = UIView() override func viewDidLoad() { super.viewDidLoad() setupUI() setupShareButtonListener() joinCall() } private func setupUI() { view.backgroundColor = .black callContainer.translatesAutoresizingMaskIntoConstraints = false view.addSubview(callContainer) NSLayoutConstraint.activate([ callContainer.topAnchor.constraint(equalTo: view.topAnchor), callContainer.leadingAnchor.constraint(equalTo: view.leadingAnchor), callContainer.trailingAnchor.constraint(equalTo: view.trailingAnchor), callContainer.bottomAnchor.constraint(equalTo: view.bottomAnchor) ]) } private func setupShareButtonListener() { CallSession.shared.addButtonClickListener(self) } private func joinCall() { let sessionSettings = CometChatCalls.sessionSettingsBuilder .setTitle(meetingName) .hideShareInviteButton(false) .build() CometChatCalls.joinSession( sessionId: sessionId, sessionSettings: sessionSettings, view: callContainer ) { session in print("Joined call") } onError: { error in print("Join failed: \(error?.errorDescription ?? "")") } } @objc private func shareInviteLink() { let inviteUrl = generateInviteUrl(sessionId: sessionId, meetingName: meetingName) let shareMessage = "📞 Join my meeting: \(meetingName)\n\n\(inviteUrl.absoluteString)" let activityVC = UIActivityViewController( activityItems: [shareMessage], applicationActivities: nil ) if let popover = activityVC.popoverPresentationController { popover.sourceView = view popover.sourceRect = CGRect(x: view.bounds.midX, y: view.bounds.midY, width: 0, height: 0) popover.permittedArrowDirections = [] } present(activityVC, animated: true) } private func generateInviteUrl(sessionId: String, meetingName: String) -> URL { let encodedName = meetingName.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? meetingName return URL(string: "https://yourapp.com/join?sessionId=\(sessionId)&name=\(encodedName)")! } } extension CallViewController: ButtonClickListener { func onShareInviteButtonClicked() { shareInviteLink() } } ``` *** ## Related Documentation * [Events](/docs/calls/ios/events) - Button click events * [Session Settings](/docs/calls/ios/session-settings) - Configure share button visibility * [Join Session](/docs/calls/ios/join-session) - Join a call session # Transcription & Closed Captions Source: https://www.cometchat.com/docs/calls/ios/transcription Use CometChat Calls SDK v5 transcription on iOS to transcribe calls, show live closed captions, and retrieve transcripts after the call. > [!NOTE] > > **Available since v5.0.4** — transcription and closed captions require CometChat Calls SDK v5.0.4 or later for iOS. See [Setup](/docs/calls/ios/setup) to install or upgrade. Transcribe call sessions in real time and display live closed captions on screen. Transcripts are stored server-side and can be retrieved after the call using `TranscriptsRequest`. > [!WARNING] > > Transcription must be enabled for your CometChat app. Contact support if you need to enable this feature. ## How It Works Transcription and closed captions are two related but separate things: | Concept | What it does | | - | - | | **Transcription** | Server-side speech-to-text for the session. Starting it brings a transcriber into the call, which produces the transcript that is stored for later retrieval. | | **Closed captions** | The on-screen overlay that renders the live transcript as it arrives. Captions are produced from the running transcription, so they only appear while transcription is active. | Starting transcription is a prerequisite for captions — turning captions on without an active transcription shows nothing. ## Starting Transcription ### Auto-Start Transcription Configure transcription to start automatically when the session begins: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .enableAutoStartTranscription(true) .build() ``` **Default:** `false` ### Manual Transcription Control #### Start Transcription Begin transcribing during an active call: ```swift theme={null} CallSession.shared.startTranscription() ``` #### Stop Transcription Stop the current transcription. Any captions currently on screen are cleared: ```swift theme={null} CallSession.shared.stopTranscription() ``` ## Built-in UI Controls Both transcription controls live in the control panel's **More** menu, and both are hidden by default. ### Transcription Menu Item To show the transcription item: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .hideTranscriptionButton(false) .build() ``` **Default:** `true` The item toggles between **Start Transcription** and **Stop Transcription** based on the current state. ### Closed Caption Menu Item To show the closed-caption item: ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .hideClosedCaptionButton(false) .build() ``` **Default:** `true` The item toggles between **Show Captions** and **Hide Captions**. > [!NOTE] > > Captions are off by default, so the overlay appears only after the user turns them on **and** transcription is running for the session. Turning captions on before transcription starts shows nothing until the transcript begins arriving. ## Caption Language **Method:** `setCaptionLanguage(_ captionLanguage: String)` Sets the language used for transcription and captions. ```swift theme={null} let sessionSettings = CometChatCalls.sessionSettingsBuilder .setCaptionLanguage("en-US") .build() ``` **Default:** `en-US` > [accordion] Supported Language Codes > > | Code | Language | > | - | - | > | `en-US` | English (United States) | > | `de-DE` | German (Germany) | > | `en-GB` | English (United Kingdom) | > | `es-ES` | Spanish (Spain) | > | `fr-FR` | French (France) | > | `hi-IN` | Hindi (India) | > | `hu-HU` | Hungarian (Hungary) | > | `it-IT` | Italian (Italy) | > | `ja-JP` | Japanese (Japan) | > | `ko-KR` | Korean (South Korea) | > | `lt-LT` | Lithuanian (Lithuania) | > | `ms-MY` | Malay (Malaysia) | > | `nl-NL` | Dutch (Netherlands) | > | `pt-PT` | Portuguese (Portugal) | > | `ru-RU` | Russian (Russia) | > | `sv-SE` | Swedish (Sweden) | > | `tr-TR` | Turkish (Turkey) | > | `zh` | Chinese Mandarin (Simplified, China) | > | `zh-TW` | Chinese Mandarin (Traditional, Taiwan) | ## Retrieving Transcripts After a call, use `TranscriptsRequest` to list the transcript artifacts for a session. Each record is a **pointer to a downloadable transcript file**, not the transcript text itself. > [!NOTE] > > The SDK must be initialized with `CometChatCalls.init()` and a user must be logged in. The auth token is read from the logged-in user at fetch time, so it automatically tracks re-logins — there is no `set(authToken:)` on this builder. ### Building a Request ```swift theme={null} let request = TranscriptsRequest.TranscriptsBuilder() .set(sessionId: "v1.us.2547167fe69871fd.alice") // required .set(limit: 10) // optional .build() request.fetchNext(onSuccess: { transcripts in for transcript in transcripts { print(transcript.tid, transcript.transcriptUrl) } }, onError: { error in print("Error: \(error?.errorDescription ?? "")") }) ``` | Method | Required | Description | | - | - | - | | `set(sessionId: String)` | Yes | The session ID whose transcripts to fetch. A missing or empty value fails the fetch with `ERROR_SESSION_ID_NILL`. | | `set(limit: Int)` | No | Page size. Defaults to `30` and is clamped to the range `1`–`1000`. | | `build()` | Yes | Returns a `TranscriptsRequest`. | > [!NOTE] > > Callbacks are delivered on the main queue, so it is safe to update UI directly from them. ### Paginating A `TranscriptsRequest` is a stateful cursor. Create one per session ID and drive it with `fetchNext` and `fetchPrevious`: ```swift theme={null} let request = TranscriptsRequest.TranscriptsBuilder() .set(sessionId: sessionId) .set(limit: 10) .build() // Next page request.fetchNext(onSuccess: { transcripts in // [Transcript] — empty once the last page has been consumed }, onError: { error in print("Error: \(error?.errorDescription ?? "")") }) // Previous page request.fetchPrevious(onSuccess: { transcripts in // [Transcript] — empty on a fresh request, or when already at the first page }, onError: { error in print("Error: \(error?.errorDescription ?? "")") }) ``` * `fetchNext` delivers the next page, or an empty array when there are no more pages. A session with no transcripts delivers an empty array. * `fetchPrevious` delivers the previous page, or an empty array when already on the first page. It never requests a page below `1`. * The cursor is committed only from a successful response, so a failed fetch can simply be retried. * Only one fetch may be in flight per request instance. Calling `fetchNext` or `fetchPrevious` while another is pending fails with `ERROR_REQUEST_IN_PROGRESS`; the original call is unaffected and still completes. ### Transcript Properties | Property | Type | Description | | - | - | - | | `tid` | String | Transcript ID | | `mid` | String | Meeting ID | | `roomName` | String | Room name of the meeting | | `startTime` | Int | Meeting start time, in epoch **seconds** | | `endTime` | Int | Meeting end time, in epoch **seconds** | | `url` | String | Meeting URL | | `transcriptDate` | String | Transcript date | | `transcriptUrl` | String | URL of the downloadable transcript JSON | | `metaData` | \[String: Any] | The raw server entry, so fields not modelled above are still reachable | > [!NOTE] > > The server omits keys whose value is empty, so sparse records are normal and should not be treated as an error. Missing string fields arrive as `""` and missing numbers as `0`. A single entry that fails to parse is skipped rather than failing the whole page. ### Reading the Transcript Content `transcriptUrl` points at the transcript file. Fetch it yourself to read the actual utterances: ```swift theme={null} request.fetchNext(onSuccess: { transcripts in guard let transcript = transcripts.first, let url = URL(string: transcript.transcriptUrl), !transcript.transcriptUrl.isEmpty else { return } URLSession.shared.dataTask(with: url) { data, _, _ in guard let data = data else { return } let content = try? JSONSerialization.jsonObject(with: data) print(content ?? "") }.resume() }, onError: { error in print("Error: \(error?.errorDescription ?? "")") }) ``` ### Error Handling Failures are delivered to the `onError` closure as a `CometChatCallException` carrying an `errorCode`: | Condition | `errorCode` | | - | - | | `CometChatCalls.init()` was not called | `INIT_NOT_CALLED` | | No logged-in user / empty auth token | `ERROR_NILL_AUTH_TOKEN` | | `sessionId` missing or empty | `ERROR_SESSION_ID_NILL` | | A fetch is already in flight | `ERROR_REQUEST_IN_PROGRESS` | | No network | `ERROR_INTERNET_UNAVAILABLE` | | Missing or malformed response | `ERROR_JSON_EXCEPTION` | | Server-side API error | The server's own code | ## Transcripts in Call Logs Call logs can be filtered to transcribed calls, which also attaches each call's transcripts to the log: ```swift theme={null} let callLogRequest = CallLogsRequest.CallLogsBuilder() .set(limit: 30) .set(hasTranscriptions: true) .build() callLogRequest.fetchNext(onSuccess: { callLogs in for callLog in callLogs { for transcript in callLog.transcriptions { print(transcript.tid, transcript.transcriptUrl) } } }, onError: { error in print("Error: \(error?.errorDescription ?? "")") }) ``` `transcriptions` is an empty array when the server omitted transcripts, so it never needs a nil check. Passing `false` leaves the list unfiltered, exactly as if the filter had never been set — and the server then omits the transcripts. ## Complete Example ```swift theme={null} // 1. Join a session with transcription enabled let sessionSettings = CometChatCalls.sessionSettingsBuilder .enableAutoStartTranscription(true) .hideTranscriptionButton(false) .hideClosedCaptionButton(false) .setCaptionLanguage("en-US") .build() // 2. Control transcription during the call CallSession.shared.startTranscription() CallSession.shared.stopTranscription() // 3. Retrieve transcripts after the call let request = TranscriptsRequest.TranscriptsBuilder() .set(sessionId: sessionId) .set(limit: 10) .build() request.fetchNext(onSuccess: { transcripts in for transcript in transcripts { print(transcript.transcriptUrl) } }, onError: { error in print("Error: \(error?.errorDescription ?? "")") }) ``` ## Related Documentation * [SessionSettingsBuilder](/docs/calls/ios/session-settings) * [Call Actions](/docs/calls/ios/actions) * [Call Logs](/docs/calls/ios/call-logs) # Troubleshooting Source: https://www.cometchat.com/docs/calls/ios/troubleshooting Troubleshoot CometChat Calls SDK v5 on iOS for setup, authentication, permissions, call launch, media, and session issues. ## Installation & Setup | Symptom | Cause | Fix | | - | - | - | | `pod install` can't find `CometChatCallsSDK` 5.1 or the Push Notifications SDK 2.0 | They are not published as pods | Add them with Swift Package Manager. See [Setup](/docs/calls/ios/setup#add-the-cometchat-dependency) | | SPM resolution fails | Incorrect package URL or version | Verify the package URL and version in Xcode's package dependencies | | `init()` fails silently | Invalid App ID or Region | Double-check credentials from the [CometChat Dashboard](https://app.cometchat.com/) | | App crashes with `-[AppDelegate window]: unrecognized selector` when a call starts | Scene-based app with no `window` property on the `AppDelegate` | Add `var window: UIWindow?` to your `AppDelegate`. See [Setup](/docs/calls/ios/setup#declare-a-window-on-your-appdelegate) | | Linker errors after install | Missing frameworks | Ensure `CometChatCallsSDK` is added to "Frameworks, Libraries, and Embedded Content" | *** ## Authentication | Symptom | Cause | Fix | | - | - | - | | `login()` fails with invalid UID | UID doesn't exist in CometChat | Create the user via [Dashboard](https://app.cometchat.com/) or [REST API](/docs/rest-api/users/create) first | | Auth token expired | Token has a limited lifetime | Generate a new auth token and call `login()` again | | `login()` called before `init()` | SDK not initialized | Always call `init()` and wait for completion before calling `login()` | *** ## Joining a Session | Symptom | Cause | Fix | | - | - | - | | `generateToken()` fails | User not logged in or invalid session ID | Ensure `login()` completes before generating a token | | Session joins but no audio/video | Permissions not granted | Request camera and microphone permissions via `AVCaptureDevice.requestAccess` | | `joinSession()` throws error | Invalid or expired token | Generate a fresh token using `generateToken()` before joining | *** ## Audio & Video | Symptom | Cause | Fix | | - | - | - | | No audio from remote participants | The app configures or activates `AVAudioSession` itself, or sets `CometChatAudioSession.callKitAudioEnabled` | Remove your own `setCategory` and `setActive` calls: the Calls SDK configures the audio session. With the Push Notifications SDK's Calls product linked, CallKit owns it for calls on CallKit and the Push SDK manages `callKitAudioEnabled`; don't set it yourself | | Camera not working | Missing `NSCameraUsageDescription` in Info.plist | Add camera usage description to your `Info.plist` | | Microphone not working | Missing `NSMicrophoneUsageDescription` in Info.plist | Add microphone usage description to your `Info.plist` | *** ## CallKit & VoIP | Symptom | Cause | Fix | | - | - | - | | Incoming calls do not ring | Push Notifications SDK Calls product not linked, Push Notifications capability or Voice over IP background mode missing, or no provider ID | Add `CometChatPushNotificationsCalls`, enable the capability and background mode, set `providerId`, and run `ensureRingReady`. See [Push Ringing](/docs/calls/ios/voip-calling) | | A killed app does not ring, a running one does | `CometChatPushNotifications.shared.initialize(config:)` runs after launch | Call it from `application(_:didFinishLaunchingWithOptions:)`: iOS only delivers the VoIP push that launched the app when the PushKit registry exists by the end of launch | | A killed app does not ring, and the dashboard push log shows APNs `400` | The APNs provider's environment does not match the build, or its Bundle ID is not the app's | Turn **Enable Production Mode** off for builds run from Xcode and on for TestFlight and App Store builds; set the provider's Bundle ID to the app's. See [Push Ringing → Check the push itself](/docs/calls/ios/voip-calling#check-the-push-itself) | | Answer does nothing / CallKit ends the call | `presentCall(_:)` returned `false`, or the push delegate was released | Keep a strong reference to the delegate (the Push SDK holds it weakly) and present your screen and join from `presentCall(_:)` | | Caller never sees "Ringing…" / answered | Caller joined right after `initiateCall`, or registered listeners through `getActiveSession()` before the session existed | Stay on the prepared session, register on `CallSession.shared`, and join on `onParticipantJoined`. See [Ringing](/docs/calls/ios/ringing) | | Audio call opens the camera | Session type not set at `initiateCall` | Pass `sessionSettings` with `.setSessionType(.voice)` in `InitiateCallOptions` | | One-way audio after a lock-screen answer | The app activates `AVAudioSession` itself | Remove your own `setActive(true)` calls: CallKit owns the call's audio session | | Caller keeps ringing when the callee's phone is off | Nothing ends a ring the callee never received for 5 minutes | Run a 45 s timer on the caller and end the call with `EndCallStatus.unanswered` | | Ring keeps playing after logout | Only the Chat SDK was logged out, and the Push SDK's Chat product is not linked | Call `CometChatCalls.logout` too, after awaiting `unregisterTokens` | | Call drops when app enters background | Background mode not enabled | Enable "Audio, AirPlay, and Picture in Picture" and "Voice over IP" background modes | # Push Ringing Source: https://www.cometchat.com/docs/calls/ios/voip-calling Ring incoming CometChat calls on iOS with the Push Notifications SDK 2.0 Calls product: PushKit and CallKit, configuration, joining on Answer, capabilities, missed calls and logout. The Calls product of the Push Notifications SDK turns a CometChat VoIP push into a ringing phone. It owns the PushKit registry, reports every call to CallKit, connects to the call while it rings, and hands the answered call to your app. It works with the app in the foreground, in the background, killed, and on the lock screen. You write no `PKPushRegistryDelegate` and no `CXProviderDelegate`. On iOS the ring is always CallKit's native incoming-call screen, in every app state. There is no custom incoming-call screen; your own UI starts when the user answers. This page covers the push side of ringing. Starting, answering and ending calls with the Calls SDK is on the [Ringing](/docs/calls/ios/ringing) page. ```mermaid theme={null} flowchart LR V[VoIP push
type=call] --> K[PushKit registry
created by the SDK] K --> D{Push SDK decides} D -->|ring| C[CallKit incoming call] D -->|duplicate, expired,
not for this user| X[Reported to CallKit
and ended at once] D -->|in another call| W[CallKit call waiting:
Decline / End & Accept] C -->|Answer| P["presentCall(call)"] P --> J[Your call screen → joinSession] C -->|Decline| Q["endCall(rejected)
1:1 only"] C -->|45 s| T["endCall(unanswered), 1:1 only
+ missed call in Recents"] ``` ## Prerequisites * [Calls SDK 5.1 set up](/docs/calls/ios/setup) and the user logged in. * Push Notifications enabled in the CometChat dashboard with an **APNs provider that uses a `.p8` auth key**, and that provider's id. The SDK registers both the APNs device token and the VoIP token under this one provider; a `.p12` certificate provider can serve only one of them. * The provider's **Bundle ID** must be your app's bundle ID. VoIP pushes go to the topic `.voip`. * The provider's **APNs environment must match the build.** A build run from Xcode gets a sandbox token, so it needs a provider with **Enable Production Mode** off. TestFlight and App Store builds need it on. On a mismatch APNs rejects the push and nothing rings. * iOS 15.1 or later. * A physical device. PushKit and CallKit do not work in the Simulator. ## Step 1: Add the SDK The Push Notifications SDK ships as three products. For ringing you add **Core** and **Calls**; add **Chat** as well if the app shows chat notifications. | Product | Add it when | Depends on | | - | - | - | | `CometChatPushNotificationsSwift` (Core) | Always | No CometChat SDK | | `CometChatPushNotificationsCalls` (Calls) | Incoming calls should ring | Core + `CometChatCallsSDK` 5.1.0 | | `CometChatPushNotificationsChat` (Chat) | You show chat notifications | Core + `CometChatSDK` 4.1.10 or later | The SDK is distributed with Swift Package Manager. In Xcode, **File → Add Package Dependencies**, enter: ``` https://github.com/cometchat/push-notifications-sdk-ios ``` Choose **Up to Next Major Version** from **2.0.0** and add `CometChatPushNotificationsSwift` and `CometChatPushNotificationsCalls` to your app target. The Calls product brings the Calls SDK 5.1 with it. Linking the Calls product turns ringing on. The Chat SDK is optional: a calls-only app adds Core and Calls and never links it. `import CometChatPushNotificationsCalls` also brings the call types (`IncomingCall`, `CallEndReason`) with it. The SDK links `PushKit`, `CallKit` and `AVFAudio` itself; you add nothing for them. > [!NOTE] > > CallKit is not allowed in apps sold in China. For a China App Store build, ship a target without the Calls product; it is the only product that uses CallKit. ## Step 2: Capabilities and Info.plist Add all of these. Each one, when missing, silences calls without an error. | What | Where | Why | | - | - | - | | **Push Notifications** capability (adds the `aps-environment` entitlement) | Signing & Capabilities | Without it iOS issues neither the APNs device token nor the VoIP token | | **Background Modes → Voice over IP** (`voip` in `UIBackgroundModes`) | Signing & Capabilities | PushKit does not deliver VoIP pushes to an app without it, so a killed app cannot ring | | **Background Modes → Audio, AirPlay, and Picture in Picture** (`audio`) | Signing & Capabilities | Keeps the call running when the user leaves the app; see [Background Handling](/docs/calls/ios/background-handling) | | **Background Modes → Remote notifications** (`remote-notification`) | Signing & Capabilities | Only for chat: silent pushes reach the app. Not needed for ringing | | `NSMicrophoneUsageDescription` | `Info.plist` | The Calls SDK captures audio on join; iOS terminates an app that uses the microphone without it | | `NSCameraUsageDescription` | `Info.plist` | Video calls. Add it even if you only place voice calls: the Calls SDK links the camera | ```xml Info.plist theme={null} NSMicrophoneUsageDescription Lets you talk on calls. NSCameraUsageDescription Lets you be seen on video calls. UIBackgroundModes voip audio ``` A development build carries `aps-environment` = `development`; TestFlight and App Store builds need `production`, which Xcode sets when you archive with a distribution profile. ## Step 3: Initialise in `didFinishLaunching` Call `initialize(config:)` in `application(_:didFinishLaunchingWithOptions:)`, **on every launch**, before the user logs in. This is the one hard rule: * The SDK creates its PushKit registry inside `initialize`. iOS delivers the VoIP push that launched a killed app only to a registry that exists by the time `didFinishLaunching` returns, so a later call loses the first call after a cold start. * Token registration on login and logout only runs in a launch where `initialize` ran. * `initialize` also sets itself as the `UNUserNotificationCenter` delegate, asks for notification permission (unless you turn it off), and saves the configuration so a launch started by a push still knows your app. Set the delegate first. The SDK holds it weakly, so keep a strong reference to it, as the `AppDelegate` below does. > [tab] Swift > > ```swift AppDelegate.swift theme={null} > import UIKit > import CometChatPushNotificationsSwift > import CometChatPushNotificationsCalls > > @main > final class AppDelegate: UIResponder, UIApplicationDelegate { > > var window: UIWindow? > > // The SDK holds its delegate weakly: the app keeps it alive. > let pushDelegate = PushDelegate() > > func application(_ application: UIApplication, > didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { > CometChatPushNotifications.shared.delegate = pushDelegate > CometChatPushNotifications.shared.initialize(config: PNConfiguration( > appId: "APP_ID", > region: "REGION", > providerId: "PROVIDER_ID", // the APNs provider from the dashboard > callKit: CallKitBranding(iconTemplateImageName: "CallKitIcon") > )) > return true > } > } > ``` > [tab] Objective-C > > ```objectivec AppDelegate.m theme={null} > @import CometChatPushNotificationsSwift; > @import CometChatPushNotificationsCalls; > > - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { > // self.pushDelegate is a strong property: the SDK holds its delegate weakly. > CometChatPushNotifications.shared.delegate = self.pushDelegate; > > PNConfiguration *config = [[[[PNConfiguration builderWithAppId:@"APP_ID" region:@"REGION"] > providerId:@"PROVIDER_ID"] > callKitWithName:nil iconTemplateImageName:@"CallKitIcon" ringtone:nil includeInRecents:YES supportsVideo:YES] > build]; > [CometChatPushNotifications.shared initializeWithConfig:config]; > return YES; > } > ``` In a SwiftUI app, put this in an `AppDelegate` attached with `@UIApplicationDelegateAdaptor`. `PNConfiguration(appId:region:…)` takes every option below as a defaulted parameter. From Objective-C, or to chain setters, use `PNConfiguration.builder(appId:region:)` and finish with `build()`. If you already have the Calls SDK's `CallAppSettings`, `PNConfigurationBuilder.from(_:)` starts a builder with its app id and region (it returns `nil` if they are missing). | Option | Default | What it does | | - | - | - | | `appId`, `region` | none; **required** | Your CometChat app. Must not be blank. Used to register tokens and to bring the Calls SDK up when a push starts the app | | `providerId` | `nil`; **required to ring** | The dashboard APNs provider the tokens are registered under. Without it no token is registered (`PNError.Code.providerRequired`), so nothing rings, and `ensureRingReady` reports `.providerMissing` | | `callKit` | `CallKitBranding()` | How CallKit shows your calls: icon, ringtone, Recents, video. See [Customising CallKit](#customising-callkit) | | `requestCallPermissions` | `true` | Ask for the microphone (and the camera for a video call) after the user answers | | `requestNotificationPermission` | `true` | Show the notification prompt and register for remote notifications in `initialize`. Calls ring without notification permission, so a calls-only app can set `false` | | `autoRegisterTokens` | `true` | Register the tokens on login and unregister them on logout, with no code of yours | | `tokenRegistrar` | `.auto` | Whose session registers the tokens: `.auto` (the Chat SDK if logged in, then the Calls SDK), `.chat` or `.calls` | | `authToken` | `nil` | A user auth token to register with when neither SDK is logged in. Not saved to disk | | `pushKitOwnership` | `.sdk` | `.app` if your app keeps its own `PKPushRegistry`; see [Owning PushKit yourself](#owning-pushkit-yourself) | | `clientHost` (builder: `overrideClientHost(_:)`) | `nil` | Register tokens against this client host instead of the default one. Set it only if you give the Chat and Calls SDKs a client host override, and use the same value | | `extensionGroupID`, `enableBadgeCount`, `showInAppNotifications` | `nil`, `true`, `true` | Chat notifications; see [iOS Push Notifications](/docs/notifications/ios-push-notifications-sdk) | A call rings for the ring timeout the push carries, or 45 seconds (`RingConstants.defaultRingTimeoutMs`) when it carries none, counted from when the caller started the call rather than from when the push arrived (the push's send time, or failing that its arrival, when the start time is missing), plus about 2 seconds of slack. If the app also shows chat notifications, forward the APNs device token from your `AppDelegate` as described in [iOS Push Notifications](/docs/notifications/ios-push-notifications-sdk#4-forward-the-apns-token). The VoIP token needs nothing: the SDK receives it from its own PushKit registry. ## Step 4: Join when the user answers On **Answer** the SDK calls `presentCall(_:)` on your delegate. It fires at once in every app state (foreground, background, launched from killed, and with the phone locked), on the main queue, and at most once per call. Present your call screen and join at once: the join connects the audio while the phone may still be locked, and the screen becomes visible when the user unlocks. There is nothing to "accept". Adopt `CometChatPushNotificationsCallsDelegate` on the object you set as the delegate: ```swift PushDelegate.swift theme={null} import UIKit import CometChatPushNotificationsSwift import CometChatPushNotificationsCalls final class PushDelegate: NSObject, CometChatPushNotificationsCallsDelegate { // The user answered: show the call screen and join. Return false only when the app // cannot take the call at all; the SDK then ends the CallKit call. // The SDK calls both methods on the main queue. func presentCall(_ call: IncomingCall) -> Bool { MainActor.assumeIsolated { CallPresenter.shared.show(call) } return true } // The call is over (or never started): take the screen down. CallKit has already been told. func callDidEnd(_ call: IncomingCall, reason: CallEndReason) { MainActor.assumeIsolated { CallPresenter.shared.end(sessionId: call.sessionId) } } } ``` A launch started by a push may not have a window when the user answers, so present on the top view controller when there is one, and otherwise as soon as your UI is up. The SDK ends an answered call with `.failed` if the session has not joined within 20 seconds, so if your UI may come up later than that (an answer from the lock screen of an app the push just started), start the join without waiting for the window: create the call screen, call `joinSession` with its container view, and present it once a window exists. ```swift CallPresenter.swift theme={null} import UIKit import CometChatPushNotificationsCalls @MainActor final class CallPresenter { static let shared = CallPresenter() private var pending: IncomingCall? private weak var screen: CallViewController? func show(_ call: IncomingCall) { if screen?.call.sessionId == call.sessionId { return } guard let top = Self.topViewController() else { pending = call // no window yet: a launch started by the push return } let screen = CallViewController(call: call) self.screen = screen top.present(screen, animated: false) } /// Call when your UI comes up, for example from sceneDidBecomeActive(_:) or your root view's onAppear. func showPending() { guard let call = pending else { return } pending = nil show(call) } func end(sessionId: String) { if pending?.sessionId == sessionId { pending = nil } if screen?.call.sessionId == sessionId { screen?.dismiss(animated: true) } } private static func topViewController() -> UIViewController? { let windows = UIApplication.shared.connectedScenes .compactMap { $0 as? UIWindowScene } .flatMap { $0.windows } var top = (windows.first { $0.isKeyWindow } ?? windows.first)?.rootViewController while let presented = top?.presentedViewController { top = presented } return top } } ``` The call screen joins by session id as soon as it loads: ```swift CallViewController.swift theme={null} import UIKit import CometChatCallsSDK import CometChatPushNotificationsCalls final class CallViewController: UIViewController { let call: IncomingCall private let container = UIView() init(call: IncomingCall) { self.call = call super.init(nibName: nil, bundle: nil) modalPresentationStyle = .fullScreen } required init?(coder: NSCoder) { fatalError("init(coder:) is not supported") } override func viewDidLoad() { super.viewDidLoad() container.frame = view.bounds container.autoresizingMask = [.flexibleWidth, .flexibleHeight] view.addSubview(container) let settings = SessionSettingsBuilder() .setSessionType(call.isVideo ? .video : .voice) .startVideoPaused(!call.isVideo) .build() CometChatCalls.joinSession(sessionID: call.sessionId, callSetting: settings, container: container, onSuccess: { _ in }, onError: { [weak self] _ in DispatchQueue.main.async { self?.dismiss(animated: true) } }) } } ``` `IncomingCall` gives you `sessionId`, `callerUid`, `callerName`, `callerAvatarUrl`, `callType`, `isVideo`, `isPeerCall` (a 1:1 call), `receiverType`, `receiverUid` and `conversationId`. > [!NOTE] > > While the phone rings, the SDK already connects to the call. `joinSession(sessionID:)` takes that prepared session over, so answering only adds the media. A prepared session keeps the settings it was prepared with (the session type, video paused for a voice call, speaker audio, and a peer call for 1:1), and the settings passed to `joinSession` are ignored for it. > [!WARNING] > > **SwiftUI: keep the delegate a plain `NSObject`.** The SDK holds its delegate as an Objective-C weak reference. Do not make an `ObservableObject` with `@Published` properties the delegate; have a small `NSObject` delegate forward to it, as `PushDelegate` forwards to `CallPresenter` above. **Hanging up.** Leave the session as usual (`CallSession.shared.leave()`), or let the user end the call from the CallKit screen. Either way the SDK ends the CallKit call and calls `callDidEnd`. **Answer without a join.** With no delegate adopting `CometChatPushNotificationsCallsDelegate`, or when `presentCall` returns `false`, the SDK ends the CallKit call at once and calls `callDidEnd` with `.failed`. If `presentCall` returned `true` but the session has not joined within 20 seconds of Answer, it does the same, rather than leave a silent call on screen. So return `true` and defer the presentation when your UI is not ready yet, as the sample above does, instead of returning `false`. `callDidEnd(_:reason:)` gets one of: | `CallEndReason` | Meaning | | - | - | | `.answeredElsewhere` | Answered on another of the user's devices | | `.cancelled` | The caller cancelled before anyone answered | | `.declined` | Declined on this device | | `.timedOut` | Nobody answered within the ring window | | `.remoteEnded` | The call ended: the other side or the user hung up, or the session ended | | `.failed` | The call could not be set up or kept, including logout while it rang | | `.filtered` | Dropped before ringing (not normally delivered) | `.answered` is never delivered. ## Permissions and ring readiness **Microphone and camera.** The SDK asks after Answer, without holding up the join. On a lock-screen answer the prompt appears when the user unlocks. A denied microphone joins muted and does not fail the call. Ask earlier as well (at sign-in, for example) so a call is not where the user first meets the prompt. If your app asks itself, turn the SDK prompt off with `requestCallPermissions: false`. **Notifications.** Calls ring through CallKit whether or not the user allows notifications. Notification permission matters only for chat notifications. **Ring readiness.** Several build and device settings silence a call with no error anywhere. Check once after sign-in and tell the user: ```swift theme={null} CometChatPushNotifications.shared.ensureRingReady { result in guard case .success(let readiness) = result, readiness != .ready else { return } showBanner("Incoming calls may not ring: \(readiness.name)") if readiness == .microphoneDenied || readiness == .notificationsOff, let url = URL(string: UIApplication.openSettingsURLString) { UIApplication.shared.open(url) } } ``` The completion runs on the main queue and reports the first problem it finds, in this order: | `RingReadiness` | Meaning | | - | - | | `.ready` | Nothing in the way | | `.backgroundModeMissing` | `UIBackgroundModes` has no `voip`: a killed app cannot ring | | `.voipEntitlementMissing` | The build has no `aps-environment` entitlement: no APNs or VoIP token. Checked on a device only | | `.microphoneDenied` | The user refused the microphone: calls ring but join muted | | `.providerMissing` | No `providerId` in the configuration | | `.notificationsOff` | Notifications are denied. Calls still ring; chat notifications do not appear | For a bug report, `CometChatPushNotifications.shared.getDiagnostics()` returns a dictionary of everything that affects ringing (products installed, login state, cached tokens, background modes, entitlement, permissions, usage strings), with no token or auth value in it. `verifyPushSetup(completion:)` registers the tokens and reports `.notLoggedIn`, `.tokenNotRegistered` or `.testPushUnavailable`; the last means registration succeeded but a round-trip test push is not available, so it is the success result today. ## How a ring ends The SDK handles every way a ring ends; you write no code for it. * **Decline, 1:1 call.** The SDK sends `rejected` to the caller, or `busy` when the user is in another call. A decline that iOS suspends the app before sending is retried when the app next launches, if that is within 90 seconds. * **Decline, group call.** The ring stops on this device only. Nothing is sent, and the call continues for the others. * **No answer, 1:1 call.** After the ring window the CallKit call ends as unanswered, which leaves a missed call in Recents, and the SDK sends `unanswered`. * **No answer, group call.** The ring stops and leaves a missed call; nothing is sent. * **Caller cancels.** The ring stops and leaves a missed call. * **Answered on another device.** The ring stops here, with no missed call. * **Late push.** A push that arrives after its ring window is not rung; it leaves a missed call. The app hears about each through `callDidEnd`. ## A call during a call A call that arrives while the user is in a CometChat call rings over it on CallKit's call-waiting screen with **Decline** and **End & Accept**. There is no Hold & Accept: the Calls SDK runs one session at a time. * **Decline** sends `busy` to a 1:1 caller; the live call continues. * **End & Accept** ends the live call (you get `callDidEnd` for it), waits for its session to leave, then delivers `presentCall` for the new call. A call that arrives while another is still ringing replaces it: the first ring stops on this device and leaves a missed call in Recents. That first call gets no `callDidEnd`, and nothing is sent to its caller. A cellular call that arrives during a CometChat call puts it on hold: the SDK mutes the microphone and pauses the video, and restores both when the cellular call ends. ## Missed calls The SDK posts no missed-call notification on iOS. CallKit writes the missed call into the Phone app's **Recents** when a call stops ringing unanswered (timed out, cancelled by the caller, or ended while still ringing), as long as `includesCallsInRecents` is `true` (the default). Declined calls and calls answered elsewhere leave no missed call. Your app gets `callDidEnd` with `.timedOut`, `.cancelled` or `.remoteEnded` (ended while still ringing), which is where to update your own missed-call UI. Call history comes from [Call Logs](/docs/calls/ios/call-logs). ## When the app is killed PushKit launches the app in the background, `didFinishLaunching` runs `initialize`, and the push reaches the SDK's registry, which reports the call to CallKit. iOS requires every VoIP push to be reported to CallKit as a call; an app that does not is terminated, and iOS stops delivering VoIP pushes to it if it keeps happening. The SDK reports **every** VoIP push: one it does not ring (a duplicate, an expired call, a call to another user, a payload that is not a call) is reported and ended at once. On a launch started by a push the SDK brings the Calls SDK up from the saved app id and region, and the Calls SDK restores the logged-in user from its own storage. Initialise the Calls SDK in your own startup code as usual as well, so the join after Answer finds it ready. ## Tokens and logout You do not register push tokens. The SDK registers the VoIP token and, when the Chat product is linked, the APNs device token, both under your `providerId`, when the user logs in to either SDK (or in `initialize` if someone is already logged in). It registers a rotated token again, and unregisters a VoIP token that iOS invalidates. A calls-only app registers only the VoIP token. To log out, **unregister first and wait for it**: the request is authenticated with the user's session, so it has to finish before that session ends. ```swift theme={null} CometChatPushNotifications.shared.unregisterTokens(completion: { _ in CometChatCalls.logout(onSuccess: { _ in }, onError: { _ in }) // With the Chat SDK, also log out of it: CometChat.logout(...) }) ``` Logging out of the Calls SDK (or of the Chat SDK, when the Chat product is linked) also ends a call still ringing for the old user (and an answered call in progress, as `.failed`), tries to unregister the tokens and clears the app badge. That unregister can be too late because the session is already gone, which is why you call `unregisterTokens` first. The tokens stay cached on the device and are registered again for the next user who logs in. ## Customising CallKit The incoming screen is CallKit's, so what you can change is CallKit's configuration, through `CallKitBranding`: ```swift theme={null} let branding = CallKitBranding( localizedName: nil, iconTemplateImageName: "CallKitIcon", // asset-catalog image ringtoneSound: "ringtone.caf", // sound file in the app bundle includesCallsInRecents: true, supportsVideo: true ) ``` | `CallKitBranding` | Default | What it does | | - | - | - | | `iconTemplateImageName` | `nil` | Asset-catalog name of a template image (40 × 40 pt, alpha only) shown on the CallKit screen | | `ringtoneSound` | `nil` | A sound file in the app bundle; `nil` plays the user's own ringtone | | `includesCallsInRecents` | `true` | Calls appear in the Phone app's Recents. Also what gives a missed call its entry | | `supportsVideo` | `true` | CallKit offers video controls | | `localizedName` | `nil` | Shown as the other party of an outgoing call the SDK puts on CallKit before the callee is known; `nil` uses your app's display name. CallKit itself shows your app's name | The caller's name on the ring comes from the push. Pass the branding as `callKit:` in `PNConfiguration`, or with the builder's `callKit(_:)` or `callKit(name:iconTemplateImageName:ringtone:includeInRecents:supportsVideo:)`. `CometChatPushNotificationsCalls.decline(sessionId:)` declines the ringing call exactly as CallKit's Decline does, for your own in-app controls or tests. `answer(sessionId:)` exists for tests only: it answers without going through CallKit, so the CallKit call is not updated and the audio session is not configured for the call. Answer from the CallKit screen in apps. ## Outgoing calls CallKit owns the Calls SDK's audio only while it has a call: from the moment an incoming call is answered or an outgoing call is reported to it, until the last such call ends. The SDK reports outgoing calls to CallKit itself, so they get CallKit-owned audio: it puts an outgoing call on CallKit when the Calls SDK connects or joins its session, including a session you join directly, such as a meeting. It reports it under your app's name as a voice call and renames it when the other party joins. A session CallKit has no call for uses WebRTC's normal audio handling. When the Calls product is linked, don't set `CometChatAudioSession.callKitAudioEnabled` yourself: the SDK turns it on and off as CallKit's calls come and go, and each write mutes WebRTC until CallKit next activates the audio session. To give CallKit the callee's name and the call type from the start, report the call yourself: ```swift theme={null} // When you start the outgoing call: CometChatPushNotificationsCalls.reportOutgoingCall(sessionId: sessionId, calleeName: "Alice", hasVideo: true) // When the session joins: CometChatPushNotificationsCalls.reportCallConnected(sessionId: sessionId) // When it is over (the reason defaults to .remoteEnded): CometChatPushNotificationsCalls.reportCallEnded(sessionId: sessionId, reason: .remoteEnded) ``` A call on CallKit survives a cellular interruption, appears in Recents and can be ended from the lock screen. > [!WARNING] > > **Do not create your own `CXProvider`, call `AVAudioSession.setActive` or set the audio session category.** For a call on CallKit, CallKit owns the audio session. The SDK does not touch `AVAudioSession`: it forwards CallKit's activation and deactivation to the Calls SDK, and WebRTC configures the session when CallKit activates it. An app that activates or configures the session itself gets one-way audio on lock-screen answers or a CallKit audio-route button out of sync, and a second provider cannot end the SDK's calls. ## Knowing about a call in your own code Listen on the Calls SDK, not on this SDK. It is the same event whether the call arrived by push on a killed app or on a running one: ```swift theme={null} final class CallEvents: NSObject, CometChatIncomingCallListener { func onIncomingCallReceived(call: CometChatIncomingCall) { /* badge, list refresh, analytics */ } func onIncomingCallEnded(call: CometChatIncomingCall, reason: String) { /* … */ } } let callEvents = CallEvents() // the Calls SDK holds listeners weakly: keep a strong reference CometChatCalls.addIncomingCallListener("my-screen", callEvents) ``` Ids are keys: registering the same id again replaces the listener. Use your own id, not `cometchat-push-notifications`, which the Push Notifications SDK uses for its own listener. Remove yours with `CometChatCalls.removeIncomingCallListener("my-screen")` when the screen goes away. ## Owning PushKit yourself If your app already has a `PKPushRegistry` for other VoIP pushes, set `pushKitOwnership: .app` and forward to the SDK from your registry delegate: ```swift theme={null} func pushRegistry(_ registry: PKPushRegistry, didUpdate pushCredentials: PKPushCredentials, for type: PKPushType) { CometChatPushNotifications.shared.handleVoIPToken(pushCredentials.token) } func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) { let handled = CometChatPushNotifications.shared.handleIncomingVoIPPush(payload.dictionaryPayload, completion: completion) if !handled { // Not a CometChat call: report your own call to CallKit, then call completion(). } } ``` When `handleIncomingVoIPPush` returns `false` the SDK did not report anything and did not call `completion`, so reporting a call to CallKit is up to you. Your registry must still be created in `didFinishLaunching`. ## Troubleshooting | Symptom | Check | | - | - | | Nothing rings when the app is killed | `voip` background mode; `initialize` called in `didFinishLaunching` on every launch; `ensureRingReady` is `.ready`. Then check the push itself (below) | | A running app rings but a killed one does not | Check the push itself (below), and test from a killed app | | Tokens never register | Push Notifications capability present; `providerId` set; the user logged in to the Chat or Calls SDK. `onPushTokenRegistrationFailed` on the delegate says why | | Nothing happens in the Simulator | PushKit and CallKit need a physical device | | Answer, then the call ends with `.failed` at once | No delegate adopting `CometChatPushNotificationsCallsDelegate`, the delegate was released (it is held weakly), or `presentCall` returned `false` | | Answer, then the call ends with `.failed` after about 20 seconds | `presentCall` returned `true` but the screen never called `joinSession` | | No audio, or the caller hears nothing after a lock-screen answer | The app calls `AVAudioSession.setActive` or has its own `CXProvider`; remove them | | `joinSession` settings have no effect on an answered call | Expected: the prepared session keeps the settings it was prepared with | | Ring keeps playing after the user logged out | The app did not log out of the Calls SDK (or the Chat SDK with the Chat product linked) | | The device still rings for a user who logged out | `unregisterTokens` was not awaited before logout | | No missed call in Recents | `includesCallsInRecents` is `false` | | The push log shows APNs `400` for the VoIP token | The provider's APNs environment does not match the build (**Enable Production Mode** must be off for Xcode builds, on for TestFlight and App Store), or its Bundle ID is not the app's | | The push log shows APNs `403` | The provider's `.p8` key, Key ID or Team ID is wrong | | Two incoming-call screens, or a call that cannot be ended | Legacy app-side ringing (your own `PKPushRegistry`, `CXProvider` or `CallListener` ringing UI) is still in place; remove it | ### Check the push itself When a killed app does not ring, look at what the server sent before debugging the app. In the dashboard, open **Notifications → Logs**, search for the call's message ID and find the row for the device's `APNS_IOS_VOIP` token. * **Success `True`, `200`**: APNs accepted the push. Check the app (the rows above). * **`400` or `403`**: APNs rejected the push, so the device was never woken. Fix the provider, not the app. * **No row for the token**: the token is not registered. See *Tokens never register* above. ## Related * [Ringing](/docs/calls/ios/ringing): starting, answering and ending calls with the Calls SDK. * [Migrating from legacy ringing](/docs/calls/ios/migrating-from-legacy-ringing). * [Background Handling](/docs/calls/ios/background-handling): keeping the call running when the user leaves the app. * [iOS Push Notifications](/docs/notifications/ios-push-notifications-sdk): chat notifications with the same SDK. # Actions Source: https://www.cometchat.com/docs/calls/react-native/actions Use CometChat Calls SDK v5 actions on React Native to control calls, manage audio/video state, and handle in-call behavior. Control the active call session programmatically using the static methods on `CometChatCalls`. These methods allow you to manage audio, video, and other call features. ## Audio Controls ### Mute Audio Mute the local user's microphone: ```tsx theme={null} CometChatCalls.muteAudio(); ``` ### Unmute Audio Unmute the local user's microphone: ```tsx theme={null} CometChatCalls.unmuteAudio(); ``` ## Video Controls ### Pause Video Stop sending the local user's video: ```tsx theme={null} CometChatCalls.pauseVideo(); ``` ### Resume Video Resume sending the local user's video: ```tsx theme={null} CometChatCalls.resumeVideo(); ``` ### Switch Camera Toggle between front and rear cameras: ```tsx theme={null} CometChatCalls.switchCamera(); ``` ## Session Control ### Leave Session End the call and leave the session: ```tsx theme={null} CometChatCalls.leaveSession(); ``` > [!NOTE] > > The `leaveSession()` method ends the call for the local user, and other participants remain. In a 1:1 call prepared with `isPeerCall: true`, it ends the call for both. > [!NOTE] > > `leaveSession()` takes no session ID. `CometChatCalls` is a singleton that tracks one active session at a time, so this leaves whichever session is currently in progress. The same applies to every action on this page. See [Single Active Session](/docs/calls/react-native/overview#single-active-session). ## Transcription *Available since v5.0.5* ### Start Transcription Begin server-side transcription of the call. This also enables the live closed captions overlay: ```tsx theme={null} CometChatCalls.startTranscription(); ``` > [!WARNING] > > Transcription requires the feature to be enabled for your CometChat app. ### Stop Transcription Stop the current transcription and clear any captions currently on screen. The transcript is saved and can be retrieved with [`TranscriptRequestBuilder`](/docs/calls/react-native/transcription#retrieving-transcripts): ```tsx theme={null} CometChatCalls.stopTranscription(); ``` ## Raise Hand ### Raise Hand Signal to other participants that you want attention: ```tsx theme={null} CometChatCalls.raiseHand(); ``` ### Lower Hand Lower your raised hand: ```tsx theme={null} CometChatCalls.lowerHand(); ``` ## Layout Control ### Set Layout Change the call layout programmatically: ```tsx theme={null} // Available layouts: 'TILE', 'SIDEBAR', 'SPOTLIGHT' CometChatCalls.setLayout('TILE'); CometChatCalls.setLayout('SIDEBAR'); CometChatCalls.setLayout('SPOTLIGHT'); ``` | Layout | Description | | - | - | | `TILE` | Grid layout showing all participants equally | | `SIDEBAR` | Main video with participants in a sidebar | | `SPOTLIGHT` | Focus on one participant with others minimized | ## Picture-in-Picture ### Enable Picture-in-Picture Enable PiP mode to continue the call in a floating window: ```tsx theme={null} CometChatCalls.enablePictureInPictureLayout(); ``` ### Disable Picture-in-Picture Exit PiP mode and return to full-screen: ```tsx theme={null} CometChatCalls.disablePictureInPictureLayout(); ``` ## Participant Management ### Pin Participant Pin a participant to the main view: ```tsx theme={null} const participantId = 'participant_pid'; const type = 'human'; // 'human' or 'screen-share' CometChatCalls.pinParticipant(participantId, type); ``` | Parameter | Type | Description | | - | - | - | | `participantId` | string | The participant's ID | | `type` | string | `'human'` for user video, `'screen-share'` for screen share | ### Unpin Participant Remove the pinned participant: ```tsx theme={null} CometChatCalls.unpinParticipant(); ``` ### Mute Participant Mute another participant's audio (requires moderator permissions): ```tsx theme={null} const participantId = 'participant_pid'; CometChatCalls.muteParticipant(participantId); ``` ### Pause Participant Video Pause another participant's video (requires moderator permissions): ```tsx theme={null} const participantId = 'participant_pid'; CometChatCalls.pauseParticipantVideo(participantId); ``` ### Participant List Panel Show, hide, or toggle the built-in participant list panel programmatically: ```tsx theme={null} CometChatCalls.showParticipantList(); CometChatCalls.hideParticipantList(); CometChatCalls.toggleParticipantList(); ``` ## Chat Integration ### Set Chat Button Unread Count Update the unread message count on the chat button: ```tsx theme={null} CometChatCalls.setChatButtonUnreadCount(5); ``` ## Complete Example ```tsx theme={null} import React, { useState } from 'react'; import { View, TouchableOpacity, Text, StyleSheet } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; function CallControls() { const [isAudioMuted, setIsAudioMuted] = useState(false); const [isVideoMuted, setIsVideoMuted] = useState(false); const [isHandRaised, setIsHandRaised] = useState(false); const [currentLayout, setCurrentLayout] = useState<'TILE' | 'SIDEBAR' | 'SPOTLIGHT'>('TILE'); const toggleAudio = () => { if (isAudioMuted) { CometChatCalls.unmuteAudio(); } else { CometChatCalls.muteAudio(); } setIsAudioMuted(!isAudioMuted); }; const toggleVideo = () => { if (isVideoMuted) { CometChatCalls.resumeVideo(); } else { CometChatCalls.pauseVideo(); } setIsVideoMuted(!isVideoMuted); }; const toggleHand = () => { if (isHandRaised) { CometChatCalls.lowerHand(); } else { CometChatCalls.raiseHand(); } setIsHandRaised(!isHandRaised); }; const cycleLayout = () => { const layouts: Array<'TILE' | 'SIDEBAR' | 'SPOTLIGHT'> = ['TILE', 'SIDEBAR', 'SPOTLIGHT']; const currentIndex = layouts.indexOf(currentLayout); const nextLayout = layouts[(currentIndex + 1) % layouts.length]; CometChatCalls.setLayout(nextLayout); setCurrentLayout(nextLayout); }; const handleSwitchCamera = () => { CometChatCalls.switchCamera(); }; const handleEndCall = () => { CometChatCalls.leaveSession(); }; return ( {isAudioMuted ? 'Unmute' : 'Mute'} {isVideoMuted ? 'Show Video' : 'Hide Video'} Switch Camera {isHandRaised ? 'Lower Hand' : 'Raise Hand'} Layout: {currentLayout} End Call ); } const styles = StyleSheet.create({ container: { flexDirection: 'row', flexWrap: 'wrap', justifyContent: 'center', padding: 16, gap: 8, }, button: { backgroundColor: '#333', paddingHorizontal: 16, paddingVertical: 12, borderRadius: 8, }, endButton: { backgroundColor: '#ff4444', }, buttonText: { color: '#fff', fontSize: 14, fontWeight: '600', }, }); export default CallControls; ``` ## Legacy Methods These methods are deprecated but still available for backward compatibility: | Deprecated Method | Replacement | | - | - | | `endSession()` | `leaveSession()` | ## Related Documentation * [Events](/docs/calls/react-native/events) - Listen for call events * [Participant Management](/docs/calls/react-native/participant-management) - Manage participants * [Call Layouts](/docs/calls/react-native/call-layouts) - Layout options * [Transcription](/docs/calls/react-native/transcription) - Transcription and closed captions # Audio Modes Source: https://www.cometchat.com/docs/calls/react-native/audio-modes Configure CometChat Calls SDK v5 audio modes on React Native for speakers, earpiece, Bluetooth, routing, and call audio behavior. The CometChat Calls SDK supports multiple audio output modes on mobile devices. Users can switch between speaker, earpiece, Bluetooth, and wired headphones. ## Available Audio Modes | Mode | Constant | Description | | - | - | - | | Speaker | `'SPEAKER'` | Phone speaker (loudspeaker) | | Earpiece | `'EARPIECE'` | Phone earpiece (for private calls) | | Bluetooth | `'BLUETOOTH'` | Connected Bluetooth device | | Headphones | `'HEADPHONES'` | Wired headphones | ## Set Default Audio Mode Configure the default audio mode when creating call settings: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; const sessionSettings = { audioMode: 'SPEAKER', }; ``` ## Set Audio Mode Programmatically Change the audio output route during an active call with `CometChatCalls.setAudioMode()`. Pass one of the mode constants: ```tsx theme={null} CometChatCalls.setAudioMode('SPEAKER'); // or 'EARPIECE' | 'BLUETOOTH' | 'HEADPHONES' ``` > [!NOTE] > > The requested route takes effect when the corresponding device is available (for example, `'BLUETOOTH'` requires a connected Bluetooth device). ## Show Audio Mode Button Enable the audio mode button in the call UI: ```tsx theme={null} const sessionSettings = { hideAudioModeButton: false, }; ``` ## Listen for Audio Mode Changes Subscribe to audio mode change events: ```tsx theme={null} CometChatCalls.addEventListener('onAudioModeChanged', (mode) => { console.log('Audio mode changed to:', mode); // mode: 'SPEAKER' | 'EARPIECE' | 'BLUETOOTH' | 'HEADPHONES' }); ``` ## Audio Mode Event Payload The `onAudioModeChanged` event delivers the **active mode as a plain string** — not an object. Its value is one of `'SPEAKER'`, `'EARPIECE'`, `'BLUETOOTH'`, or `'HEADPHONES'`: ```tsx theme={null} CometChatCalls.addEventListener('onAudioModeChanged', (mode) => { // mode is a string, e.g. 'SPEAKER' if (mode === 'BLUETOOTH') { console.log('Now routing audio to Bluetooth'); } }); ``` ## Complete Example ```tsx theme={null} import React, { useState, useEffect } from 'react'; import { View, TouchableOpacity, Text, StyleSheet, Modal, FlatList } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; type AudioMode = 'SPEAKER' | 'EARPIECE' | 'BLUETOOTH' | 'HEADPHONES'; interface AudioModeOption { type: AudioMode; label: string; icon: string; } const audioModeOptions: AudioModeOption[] = [ { type: 'SPEAKER', label: 'Speaker', icon: '🔊' }, { type: 'EARPIECE', label: 'Earpiece', icon: '📱' }, { type: 'BLUETOOTH', label: 'Bluetooth', icon: '🎧' }, { type: 'HEADPHONES', label: 'Headphones', icon: '🎵' }, ]; function AudioModeSelector() { const [currentMode, setCurrentMode] = useState('SPEAKER'); // NOTE: The SDK does not expose a list of currently-available audio modes. // This array is illustrative — populate it from your own device detection if needed. const [availableModes] = useState(['SPEAKER', 'EARPIECE', 'BLUETOOTH', 'HEADPHONES']); const [modalVisible, setModalVisible] = useState(false); useEffect(() => { const unsubscribe = CometChatCalls.addEventListener( 'onAudioModeChanged', (mode: AudioMode) => { setCurrentMode(mode); } ); return () => unsubscribe(); }, []); const selectMode = (mode: AudioMode) => { // The SDK handles audio mode switching through the UI // This is for display purposes setCurrentMode(mode); setModalVisible(false); }; const getCurrentModeOption = () => { return audioModeOptions.find((opt) => opt.type === currentMode) || audioModeOptions[0]; }; const renderModeOption = ({ item }: { item: AudioModeOption }) => { const isAvailable = availableModes.includes(item.type); const isSelected = currentMode === item.type; return ( isAvailable && selectMode(item.type)} disabled={!isAvailable} > {item.icon} {item.label} {isSelected && ✓} ); }; return ( setModalVisible(true)} > {getCurrentModeOption().icon} {getCurrentModeOption().label} setModalVisible(false)} > Audio Output item.type} renderItem={renderModeOption} /> setModalVisible(false)} > Close ); } const styles = StyleSheet.create({ button: { flexDirection: 'row', alignItems: 'center', backgroundColor: '#333', paddingHorizontal: 16, paddingVertical: 12, borderRadius: 8, gap: 8, }, buttonIcon: { fontSize: 18, }, buttonText: { color: '#fff', fontSize: 14, fontWeight: '600', }, modalOverlay: { flex: 1, backgroundColor: 'rgba(0, 0, 0, 0.5)', justifyContent: 'flex-end', }, modalContent: { backgroundColor: '#1a1a1a', borderTopLeftRadius: 20, borderTopRightRadius: 20, padding: 20, }, modalTitle: { color: '#fff', fontSize: 18, fontWeight: '600', marginBottom: 16, textAlign: 'center', }, modeOption: { flexDirection: 'row', alignItems: 'center', padding: 16, borderRadius: 8, marginBottom: 8, backgroundColor: '#333', }, selectedOption: { backgroundColor: '#6851D6', }, disabledOption: { opacity: 0.5, }, modeIcon: { fontSize: 24, marginRight: 12, }, modeLabel: { flex: 1, color: '#fff', fontSize: 16, }, selectedLabel: { fontWeight: '600', }, disabledLabel: { color: '#666', }, checkmark: { color: '#fff', fontSize: 18, }, closeButton: { marginTop: 16, padding: 16, alignItems: 'center', }, closeButtonText: { color: '#6851D6', fontSize: 16, fontWeight: '600', }, }); export default AudioModeSelector; ``` ## Platform Considerations ### iOS * Audio mode switching is handled automatically by iOS based on connected devices * Bluetooth devices appear when connected * Headphones are detected when plugged in ### Android * Requires `MODIFY_AUDIO_SETTINGS` permission * Bluetooth requires `BLUETOOTH` and `BLUETOOTH_CONNECT` permissions * Audio routing may vary by device manufacturer ## Related Documentation * [Session Settings](/docs/calls/react-native/session-settings) - Configure default audio mode * [Events](/docs/calls/react-native/events) - Audio mode events * [Actions](/docs/calls/react-native/actions) - Audio control methods # Authentication Source: https://www.cometchat.com/docs/calls/react-native/authentication Configure authentication for CometChat Calls SDK v5 on React Native with app credentials, logged-in users, and secure call access. This guide covers initializing the CometChat Calls SDK and authenticating users in your React Native application. ## Initialize CometChat Calls The `init()` method initializes the SDK with your app credentials. Call this method once when your application starts, typically in your app's entry point or a dedicated initialization module. ### Init Settings Pass a plain settings object with your app credentials to `init()`: | Parameter | Type | Required | Description | | - | - | - | - | | `appId` | string | Yes | Your CometChat App ID | | `region` | string | Yes | Your app region (`us`, `eu`, or `in`) | | `authKey` | string | No | Your CometChat Auth Key. If passed during initialization, you do not need to pass it to methods such as `login()` | ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; const appId = 'APP_ID'; // Replace with your App ID const region = 'REGION'; // Replace with your Region ("us", "eu", or "in") const authKey = 'AUTH_KEY'; // Optional. Required only if you want to call login() without passing an Auth Key const callAppSettings = { appId, region, authKey }; const initResult = await CometChatCalls.init(callAppSettings); if (initResult.success) { console.log('CometChat Calls SDK initialized successfully'); } else { console.error('CometChat Calls SDK initialization failed:', initResult.error); } ``` ## Login After initialization, authenticate the user using one of the login methods. ### Login with UID and Auth Key Use this method during development or when you manage authentication on the client side. If you passed `authKey` to `init()`, you can call `login()` with only the user UID. Otherwise, pass the Auth Key directly as `login(uid, authKey)`. ```tsx theme={null} const uid = 'USER_UID'; try { const user = await CometChatCalls.login(uid); console.log('Login successful:', user); } catch (error) { console.error('Login failed:', error); } ``` | Parameter | Type | Required | Description | | - | - | - | - | | `uid` | string | Yes | The unique identifier of the user | | `authKey` | string | No | Your CometChat Auth Key. Required only when it was not passed to `init()` | > [!WARNING] > > Never expose your Auth Key in production apps. Use Auth Tokens generated from your backend server instead. ### Login with Auth Token For production apps, generate an Auth Token on your backend server and use it to authenticate: ```tsx theme={null} const authToken = 'USER_AUTH_TOKEN'; // Token from your backend try { const user = await CometChatCalls.loginWithAuthToken(authToken); console.log('Login successful:', user); } catch (error) { console.error('Login failed:', error); } ``` | Parameter | Type | Required | Description | | - | - | - | - | | `authToken` | string | Yes | Auth token generated from your backend | ## Logout Log out the current user when they sign out of your app: ```tsx theme={null} try { const message = await CometChatCalls.logout(); console.log('Logout successful:', message); } catch (error) { console.error('Logout failed:', error); } ``` ## Check Login Status Verify if a user is currently logged in: ```tsx theme={null} const isLoggedIn = CometChatCalls.isUserLoggedIn(); if (isLoggedIn) { console.log('User is logged in'); } else { console.log('No user logged in'); } ``` ## Get Logged In User Retrieve the currently logged-in user's details: ```tsx theme={null} const user = CometChatCalls.getLoggedInUser(); if (user) { console.log('Current user:', user.uid, user.name); } else { console.log('No user logged in'); } ``` ## Get User Auth Token Retrieve the auth token of the currently logged-in user: ```tsx theme={null} const authToken = CometChatCalls.getUserAuthToken(); if (authToken) { console.log('User auth token:', authToken); } ``` ## Login Listeners Monitor login state changes by adding a login listener: ```tsx theme={null} const listenerId = 'unique_listener_id'; CometChatCalls.addLoginListener(listenerId, { onLoginSuccess: (user) => { console.log('User logged in:', user); }, onLoginFailure: (error) => { console.error('Login failed:', error); }, onLogoutSuccess: () => { console.log('User logged out'); }, onLogoutFailure: (error) => { console.error('Logout failed:', error); }, }); // Remove listener when no longer needed CometChatCalls.removeLoginListener(listenerId); ``` ## Error Handling The SDK throws structured errors with the following properties: | Property | Type | Description | | - | - | - | | `errorCode` | string | A unique error code | | `errorDescription` | string | Human-readable error description | Common error codes: | Error Code | Description | | - | - | | `ERROR_SDK_NOT_INITIALIZED` | SDK not initialized. Call `init()` first | | `ERROR_LOGIN_IN_PROGRESS` | A login operation is already in progress | | `ERROR_INVALID_UID` | UID is empty or invalid | | `ERROR_UID_WITH_SPACE` | UID contains spaces | | `ERROR_API_KEY_NOT_FOUND` | Auth Key is empty | | `ERROR_BLANK_AUTHTOKEN` | Auth token is empty | | `ERROR_AUTHTOKEN_WITH_SPACE` | Auth token contains spaces | | `ERROR_NO_USER_LOGGED_IN` | No user is currently logged in | ## Related Documentation * [Setup](/docs/calls/react-native/setup) - Install and configure the SDK * [Session Settings](/docs/calls/react-native/session-settings) - Configure call settings * [Join Session](/docs/calls/react-native/join-session) - Start your first call # Background Handling Source: https://www.cometchat.com/docs/calls/react-native/background-handling Handle background calling with CometChat Calls SDK v5 on React Native for app lifecycle, call continuity, and notifications. Keep calls active when your app goes to the background. This requires platform-specific configuration to maintain audio/video streams and handle system interruptions. ## iOS Configuration ### Enable Background Modes 1. Open your project in Xcode 2. Select your target and go to **Signing & Capabilities** 3. Add **Background Modes** capability 4. Enable: * **Audio, AirPlay, and Picture in Picture** * **Voice over IP** (for VoIP push notifications) ### Configure Audio Session The SDK automatically configures the audio session, but you can customize it in your native code: ```swift theme={null} // ios/AppDelegate.swift import AVFoundation func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { // Configure audio session for calls do { try AVAudioSession.sharedInstance().setCategory( .playAndRecord, mode: .voiceChat, options: [.allowBluetooth, .allowBluetoothA2DP, .defaultToSpeaker] ) try AVAudioSession.sharedInstance().setActive(true) } catch { print("Failed to configure audio session: \(error)") } return true } ``` ## Android Configuration ### Add Permissions Add to your `AndroidManifest.xml`: ```xml theme={null}

``` ### Configure Foreground Service For Android 10+, calls require a foreground service to continue in the background. The SDK ships this service (`com.cometchat.calls.services.CometChatOngoingCallService`) and declares it in its own manifest, so it is merged into your app automatically — you usually don't need to declare it yourself. If you do need to override its configuration, use the SDK's actual service class and foreground-service types: ```xml theme={null} ``` ### Keep Screen Awake The SDK automatically manages wake locks during calls. No additional configuration is needed. ## Handle App State Changes Monitor app state to handle background transitions: ```tsx theme={null} import { useEffect, useRef } from 'react'; import { AppState, AppStateStatus } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; function useBackgroundHandling() { const appState = useRef(AppState.currentState); useEffect(() => { const subscription = AppState.addEventListener( 'change', (nextAppState: AppStateStatus) => { if ( appState.current.match(/active/) && nextAppState === 'background' ) { console.log('App going to background'); // Optionally enable PiP CometChatCalls.enablePictureInPictureLayout(); } else if ( appState.current === 'background' && nextAppState === 'active' ) { console.log('App coming to foreground'); // Optionally disable PiP CometChatCalls.disablePictureInPictureLayout(); } appState.current = nextAppState; } ); return () => { subscription.remove(); }; }, []); } export default useBackgroundHandling; ``` ## Handle Audio Interruptions Handle system audio interruptions (phone calls, alarms, etc.): ```tsx theme={null} import { useEffect } from 'react'; import { NativeEventEmitter, NativeModules, Platform } from 'react-native'; function useAudioInterruptions() { useEffect(() => { if (Platform.OS === 'ios') { // iOS handles audio interruptions automatically // The SDK will pause/resume as needed return; } // Android: Listen for audio focus changes // This is typically handled by the SDK automatically }, []); } export default useAudioInterruptions; ``` ## Connection Events Listen for connection state changes: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; // Connection lost (e.g., network issues) CometChatCalls.addEventListener('onConnectionLost', () => { console.log('Connection lost - attempting to reconnect'); }); // Connection restored CometChatCalls.addEventListener('onConnectionRestored', () => { console.log('Connection restored'); }); // Connection closed CometChatCalls.addEventListener('onConnectionClosed', () => { console.log('Connection closed'); }); ``` ## Complete Example ```tsx theme={null} import React, { useEffect, useRef, useCallback } from 'react'; import { View, StyleSheet, AppState, AppStateStatus } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; interface CallScreenProps { callToken: string; sessionSettings: any; onCallEnd: () => void; } function CallScreen({ callToken, sessionSettings, onCallEnd }: CallScreenProps) { const appState = useRef(AppState.currentState); const isInCall = useRef(true); // Handle app state changes useEffect(() => { const subscription = AppState.addEventListener( 'change', (nextAppState: AppStateStatus) => { if (!isInCall.current) return; if ( appState.current.match(/active/) && nextAppState === 'background' ) { // Going to background - enable PiP for video calls CometChatCalls.enablePictureInPictureLayout(); } else if ( appState.current === 'background' && nextAppState === 'active' ) { // Coming to foreground - disable PiP CometChatCalls.disablePictureInPictureLayout(); } appState.current = nextAppState; } ); return () => { subscription.remove(); }; }, []); // Handle connection events useEffect(() => { const controller = new AbortController(); const { signal } = controller; CometChatCalls.addEventListener( 'onConnectionLost', () => { console.log('Connection lost'); // Show reconnecting UI }, { signal } ); CometChatCalls.addEventListener( 'onConnectionRestored', () => { console.log('Connection restored'); // Hide reconnecting UI }, { signal } ); CometChatCalls.addEventListener( 'onConnectionClosed', () => { console.log('Connection closed'); isInCall.current = false; onCallEnd(); }, { signal } ); return () => controller.abort(); }, [onCallEnd]); // Cleanup on unmount useEffect(() => { return () => { isInCall.current = false; }; }, []); return ( ); } const styles = StyleSheet.create({ container: { flex: 1, backgroundColor: '#000', }, }); export default CallScreen; ``` ## Platform Behavior ### iOS | Scenario | Behavior | | - | - | | App backgrounded | Audio continues, video pauses | | Phone call received | Call audio is interrupted | | Phone call ended | Call audio resumes | | Screen locked | Audio continues | ### Android | Scenario | Behavior | | - | - | | App backgrounded | Audio continues with foreground service | | Phone call received | Call audio may be interrupted | | Screen off | Audio continues with wake lock | ## Related Documentation * [Picture-in-Picture](/docs/calls/react-native/picture-in-picture) - Continue calls in floating window * [VoIP Calling](/docs/calls/react-native/voip-calling) - Receive calls when app is closed * [Events](/docs/calls/react-native/events) - Connection events # Call Layouts Source: https://www.cometchat.com/docs/calls/react-native/call-layouts Customize CometChat Calls SDK v5 call layouts on React Native for participant grids, speaker views, screen sharing, and call UI. The CometChat Calls SDK provides three layout modes for displaying participants during a call. You can set the initial layout in call settings or change it programmatically during the call. ## Available Layouts ### Tile Layout The default grid layout that displays all participants equally sized in a grid pattern. ```tsx theme={null} CometChatCalls.setLayout('TILE'); ``` ### Sidebar Layout Displays one main participant with other participants in a sidebar. Useful when focusing on a presenter or active speaker. ```tsx theme={null} CometChatCalls.setLayout('SIDEBAR'); ``` ### Spotlight Layout Focuses on a single participant with minimal UI for others. Ideal for presentations or when one participant needs full attention. ```tsx theme={null} CometChatCalls.setLayout('SPOTLIGHT'); ``` ## Set Initial Layout Configure the initial layout when creating call settings: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; const sessionSettings = { layout: 'TILE', // or 'SIDEBAR' or 'SPOTLIGHT' }; ``` | Layout | Description | | - | - | | `'TILE'` | Starts with Tile layout | | `'SIDEBAR'` | Starts with Sidebar layout | | `'SPOTLIGHT'` | Starts with Spotlight layout | ## Change Layout During Call Change the layout programmatically at any time during the call: ```tsx theme={null} // Switch to Tile layout CometChatCalls.setLayout('TILE'); // Switch to Sidebar layout CometChatCalls.setLayout('SIDEBAR'); // Switch to Spotlight layout CometChatCalls.setLayout('SPOTLIGHT'); ``` ## Listen for Layout Changes Subscribe to layout change events: ```tsx theme={null} const unsubscribe = CometChatCalls.addEventListener('onCallLayoutChanged', (layout) => { console.log('Layout changed to:', layout); // Update UI state if needed }); // Cleanup unsubscribe(); ``` ## Spotlight Mode Options When using Spotlight layout, you can configure video tile interactions: ```tsx theme={null} const sessionSettings = { layout: 'SPOTLIGHT', enableSpotlightSwap: true, // Allow clicking tiles to spotlight enableSpotlightDrag: true, // Allow dragging tiles }; ``` | Option | Default | Description | | - | - | - | | `enableSpotlightSwap` | `true` | Click a participant tile to spotlight them | | `enableSpotlightDrag` | `true` | Drag tiles to reposition in Spotlight mode | ## Pin Participant Pin a specific participant to the main view in Sidebar or Spotlight layouts: ```tsx theme={null} // Pin a participant const participantId = 'participant_pid'; CometChatCalls.pinParticipant(participantId, 'human'); // Pin a screen share CometChatCalls.pinParticipant(participantId, 'screen-share'); // Unpin CometChatCalls.unpinParticipant(); ``` ## Automatic Layout Changes The SDK automatically switches to Sidebar layout when: * A participant starts screen sharing * A participant is pinned When screen sharing stops or the participant is unpinned, the layout returns to the previous state if it was programmatically set. ## Complete Example ```tsx theme={null} import React, { useState, useEffect } from 'react'; import { View, TouchableOpacity, Text, StyleSheet } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; type Layout = 'TILE' | 'SIDEBAR' | 'SPOTLIGHT'; function LayoutControls() { const [currentLayout, setCurrentLayout] = useState('TILE'); useEffect(() => { const unsubscribe = CometChatCalls.addEventListener( 'onCallLayoutChanged', (layout: Layout) => { setCurrentLayout(layout); } ); return () => unsubscribe(); }, []); const layouts: Layout[] = ['TILE', 'SIDEBAR', 'SPOTLIGHT']; return ( Layout: {currentLayout} {layouts.map((layout) => ( CometChatCalls.setLayout(layout)} > {layout} ))} ); } const styles = StyleSheet.create({ container: { padding: 16, }, label: { color: '#fff', fontSize: 14, marginBottom: 8, }, buttons: { flexDirection: 'row', gap: 8, }, button: { backgroundColor: '#333', paddingHorizontal: 16, paddingVertical: 8, borderRadius: 8, }, activeButton: { backgroundColor: '#6851D6', }, buttonText: { color: '#999', fontSize: 12, fontWeight: '600', }, activeButtonText: { color: '#fff', }, }); export default LayoutControls; ``` ## Related Documentation * [Actions](/docs/calls/react-native/actions) - Control the call programmatically * [Participant Management](/docs/calls/react-native/participant-management) - Pin and manage participants * [Screen Sharing](/docs/calls/react-native/screen-sharing) - Share your screen # Call Logs Source: https://www.cometchat.com/docs/calls/react-native/call-logs Display CometChat Calls SDK v5 call logs on React Native with call history, participants, call type, duration, and status details. Call logs provide a history of calls made through your application. You can retrieve call logs using the CometChat Chat SDK's call log APIs. > [!NOTE] > > Call logs are managed by the CometChat Chat SDK, not the Calls SDK. Ensure you have the Chat SDK integrated to access call history. ## Prerequisites To use call logs, you need: 1. CometChat Chat SDK integrated (`@cometchat/chat-sdk-react-native`) 2. User authenticated with the Chat SDK ## Retrieve Call Logs Use the Calls SDK's `CallLogRequestBuilder` to fetch call logs. It needs the logged-in user's auth token: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; async function fetchCallLogs() { const callLogRequest = new CometChatCalls.CallLogRequestBuilder() .setAuthToken(CometChatCalls.getUserAuthToken() ?? '') .setLimit(30) .setCallStatus('ended') // 'ongoing', 'busy', 'rejected', 'cancelled', 'ended', 'missed' .build(); try { const callLogs = await callLogRequest.fetchNext(); console.log('Call logs:', callLogs); return callLogs; } catch (error) { console.error('Error fetching call logs:', error); throw error; } } ``` ## CallLogRequestBuilder Options | Method | Type | Description | | - | - | - | | `setLimit(limit)` | number | Maximum number of logs to fetch (default: 30, max: 100) | | `setCallStatus(status)` | string | Filter by call status | | `setCallType(type)` | string | Filter by call type (`audio` or `video`) | | `setCallCategory(category)` | string | Filter by category: `call` or `meet` | | `setCallDirection(direction)` | string | Filter by direction: `incoming` or `outgoing` | | `setUid(uid)` | string | Calls with this user | | `setGuid(guid)` | string | Calls with this group | | `setHasRecording(hasRecording)` | boolean | Only calls with a recording | | `setHasTranscriptions(hasTranscriptions)` | boolean | Only calls with transcripts | | `setAuthToken(token)` | string | Auth token for the request | ### Call Status Values | Status | Description | | - | - | | `ongoing` | Currently active calls | | `ended` | Completed calls | | `cancelled` | Calls cancelled by the initiator | | `rejected` | Calls rejected by the receiver | | `busy` | Calls where the receiver was busy | | `missed` | Calls that weren't answered | ## Call Log Object Each call log is a `CallLog` object. Read it through its getters: | Getter | Returns | Description | | - | - | - | | `getSessionID()` | string | Unique session identifier | | `getInitiator()` | `CallUser` | User who initiated the call | | `getReceiver()` | `CallUser` or `CallGroup` | Call recipient | | `getReceiverType()` | string | `user` or `group` | | `getStatus()` | string | Final status of the call | | `getType()` | string | `audio` or `video` | | `getInitiatedAt()` | number | Timestamp when the call was initiated | | `getStartedAt()` | number | Timestamp when the call started | | `getEndedAt()` | number | Timestamp when the call ended | | `getTotalDuration()` | string | Call duration | | `getParticipants()` | `Participant[]` | List of participants | | `getRecordings()` | `Recording[]` | List of recordings (if any) | | `getTranscriptions()` | `Transcription[]` | List of transcripts. Only attached when the request opts in with `setHasTranscriptions(true)` | ## Filter by User Get call logs for a specific user: ```tsx theme={null} const callLogRequest = new CometChatCalls.CallLogRequestBuilder() .setAuthToken(CometChatCalls.getUserAuthToken() ?? '') .setLimit(30) .setUid('user_uid') .build(); ``` ## Filter by Group Get call logs for a specific group: ```tsx theme={null} const callLogRequest = new CometChatCalls.CallLogRequestBuilder() .setAuthToken(CometChatCalls.getUserAuthToken() ?? '') .setLimit(30) .setGuid('group_guid') .build(); ``` ## Pagination Fetch call logs in pages: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; type CallLogRequest = ReturnType['build']>; class CallLogManager { private callLogRequest: CallLogRequest; constructor() { this.callLogRequest = new CometChatCalls.CallLogRequestBuilder() .setAuthToken(CometChatCalls.getUserAuthToken() ?? '') .setLimit(30) .build(); } async fetchNextPage() { try { const callLogs = await this.callLogRequest.fetchNext(); return callLogs; } catch (error) { console.error('Error fetching call logs:', error); throw error; } } } // Usage const manager = new CallLogManager(); // First page const page1 = await manager.fetchNextPage(); // Next page const page2 = await manager.fetchNextPage(); ``` ## Transcripts *Available since v5.0.5* Use the Calls SDK's `CallLogRequestBuilder` to fetch only calls that were transcribed. Opting in also makes the server attach each call's transcripts to the log: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; const callLogRequest = new CometChatCalls.CallLogRequestBuilder() .setLimit(30) .setHasTranscriptions(true) .build(); const callLogs = await callLogRequest.fetchNext(); callLogs.forEach((callLog) => { callLog.getTranscriptions().forEach((transcription) => { console.log(transcription.getTid(), transcription.getTranscriptURL()); }); }); ``` `getTranscriptions()` returns an empty array when the server omitted transcripts, so it never needs a null check. To page through a session's transcripts directly, use [`TranscriptRequestBuilder`](/docs/calls/react-native/transcription#retrieving-transcripts). ## Complete Example ```tsx theme={null} import React, { useState, useEffect, useCallback } from 'react'; import { View, FlatList, Text, StyleSheet, ActivityIndicator } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; type CallLogRequest = ReturnType['build']>; type CallLog = InstanceType; function CallLogsScreen() { const [callLogs, setCallLogs] = useState([]); const [loading, setLoading] = useState(true); const [loadingMore, setLoadingMore] = useState(false); const [callLogRequest, setCallLogRequest] = useState(null); useEffect(() => { const request = new CometChatCalls.CallLogRequestBuilder() .setAuthToken(CometChatCalls.getUserAuthToken() ?? '') .setLimit(30) .build(); setCallLogRequest(request); fetchCallLogs(request); }, []); const fetchCallLogs = async (request: CallLogRequest) => { try { const logs = await request.fetchNext(); setCallLogs(logs); } catch (error) { console.error('Error fetching call logs:', error); } finally { setLoading(false); } }; const loadMore = useCallback(async () => { if (!callLogRequest || loadingMore) return; setLoadingMore(true); try { const moreLogs = await callLogRequest.fetchNext(); setCallLogs((prev) => [...prev, ...moreLogs]); } catch (error) { console.error('Error loading more:', error); } finally { setLoadingMore(false); } }, [callLogRequest, loadingMore]); const formatDate = (timestamp: number) => { return new Date(timestamp * 1000).toLocaleString(); }; const renderCallLog = ({ item }: { item: CallLog }) => ( {item.getInitiator().getName()} → {item.getReceiver().getName()} {item.getType()} • {item.getStatus()} {formatDate(item.getInitiatedAt())} {item.getTotalDuration() || '-'} ); if (loading) { return ( ); } return ( item.getSessionID()} renderItem={renderCallLog} onEndReached={loadMore} onEndReachedThreshold={0.5} ListFooterComponent={ loadingMore ? : null } ListEmptyComponent={ No call logs } /> ); } const styles = StyleSheet.create({ centered: { flex: 1, justifyContent: 'center', alignItems: 'center', }, callLogItem: { flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center', padding: 16, borderBottomWidth: 1, borderBottomColor: '#eee', }, callInfo: { flex: 1, }, participantName: { fontSize: 16, fontWeight: '600', }, callDetails: { fontSize: 14, color: '#666', marginTop: 4, }, callTime: { fontSize: 12, color: '#999', marginTop: 4, }, duration: { fontSize: 14, color: '#333', }, footer: { padding: 16, }, emptyText: { fontSize: 16, color: '#999', }, }); export default CallLogsScreen; ``` ## Related Documentation * [Recording](/docs/calls/react-native/recording) - Access call recordings * [Transcription](/docs/calls/react-native/transcription) - Retrieve call transcripts * [Ringing](/docs/calls/react-native/ringing) - Implement call notifications # Custom Control Panel Source: https://www.cometchat.com/docs/calls/react-native/custom-control-panel Customize the CometChat Calls SDK v5 control panel on React Native with call buttons, actions, layout, and user controls. Build a custom control panel to replace or extend the default call controls. Hide the default layout and implement your own UI using the SDK's action methods. ## Hide Default Layout Disable the default control panel to use your own: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; const sessionSettings = { hideControlPanel: true, }; ``` ## Available Actions Use these methods to control the call from your custom UI: | Action | Method | Description | | - | - | - | | Mute Audio | `CometChatCalls.muteAudio()` | Mute local microphone | | Unmute Audio | `CometChatCalls.unmuteAudio()` | Unmute local microphone | | Pause Video | `CometChatCalls.pauseVideo()` | Stop sending video | | Resume Video | `CometChatCalls.resumeVideo()` | Resume sending video | | Switch Camera | `CometChatCalls.switchCamera()` | Toggle front/rear camera | | Leave Session | `CometChatCalls.leaveSession()` | End the call | | Raise Hand | `CometChatCalls.raiseHand()` | Raise hand | | Lower Hand | `CometChatCalls.lowerHand()` | Lower hand | | Set Layout | `CometChatCalls.setLayout(layout)` | Change call layout | | Start Recording | `CometChatCalls.startRecording()` | Start recording | | Stop Recording | `CometChatCalls.stopRecording()` | Stop recording | | Enable PiP | `CometChatCalls.enablePictureInPictureLayout()` | Enter PiP mode | | Disable PiP | `CometChatCalls.disablePictureInPictureLayout()` | Exit PiP mode | ## Complete Example ```tsx theme={null} import React, { useState, useEffect } from 'react'; import { View, TouchableOpacity, Text, StyleSheet, SafeAreaView } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; interface CustomControlPanelProps { isAudioOnly?: boolean; } function CustomControlPanel({ isAudioOnly = false }: CustomControlPanelProps) { const [isAudioMuted, setIsAudioMuted] = useState(false); const [isVideoMuted, setIsVideoMuted] = useState(false); const [isHandRaised, setIsHandRaised] = useState(false); const [isRecording, setIsRecording] = useState(false); const [currentLayout, setCurrentLayout] = useState<'TILE' | 'SIDEBAR' | 'SPOTLIGHT'>('TILE'); useEffect(() => { const controller = new AbortController(); const { signal } = controller; // Listen for media events CometChatCalls.addEventListener( 'onAudioMuted', () => setIsAudioMuted(true), { signal } ); CometChatCalls.addEventListener( 'onAudioUnMuted', () => setIsAudioMuted(false), { signal } ); CometChatCalls.addEventListener( 'onVideoPaused', () => setIsVideoMuted(true), { signal } ); CometChatCalls.addEventListener( 'onVideoResumed', () => setIsVideoMuted(false), { signal } ); CometChatCalls.addEventListener( 'onRecordingStarted', () => setIsRecording(true), { signal } ); CometChatCalls.addEventListener( 'onRecordingStopped', () => setIsRecording(false), { signal } ); CometChatCalls.addEventListener( 'onCallLayoutChanged', (layout: 'TILE' | 'SIDEBAR' | 'SPOTLIGHT') => setCurrentLayout(layout), { signal } ); return () => controller.abort(); }, []); const toggleAudio = () => { if (isAudioMuted) { CometChatCalls.unmuteAudio(); } else { CometChatCalls.muteAudio(); } }; const toggleVideo = () => { if (isVideoMuted) { CometChatCalls.resumeVideo(); } else { CometChatCalls.pauseVideo(); } }; const toggleHand = () => { if (isHandRaised) { CometChatCalls.lowerHand(); setIsHandRaised(false); } else { CometChatCalls.raiseHand(); setIsHandRaised(true); } }; const toggleRecording = () => { if (isRecording) { CometChatCalls.stopRecording(); } else { CometChatCalls.startRecording(); } }; const cycleLayout = () => { const layouts: Array<'TILE' | 'SIDEBAR' | 'SPOTLIGHT'> = ['TILE', 'SIDEBAR', 'SPOTLIGHT']; const currentIndex = layouts.indexOf(currentLayout); const nextLayout = layouts[(currentIndex + 1) % layouts.length]; CometChatCalls.setLayout(nextLayout); }; const handleEndCall = () => { CometChatCalls.leaveSession(); }; return ( {/* Audio Toggle */} {isAudioMuted ? '🔇' : '🎤'} {isAudioMuted ? 'Unmute' : 'Mute'} {/* Video Toggle (only for video calls) */} {!isAudioOnly && ( {isVideoMuted ? '📷' : '🎥'} {isVideoMuted ? 'Show' : 'Hide'} )} {/* Switch Camera (only for video calls) */} {!isAudioOnly && ( CometChatCalls.switchCamera()} > 🔄 Flip )} {/* Raise Hand */} {isHandRaised ? '✋' : '🤚'} {isHandRaised ? 'Lower' : 'Raise'} {/* Layout Toggle */} 📐 {currentLayout} {/* Recording */} {isRecording ? '⏹️' : '⏺️'} {isRecording ? 'Stop' : 'Record'} {/* End Call */} 📞 End ); } const styles = StyleSheet.create({ container: { position: 'absolute', bottom: 0, left: 0, right: 0, backgroundColor: 'rgba(0, 0, 0, 0.8)', paddingVertical: 16, paddingHorizontal: 8, }, controlRow: { flexDirection: 'row', justifyContent: 'center', marginBottom: 12, gap: 12, }, controlButton: { alignItems: 'center', justifyContent: 'center', backgroundColor: '#333', width: 64, height: 64, borderRadius: 32, }, activeButton: { backgroundColor: '#6851D6', }, handRaisedButton: { backgroundColor: '#f59e0b', }, recordingButton: { backgroundColor: '#ef4444', }, endCallButton: { backgroundColor: '#dc2626', }, buttonIcon: { fontSize: 24, }, buttonLabel: { color: '#fff', fontSize: 10, marginTop: 4, }, }); export default CustomControlPanel; ``` ## Using with Call Component Combine the custom control panel with the call component: ```tsx theme={null} import React from 'react'; import { View, StyleSheet } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; import CustomControlPanel from './CustomControlPanel'; interface CallScreenProps { callToken: string; isAudioOnly?: boolean; } function CallScreen({ callToken, isAudioOnly = false }: CallScreenProps) { const sessionSettings = { hideControlPanel: true, // Hide default controls sessionType: isAudioOnly ? 'VOICE' : 'VIDEO', }; return ( ); } const styles = StyleSheet.create({ container: { flex: 1, backgroundColor: '#000', }, }); export default CallScreen; ``` ## Related Documentation * [Actions](/docs/calls/react-native/actions) - All available call actions * [Events](/docs/calls/react-native/events) - Listen for call events * [Session Settings](/docs/calls/react-native/session-settings) - Configure call settings # Custom Participant List Source: https://www.cometchat.com/docs/calls/react-native/custom-participant-list Customize the CometChat Calls SDK v5 participant list on React Native with participant views, actions, status, and layout. Build a custom participant list UI to display and manage call participants. Listen for participant events and use the SDK's management methods. ## Get Participants Listen for participant list changes: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; CometChatCalls.addEventListener('onParticipantListChanged', (participants) => { console.log('Participants:', participants); }); ``` ## Participant Object Each participant contains: | Property | Type | Description | | - | - | - | | `pid` | string | Participant ID (unique per session) | | `uid` | string | User ID | | `name` | string | Display name | | `avatar` | string | Avatar URL (optional) | ## Participant Events Subscribe to individual participant events: ```tsx theme={null} // Join/Leave CometChatCalls.addEventListener('onParticipantJoined', (participant) => { console.log(`${participant.name} joined`); }); CometChatCalls.addEventListener('onParticipantLeft', (participant) => { console.log(`${participant.name} left`); }); // Audio state CometChatCalls.addEventListener('onParticipantAudioMuted', (participant) => { console.log(`${participant.name} muted`); }); CometChatCalls.addEventListener('onParticipantAudioUnmuted', (participant) => { console.log(`${participant.name} unmuted`); }); // Video state CometChatCalls.addEventListener('onParticipantVideoPaused', (participant) => { console.log(`${participant.name} video paused`); }); CometChatCalls.addEventListener('onParticipantVideoResumed', (participant) => { console.log(`${participant.name} video resumed`); }); // Hand raised CometChatCalls.addEventListener('onParticipantHandRaised', (participant) => { console.log(`${participant.name} raised hand`); }); CometChatCalls.addEventListener('onParticipantHandLowered', (participant) => { console.log(`${participant.name} lowered hand`); }); // Screen sharing CometChatCalls.addEventListener('onParticipantStartedScreenShare', (participant) => { console.log(`${participant.name} started screen share`); }); CometChatCalls.addEventListener('onParticipantStoppedScreenShare', (participant) => { console.log(`${participant.name} stopped screen share`); }); // Dominant speaker CometChatCalls.addEventListener('onDominantSpeakerChanged', (participant) => { console.log(`Dominant speaker: ${participant.name}`); }); ``` ## Participant Actions Manage participants using these methods: ```tsx theme={null} // Pin participant CometChatCalls.pinParticipant(participantId, 'human'); // Unpin CometChatCalls.unpinParticipant(); // Mute participant (requires moderator) CometChatCalls.muteParticipant(participantId); // Pause participant video (requires moderator) CometChatCalls.pauseParticipantVideo(participantId); ``` ## Complete Example ```tsx theme={null} import React, { useState, useEffect } from 'react'; import { View, FlatList, Text, TouchableOpacity, StyleSheet, Image, Modal, } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; interface Participant { pid: string; uid: string; name: string; avatar?: string; } interface ParticipantState extends Participant { isAudioMuted: boolean; isVideoMuted: boolean; isHandRaised: boolean; isScreenSharing: boolean; isDominantSpeaker: boolean; } function CustomParticipantList() { const [participants, setParticipants] = useState>( new Map() ); const [pinnedId, setPinnedId] = useState(null); const [isVisible, setIsVisible] = useState(false); const [dominantSpeakerId, setDominantSpeakerId] = useState(null); useEffect(() => { const controller = new AbortController(); const { signal } = controller; // Participant list changes CometChatCalls.addEventListener( 'onParticipantListChanged', (list: Participant[]) => { setParticipants((prev) => { const newMap = new Map(prev); // Add new participants list.forEach((p) => { if (!newMap.has(p.pid)) { newMap.set(p.pid, { ...p, isAudioMuted: false, isVideoMuted: false, isHandRaised: false, isScreenSharing: false, isDominantSpeaker: false, }); } }); // Remove participants who left const currentPids = new Set(list.map((p) => p.pid)); newMap.forEach((_, pid) => { if (!currentPids.has(pid)) { newMap.delete(pid); } }); return newMap; }); }, { signal } ); // Audio state CometChatCalls.addEventListener( 'onParticipantAudioMuted', (p: Participant) => { updateParticipant(p.pid, { isAudioMuted: true }); }, { signal } ); CometChatCalls.addEventListener( 'onParticipantAudioUnmuted', (p: Participant) => { updateParticipant(p.pid, { isAudioMuted: false }); }, { signal } ); // Video state CometChatCalls.addEventListener( 'onParticipantVideoPaused', (p: Participant) => { updateParticipant(p.pid, { isVideoMuted: true }); }, { signal } ); CometChatCalls.addEventListener( 'onParticipantVideoResumed', (p: Participant) => { updateParticipant(p.pid, { isVideoMuted: false }); }, { signal } ); // Hand raised CometChatCalls.addEventListener( 'onParticipantHandRaised', (p: Participant) => { updateParticipant(p.pid, { isHandRaised: true }); }, { signal } ); CometChatCalls.addEventListener( 'onParticipantHandLowered', (p: Participant) => { updateParticipant(p.pid, { isHandRaised: false }); }, { signal } ); // Screen sharing CometChatCalls.addEventListener( 'onParticipantStartedScreenShare', (p: Participant) => { updateParticipant(p.pid, { isScreenSharing: true }); }, { signal } ); CometChatCalls.addEventListener( 'onParticipantStoppedScreenShare', (p: Participant) => { updateParticipant(p.pid, { isScreenSharing: false }); }, { signal } ); // Dominant speaker CometChatCalls.addEventListener( 'onDominantSpeakerChanged', (p: Participant) => { setDominantSpeakerId(p.pid); }, { signal } ); return () => controller.abort(); }, []); const updateParticipant = (pid: string, updates: Partial) => { setParticipants((prev) => { const newMap = new Map(prev); const participant = newMap.get(pid); if (participant) { newMap.set(pid, { ...participant, ...updates }); } return newMap; }); }; const handlePin = (participant: ParticipantState) => { if (pinnedId === participant.pid) { CometChatCalls.unpinParticipant(); setPinnedId(null); } else { CometChatCalls.pinParticipant(participant.pid, 'human'); setPinnedId(participant.pid); } }; const handleMute = (participant: ParticipantState) => { CometChatCalls.muteParticipant(participant.pid); }; const renderParticipant = ({ item }: { item: ParticipantState }) => ( {item.avatar ? ( ) : ( {item.name.charAt(0).toUpperCase()} )} {dominantSpeakerId === item.pid && ( )} {item.name} {item.isAudioMuted && 🔇} {item.isVideoMuted && 📷} {item.isHandRaised && ✋} {item.isScreenSharing && 🖥️} {pinnedId === item.pid && 📌} handlePin(item)} > {pinnedId === item.pid ? 'Unpin' : 'Pin'} handleMute(item)} > Mute ); const participantList = Array.from(participants.values()); return ( <> setIsVisible(true)} > 👥 {participantList.length} setIsVisible(false)} > Participants ({participantList.length}) setIsVisible(false)}> ✕ item.pid} renderItem={renderParticipant} ListEmptyComponent={ No participants } /> ); } const styles = StyleSheet.create({ toggleButton: { position: 'absolute', top: 60, right: 16, backgroundColor: 'rgba(0, 0, 0, 0.6)', paddingHorizontal: 16, paddingVertical: 8, borderRadius: 20, }, toggleButtonText: { color: '#fff', fontSize: 16, }, modalOverlay: { flex: 1, backgroundColor: 'rgba(0, 0, 0, 0.5)', justifyContent: 'flex-end', }, modalContent: { backgroundColor: '#1a1a1a', borderTopLeftRadius: 20, borderTopRightRadius: 20, maxHeight: '70%', }, modalHeader: { flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center', padding: 16, borderBottomWidth: 1, borderBottomColor: '#333', }, modalTitle: { color: '#fff', fontSize: 18, fontWeight: '600', }, closeButton: { color: '#fff', fontSize: 20, padding: 4, }, participantItem: { flexDirection: 'row', alignItems: 'center', padding: 12, borderBottomWidth: 1, borderBottomColor: '#333', }, avatarContainer: { position: 'relative', }, avatar: { width: 44, height: 44, borderRadius: 22, }, avatarPlaceholder: { width: 44, height: 44, borderRadius: 22, backgroundColor: '#6851D6', justifyContent: 'center', alignItems: 'center', }, avatarText: { color: '#fff', fontSize: 18, fontWeight: '600', }, speakingIndicator: { position: 'absolute', bottom: 0, right: 0, width: 14, height: 14, borderRadius: 7, backgroundColor: '#22c55e', borderWidth: 2, borderColor: '#1a1a1a', }, participantInfo: { flex: 1, marginLeft: 12, }, participantName: { color: '#fff', fontSize: 16, fontWeight: '500', }, statusIcons: { flexDirection: 'row', marginTop: 4, gap: 4, }, statusIcon: { fontSize: 14, }, actions: { flexDirection: 'row', gap: 8, }, actionButton: { backgroundColor: '#333', paddingHorizontal: 12, paddingVertical: 6, borderRadius: 4, }, actionText: { color: '#fff', fontSize: 12, }, emptyText: { color: '#666', textAlign: 'center', padding: 20, }, }); export default CustomParticipantList; ``` ## Related Documentation * [Participant Management](/docs/calls/react-native/participant-management) - Manage participants * [Events](/docs/calls/react-native/events) - All participant events * [Custom Control Panel](/docs/calls/react-native/custom-control-panel) - Build custom controls # Events Source: https://www.cometchat.com/docs/calls/react-native/events Handle CometChat Calls SDK v5 events on React Native for call lifecycle, participants, media state, errors, and real-time updates. The CometChat Calls SDK uses the `addEventListener` method to subscribe to call events for the call lifecycle, participants, media state, and real-time updates. ## addEventListener For more granular control, use `CometChatCalls.addEventListener()` to subscribe to specific events: ```tsx theme={null} const unsubscribe = CometChatCalls.addEventListener('onParticipantJoined', (participant) => { console.log('Participant joined:', participant); }); // Later, unsubscribe when no longer needed unsubscribe(); ``` ### Session Status Events | Event | Payload | Description | | - | - | - | | `onSessionJoined` | - | Successfully joined the session | | `onSessionLeft` | - | Left the session | | `onConnectionLost` | - | Connection to the session was lost | | `onConnectionRestored` | - | Connection was restored | | `onConnectionFailed` | Connection error | Failed to establish the connection to the session | | `onConnectionClosed` | - | Connection was closed | | `onSessionTimedOut` | - | Session timed out due to inactivity | ```tsx theme={null} CometChatCalls.addEventListener('onSessionJoined', () => { console.log('Successfully joined the session'); }); CometChatCalls.addEventListener('onSessionLeft', () => { console.log('Left the session'); }); CometChatCalls.addEventListener('onConnectionLost', () => { console.log('Connection lost - attempting to reconnect'); }); CometChatCalls.addEventListener('onConnectionRestored', () => { console.log('Connection restored'); }); CometChatCalls.addEventListener('onConnectionFailed', (error) => { console.log('Connection failed:', error); }); CometChatCalls.addEventListener('onSessionTimedOut', () => { console.log('Session timed out'); }); ``` ### Media Events | Event | Payload | Description | | - | - | - | | `onAudioMuted` | - | Local audio was muted | | `onAudioUnMuted` | - | Local audio was unmuted | | `onVideoPaused` | - | Local video was paused | | `onVideoResumed` | - | Local video was resumed | | `onRecordingStarted` | - | Recording started | | `onRecordingStopped` | - | Recording stopped | | `onScreenShareStarted` | - | Screen sharing started | | `onScreenShareStopped` | - | Screen sharing stopped | | `onAudioModeChanged` | Audio mode | Audio output mode changed | | `onCameraFacingChanged` | Camera facing | Camera switched (front/rear) | ```tsx theme={null} CometChatCalls.addEventListener('onAudioMuted', () => { console.log('Audio muted'); }); CometChatCalls.addEventListener('onAudioUnMuted', () => { console.log('Audio unmuted'); }); CometChatCalls.addEventListener('onVideoPaused', () => { console.log('Video paused'); }); CometChatCalls.addEventListener('onVideoResumed', () => { console.log('Video resumed'); }); CometChatCalls.addEventListener('onAudioModeChanged', (mode) => { console.log('Audio mode changed to:', mode); }); CometChatCalls.addEventListener('onCameraFacingChanged', (facing) => { console.log('Camera facing:', facing); // 'FRONT' or 'REAR' }); ``` ### Participant Events | Event | Payload | Description | | - | - | - | | `onParticipantConnected` | Participant | A participant's device prepared the session without joining. On the caller's prepared session this is the callee ringing | | `onParticipantJoined` | Participant | A participant joined. On the caller's prepared session this is the callee answering: join now | | `onParticipantLeft` | Participant | A participant left | | `onParticipantAudioMuted` | Participant | A participant muted their audio | | `onParticipantAudioUnmuted` | Participant | A participant unmuted their audio | | `onParticipantVideoPaused` | Participant | A participant paused their video | | `onParticipantVideoResumed` | Participant | A participant resumed their video | | `onParticipantHandRaised` | Participant | A participant raised their hand | | `onParticipantHandLowered` | Participant | A participant lowered their hand | | `onParticipantStartedScreenShare` | Participant | A participant started screen sharing | | `onParticipantStoppedScreenShare` | Participant | A participant stopped screen sharing | | `onParticipantStartedRecording` | Participant | A participant started recording | | `onParticipantStoppedRecording` | Participant | A participant stopped recording | | `onDominantSpeakerChanged` | Participant | The dominant speaker changed | | `onParticipantListChanged` | Participant array | The participant list changed | ```tsx theme={null} CometChatCalls.addEventListener('onParticipantJoined', (participant) => { console.log('Participant joined:', participant.name); }); CometChatCalls.addEventListener('onParticipantLeft', (participant) => { console.log('Participant left:', participant.name); }); CometChatCalls.addEventListener('onParticipantListChanged', (participants) => { console.log('Total participants:', participants.length); }); CometChatCalls.addEventListener('onParticipantHandRaised', (participant) => { console.log('Hand raised by:', participant.name); }); CometChatCalls.addEventListener('onDominantSpeakerChanged', (participant) => { console.log('Dominant speaker:', participant.name); }); ``` ### Button Click Events | Event | Payload | Description | | - | - | - | | `onLeaveSessionButtonClicked` | - | Leave session button clicked | | `onRaiseHandButtonClicked` | - | Raise hand button clicked | | `onShareInviteButtonClicked` | - | Share invite button clicked | | `onChangeLayoutButtonClicked` | - | Change layout button clicked | | `onParticipantListButtonClicked` | - | Participant list button clicked | | `onToggleAudioButtonClicked` | - | Toggle audio button clicked | | `onToggleVideoButtonClicked` | - | Toggle video button clicked | | `onRecordingToggleButtonClicked` | - | Recording toggle button clicked | | `onScreenShareButtonClicked` | - | Screen share button clicked | | `onChatButtonClicked` | - | Chat button clicked | | `onSwitchCameraButtonClicked` | - | Switch camera button clicked | ```tsx theme={null} CometChatCalls.addEventListener('onLeaveSessionButtonClicked', () => { console.log('Leave button clicked'); // Handle leave confirmation }); CometChatCalls.addEventListener('onChatButtonClicked', () => { console.log('Chat button clicked'); // Open chat interface }); ``` ### Layout Events | Event | Payload | Description | | - | - | - | | `onCallLayoutChanged` | Layout | The call layout changed | | `onParticipantListVisible` | - | Participant list became visible | | `onParticipantListHidden` | - | Participant list was hidden | | `onPictureInPictureLayoutEnabled` | - | PiP mode was enabled | | `onPictureInPictureLayoutDisabled` | - | PiP mode was disabled | ```tsx theme={null} CometChatCalls.addEventListener('onCallLayoutChanged', (layout) => { console.log('Layout changed to:', layout); // 'TILE', 'SIDEBAR', or 'SPOTLIGHT' }); CometChatCalls.addEventListener('onPictureInPictureLayoutEnabled', () => { console.log('PiP enabled'); }); ``` ## Participant Object The participant object contains: | Property | Type | Description | | - | - | - | | `pid` | string | Participant ID | | `uid` | string | User ID | | `name` | string | Display name | | `avatar` | string | Avatar URL (optional) | ## Complete Example ```tsx theme={null} import React, { useEffect } from 'react'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; function useCallEvents(onCallEnd: () => void) { useEffect(() => { const controller = new AbortController(); const { signal } = controller; // Session events CometChatCalls.addEventListener('onSessionJoined', () => { console.log('Joined session'); }, { signal }); CometChatCalls.addEventListener('onSessionLeft', () => { console.log('Left session'); onCallEnd(); }, { signal }); CometChatCalls.addEventListener('onSessionTimedOut', () => { console.log('Session timed out'); onCallEnd(); }, { signal }); // Participant events CometChatCalls.addEventListener('onParticipantJoined', (participant) => { console.log(`${participant.name} joined`); }, { signal }); CometChatCalls.addEventListener('onParticipantLeft', (participant) => { console.log(`${participant.name} left`); }, { signal }); // Media events CometChatCalls.addEventListener('onAudioModeChanged', (mode) => { console.log('Audio mode:', mode); }, { signal }); // Layout events CometChatCalls.addEventListener('onCallLayoutChanged', (layout) => { console.log('Layout:', layout); }, { signal }); // Cleanup return () => controller.abort(); }, [onCallEnd]); } export default useCallEvents; ``` ## Events on a prepared session `CometChatCalls.getActiveSession()` returns the session as soon as it is **prepared** — which is what `initiateCall` does on the caller and what the Push SDK's ring does on the callee — before anyone has joined. Listening on it is what lets a caller show "Ringing…" and detect the answer without joining first. ```ts theme={null} const session = CometChatCalls.getActiveSession(); // null when no session is prepared or joined const me = CometChatCalls.getLoggedInUser()?.uid; session?.addEventListener('onParticipantConnected', p => { if (p.uid !== me) setStatus('Ringing…'); // the callee's device got the push }); session?.addEventListener('onParticipantJoined', p => { if (p.uid !== me) join(); // the callee answered }); ``` | Event | On a prepared session it means | | - | - | | `onParticipantConnected` | The other device prepared the session: it is ringing there | | `onParticipantJoined` | The other side answered | | `onSessionTimedOut` | A joined session ended after being idle. A prepared session that nobody joins fires `onConnectionClosed` instead | | `onConnectionClosed` | The call ended before anyone joined (declined, cancelled from another device, or the room went away) | > [!WARNING] > > **A participant who has only prepared isn't in the roster.** A callee whose device has prepared the session reaches the caller as `onParticipantConnected`, not `onParticipantJoined`, and that is the only caller-side signal that the callee's device has been reached. Participants who have actually joined are reported as usual, including to a session that is still prepared, so handle a callee who is already there. *** ## Incoming call events On React Native these come from the Push Notifications SDK, not the Calls SDK. They report a call for the logged-in user starting and ending, whether it arrived by push while the app was killed or while it was running. ```ts theme={null} import { CometChatVoipNotifications } from '@cometchat/push-notifications-voip-react-native'; const offRinging = CometChatVoipNotifications.onCallRinging(call => { /* ringing */ }); const offAccepted = CometChatVoipNotifications.onCallAccepted(call => { /* answered here */ }); const offEnded = CometChatVoipNotifications.onCallEnded(e => { /* e.reason */ }); const offRingEnded = CometChatVoipNotifications.onRingEnded(e => { /* the ring stopped */ }); ``` | Event | Payload | Description | | - | - | - | | `onCallRinging` | `PNCallInfo` | A call for the logged-in user is ringing | | `onCallAccepted` | `PNCallInfo` | The user answered; open your call screen | | `onCallEnded` | `PNCallEndEvent` | The call ended. Caller: `declined`, `timedOut`, `cancelled`. Callee still ringing: `cancelled`, `answeredElsewhere`, `declined`, `timedOut`. The raw wire action is on `PNCallEndEvent.callAction` | | `onRingEnded` | `PNRingEndEvent` | The ring stopped, whatever happened to the call | Each returns an unsubscribe function. Subscribing late is safe: a call answered before your component mounted is held and delivered to the first subscriber. See [Ringing](/docs/calls/react-native/ringing). *** ## Login events `CometChatCalls.addLoginListener` reports the Calls SDK login state. The Push SDK uses it to keep the identity its ring gates read in step with the logged-in user; your app can use it to gate call UI. ```ts theme={null} CometChatCalls.addLoginListener('my-app', { onLoginSuccess: user => console.log('logged in as', user.uid), onLogoutSuccess: () => console.log('logged out'), }); CometChatCalls.removeLoginListener('my-app'); ``` > [!NOTE] > > Listener ids are keys: registering the same id twice replaces the earlier listener. Remove it when the screen goes away. The `User` the Calls SDK hands back is a plain object with a `uid` field, not a class with `getUid()`. *** ## Related Documentation * [Ringing](/docs/calls/react-native/ringing) - Start, answer and end calls * [Actions](/docs/calls/react-native/actions) - Control the call programmatically * [Session Settings](/docs/calls/react-native/session-settings) - Configure event listeners * [Participant Management](/docs/calls/react-native/participant-management) - Manage participants # Idle Timeout Source: https://www.cometchat.com/docs/calls/react-native/idle-timeout Configure CometChat Calls SDK v5 idle timeout on React Native to handle inactive participants and call session cleanup. The idle timeout feature automatically ends a call session when a participant is alone for a specified period. This prevents abandoned calls from running indefinitely. ## Configure Idle Timeout Set the idle timeout period when creating call settings: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; const sessionSettings = { idleTimeoutPeriodBeforePrompt: 180000, // 180 seconds (3 minutes) idleTimeoutPeriodAfterPrompt: 120000, // 120 seconds (2 minutes) }; ``` | Parameter | Type | Default | Description | | - | - | - | - | | `idleTimeoutPeriodBeforePrompt` | number | `60000` | Milliseconds you may remain alone in the call before the idle prompt appears | | `idleTimeoutPeriodAfterPrompt` | number | `180000` | Milliseconds the prompt stays on screen waiting for a response before the session ends | ## How It Works 1. When all other participants leave the call, the idle timeout timer starts 2. A prompt appears 60 seconds before the timeout, allowing the user to extend the session 3. If the user doesn't respond, the session ends automatically 4. If another participant joins, the timer is cancelled ## Listen for Timeout Events ### Session Timeout Event Listen for when the session times out: ```tsx theme={null} CometChatCalls.addEventListener('onSessionTimedOut', () => { console.log('Session timed out due to inactivity'); // Navigate away from call screen }); ``` ## Disable Idle Timeout Set a very high value to effectively disable the timeout: ```tsx theme={null} const sessionSettings = { idleTimeoutPeriodBeforePrompt: 86400000, // 24 hours }; ``` ## Complete Example ```tsx theme={null} import React, { useEffect, useCallback } from 'react'; import { Alert } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; interface CallScreenProps { sessionId: string; onCallEnd: () => void; } function CallScreen({ sessionId, onCallEnd }: CallScreenProps) { const handleSessionTimeout = useCallback(() => { Alert.alert( 'Session Ended', 'The call has ended due to inactivity.', [ { text: 'OK', onPress: onCallEnd, }, ] ); }, [onCallEnd]); useEffect(() => { const unsubscribe = CometChatCalls.addEventListener( 'onSessionTimedOut', handleSessionTimeout ); return () => unsubscribe(); }, [handleSessionTimeout]); useEffect(() => { async function initializeCall() { try { const { token } = await CometChatCalls.generateToken(sessionId); const sessionSettings = { idleTimeoutPeriodBeforePrompt: 180000, // 3 minutes idleTimeoutPeriodAfterPrompt: 120000, // 2 minutes }; // Render call component with token and sessionSettings } catch (error) { console.error('Failed to initialize call:', error); } } initializeCall(); }, [sessionId, handleSessionTimeout, onCallEnd]); // ... render call UI return null; } export default CallScreen; ``` ## Timeout Behavior | Scenario | Behavior | | - | - | | User is alone | Timer starts counting down | | Another participant joins | Timer is cancelled | | User extends session | Timer resets | | Timer expires | Session ends, `onSessionTimedOut` fires | ## Related Documentation * [Session Settings](/docs/calls/react-native/session-settings) - Configure call settings * [Events](/docs/calls/react-native/events) - Handle timeout events * [Join Session](/docs/calls/react-native/join-session) - Start a call session # In-Call Chat Source: https://www.cometchat.com/docs/calls/react-native/in-call-chat Enable in-call chat in CometChat Calls SDK v5 on React Native so participants can send messages during active calls. Enable messaging during calls by integrating the CometChat Chat SDK. Users can send and receive text messages while on a call. > [!NOTE] > > In-call chat requires the CometChat Chat SDK (`@cometchat/chat-sdk-react-native`) for messaging functionality. ## Prerequisites 1. CometChat Chat SDK integrated 2. User authenticated with the Chat SDK 3. Active call session ## Update Chat Button Badge Update the unread message count on the chat button: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; // Set unread count CometChatCalls.setChatButtonUnreadCount(5); // Clear unread count CometChatCalls.setChatButtonUnreadCount(0); ``` ## Listen for Chat Button Click Handle when the user clicks the chat button: ```tsx theme={null} CometChatCalls.addEventListener('onChatButtonClicked', () => { console.log('Chat button clicked'); // Open chat interface }); ``` ## Send Messages Use the Chat SDK to send messages during a call: ```tsx theme={null} import { CometChat } from '@cometchat/chat-sdk-react-native'; async function sendMessage(receiverId: string, text: string, receiverType: string) { const message = new CometChat.TextMessage( receiverId, text, receiverType ); try { const sentMessage = await CometChat.sendMessage(message); console.log('Message sent:', sentMessage); return sentMessage; } catch (error) { console.error('Error sending message:', error); throw error; } } // Send to user sendMessage('user_uid', 'Hello!', CometChat.RECEIVER_TYPE.USER); // Send to group sendMessage('group_guid', 'Hello everyone!', CometChat.RECEIVER_TYPE.GROUP); ``` ## Receive Messages Listen for incoming messages: ```tsx theme={null} import { CometChat } from '@cometchat/chat-sdk-react-native'; const listenerId = 'in_call_chat_listener'; CometChat.addMessageListener( listenerId, new CometChat.MessageListener({ onTextMessageReceived: (message) => { console.log('Text message received:', message); // Update UI and badge count }, onMediaMessageReceived: (message) => { console.log('Media message received:', message); }, }) ); // Remove listener when done CometChat.removeMessageListener(listenerId); ``` ## Complete Example ```tsx theme={null} import React, { useState, useEffect, useRef } from 'react'; import { View, FlatList, TextInput, TouchableOpacity, Text, StyleSheet, Modal, KeyboardAvoidingView, Platform, } from 'react-native'; import { CometChat } from '@cometchat/chat-sdk-react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; interface Message { id: string; text: string; sender: { uid: string; name: string; }; sentAt: number; isOwn: boolean; } interface InCallChatProps { receiverId: string; receiverType: string; } function InCallChat({ receiverId, receiverType }: InCallChatProps) { const [isVisible, setIsVisible] = useState(false); const [messages, setMessages] = useState([]); const [inputText, setInputText] = useState(''); const [unreadCount, setUnreadCount] = useState(0); const flatListRef = useRef(null); const currentUserId = useRef(''); useEffect(() => { // Get current user CometChat.getLoggedinUser().then(user => { if (user) { currentUserId.current = user.getUid(); } }); // Listen for chat button click const unsubscribeChatButton = CometChatCalls.addEventListener( 'onChatButtonClicked', () => { setIsVisible(true); setUnreadCount(0); CometChatCalls.setChatButtonUnreadCount(0); } ); // Listen for messages const listenerId = 'in_call_chat'; CometChat.addMessageListener( listenerId, new CometChat.MessageListener({ onTextMessageReceived: (message: any) => { const newMessage: Message = { id: message.getId().toString(), text: message.getText(), sender: { uid: message.getSender().getUid(), name: message.getSender().getName(), }, sentAt: message.getSentAt(), isOwn: message.getSender().getUid() === currentUserId.current, }; setMessages((prev) => [...prev, newMessage]); if (!isVisible) { setUnreadCount((prev) => { const newCount = prev + 1; CometChatCalls.setChatButtonUnreadCount(newCount); return newCount; }); } }, }) ); // Fetch previous messages fetchMessages(); return () => { unsubscribeChatButton(); CometChat.removeMessageListener(listenerId); }; }, []); const fetchMessages = async () => { try { const messagesRequest = new CometChat.MessagesRequestBuilder() .setUID(receiverId) .setLimit(50) .build(); const fetchedMessages = await messagesRequest.fetchPrevious(); const formattedMessages: Message[] = fetchedMessages .filter((msg: any) => msg.getType() === 'text') .map((msg: any) => ({ id: msg.getId().toString(), text: msg.getText(), sender: { uid: msg.getSender().getUid(), name: msg.getSender().getName(), }, sentAt: msg.getSentAt(), isOwn: msg.getSender().getUid() === currentUserId.current, })); setMessages(formattedMessages); } catch (error) { console.error('Error fetching messages:', error); } }; const sendMessage = async () => { if (!inputText.trim()) return; const text = inputText.trim(); setInputText(''); try { const message = new CometChat.TextMessage( receiverId, text, receiverType ); const sentMessage: any = await CometChat.sendMessage(message); const newMessage: Message = { id: sentMessage.getId().toString(), text: sentMessage.getText(), sender: { uid: sentMessage.getSender().getUid(), name: sentMessage.getSender().getName(), }, sentAt: sentMessage.getSentAt(), isOwn: true, }; setMessages((prev) => [...prev, newMessage]); // Scroll to bottom setTimeout(() => { flatListRef.current?.scrollToEnd(); }, 100); } catch (error) { console.error('Error sending message:', error); } }; const renderMessage = ({ item }: { item: Message }) => ( {!item.isOwn && ( {item.sender.name} )} {item.text} {new Date(item.sentAt * 1000).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', })} ); return ( <> {/* Chat toggle button with badge */} { setIsVisible(true); setUnreadCount(0); CometChatCalls.setChatButtonUnreadCount(0); }} > 💬 {unreadCount > 0 && ( {unreadCount > 99 ? '99+' : unreadCount} )} {/* Chat modal */} setIsVisible(false)} > Chat setIsVisible(false)}> ✕ item.id} renderItem={renderMessage} contentContainerStyle={styles.messagesList} onContentSizeChange={() => flatListRef.current?.scrollToEnd()} /> Send ); } const styles = StyleSheet.create({ chatButton: { position: 'absolute', top: 60, left: 16, backgroundColor: 'rgba(0, 0, 0, 0.6)', width: 48, height: 48, borderRadius: 24, justifyContent: 'center', alignItems: 'center', }, chatButtonText: { fontSize: 24, }, badge: { position: 'absolute', top: -4, right: -4, backgroundColor: '#ef4444', minWidth: 20, height: 20, borderRadius: 10, justifyContent: 'center', alignItems: 'center', paddingHorizontal: 4, }, badgeText: { color: '#fff', fontSize: 12, fontWeight: '600', }, modalContainer: { flex: 1, backgroundColor: 'rgba(0, 0, 0, 0.5)', justifyContent: 'flex-end', }, chatContainer: { backgroundColor: '#1a1a1a', borderTopLeftRadius: 20, borderTopRightRadius: 20, height: '60%', }, header: { flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center', padding: 16, borderBottomWidth: 1, borderBottomColor: '#333', }, headerTitle: { color: '#fff', fontSize: 18, fontWeight: '600', }, closeButton: { color: '#fff', fontSize: 20, padding: 4, }, messagesList: { padding: 16, }, messageContainer: { maxWidth: '80%', padding: 12, borderRadius: 16, marginBottom: 8, }, ownMessage: { alignSelf: 'flex-end', backgroundColor: '#6851D6', }, otherMessage: { alignSelf: 'flex-start', backgroundColor: '#333', }, senderName: { color: '#999', fontSize: 12, marginBottom: 4, }, messageText: { color: '#fff', fontSize: 16, }, messageTime: { color: 'rgba(255, 255, 255, 0.6)', fontSize: 10, marginTop: 4, alignSelf: 'flex-end', }, inputContainer: { flexDirection: 'row', padding: 12, borderTopWidth: 1, borderTopColor: '#333', alignItems: 'flex-end', }, input: { flex: 1, backgroundColor: '#333', borderRadius: 20, paddingHorizontal: 16, paddingVertical: 10, color: '#fff', maxHeight: 100, }, sendButton: { marginLeft: 8, backgroundColor: '#6851D6', paddingHorizontal: 16, paddingVertical: 10, borderRadius: 20, }, sendButtonText: { color: '#fff', fontWeight: '600', }, }); export default InCallChat; ``` ## Related Documentation * [Events](/docs/calls/react-native/events) - Chat button events * [Custom Control Panel](/docs/calls/react-native/custom-control-panel) - Build custom controls * [Ringing](/docs/calls/react-native/ringing) - Call signaling with Chat SDK # Join Session Source: https://www.cometchat.com/docs/calls/react-native/join-session Join CometChat Calls SDK v5 sessions on React Native with session IDs, call tokens, participant setup, and in-call UI launch. > [!NOTE] > > **Quick Reference for AI Agents & Developers** > > ```tsx theme={null} theme={null} > import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; > > // 1. a token for this session (init + login must already have resolved) > const { token } = await CometChatCalls.generateToken(sessionId); > > // 2. joining IS rendering — React Native has NO joinSession() > > callToken={token} > sessionSettings={{ sessionType: 'VIDEO', layout: 'TILE' }} > /> > > > // 3. teardown > CometChatCalls.leaveSession(); > ``` > > * The parent `View` **must be sized** (`flex: 1`) — an unsized parent renders the call invisibly > * `CometChatCalls` is a **singleton**: one active session, one mounted `Component`, and actions take no session id > * The `Component` already renders mute / video / camera / layout / leave — **do not add your own controls** > * **Related** → [Session Settings](/docs/calls/react-native/session-settings) · [Events](/docs/calls/react-native/events) · [Actions](/docs/calls/react-native/actions) This guide covers generating call tokens and joining call sessions using the CometChat Calls SDK. ## Generate Token Before joining a call, you need to generate a call token. The token authenticates the user for the specific call session. ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; const sessionId = 'UNIQUE_SESSION_ID'; try { const { token } = await CometChatCalls.generateToken(sessionId); console.log('Call token generated:', token); } catch (error) { console.error('Token generation failed:', error); } ``` | Parameter | Type | Required | Description | | - | - | - | - | | `sessionId` | string | Yes | Unique identifier for the call session | | `authToken` | string | No | User's auth token (uses logged-in user's token if not provided) | > [!NOTE] > > The `sessionId` should be unique for each call. You can use a UUID, a combination of user IDs, or any unique string that identifies the call session. ## Join Session with Component The `CometChatCalls.Component` renders the call UI. Pass the generated token and a plain `sessionSettings` object to join the session. Subscribe to call events with `CometChatCalls.addEventListener` and unsubscribe on cleanup. ```tsx theme={null} import React, { useState, useEffect } from 'react'; import { View, StyleSheet } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; interface CallScreenProps { sessionId: string; isAudioOnly?: boolean; } function CallScreen({ sessionId, isAudioOnly = false }: CallScreenProps) { const [callToken, setCallToken] = useState(null); // Plain session settings object const sessionSettings = { sessionType: isAudioOnly ? 'VOICE' : 'VIDEO', layout: 'TILE', hideLeaveSessionButton: false, hideToggleAudioButton: false, hideToggleVideoButton: isAudioOnly, } as const; useEffect(() => { async function initializeCall() { try { // Generate call token const { token } = await CometChatCalls.generateToken(sessionId); setCallToken(token); } catch (error) { console.error('Failed to initialize call:', error); } } initializeCall(); }, [sessionId]); useEffect(() => { // Subscribe to call events const controller = new AbortController(); const { signal } = controller; CometChatCalls.addEventListener('onParticipantJoined', (participant) => console.log('Participant joined:', participant.name) , { signal }); CometChatCalls.addEventListener('onParticipantLeft', (participant) => console.log('Participant left:', participant.name) , { signal }); CometChatCalls.addEventListener('onSessionLeft', () => console.log('Session left') , { signal }); return () => controller.abort(); }, []); if (!callToken) { return null; // Or show a loading indicator } return ( ); } const styles = StyleSheet.create({ container: { flex: 1, }, }); export default CallScreen; ``` > [!NOTE] > > **Two equivalent ways to remove a listener.** `addEventListener` **returns an unsubscribe function** and > also accepts an optional `AbortSignal`: > > ```ts theme={null} > static addEventListener(eventType, listener, options?: { signal?: AbortSignal }): () => void > ``` > > Call the returned function, or pass `{ signal }` and `abort()` the controller — one `AbortController` > removes every listener registered with its signal, which is why the examples here use it. Neither > supersedes the other; other pages show the unsubscribe form. ## Component Props | Prop | Type | Required | Description | | - | - | - | - | | `callToken` | string | Yes | Token generated from `generateToken()` | | `sessionSettings` | object | No | Plain session settings object | ## Complete Example ```tsx theme={null} import React, { useState, useEffect, useCallback } from 'react'; import { View, StyleSheet, ActivityIndicator, Text } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; interface CallScreenProps { sessionId: string; isAudioOnly?: boolean; onCallEnd?: () => void; } function CallScreen({ sessionId, isAudioOnly = false, onCallEnd }: CallScreenProps) { const [callToken, setCallToken] = useState(null); const [error, setError] = useState(null); const [isLoading, setIsLoading] = useState(true); const handleCallEnd = useCallback(() => { console.log('Call ended'); onCallEnd?.(); }, [onCallEnd]); // Plain session settings object const sessionSettings = { sessionType: isAudioOnly ? 'VOICE' : 'VIDEO', layout: 'TILE', hideLeaveSessionButton: false, hideToggleAudioButton: false, hideToggleVideoButton: isAudioOnly, hideSwitchCameraButton: isAudioOnly, hideAudioModeButton: false, startAudioMuted: false, startVideoPaused: false, audioMode: 'SPEAKER', hideRecordingButton: false, idleTimeoutPeriodBeforePrompt: 180000, } as const; useEffect(() => { async function initializeCall() { try { setIsLoading(true); setError(null); // Generate call token const { token } = await CometChatCalls.generateToken(sessionId); setCallToken(token); } catch (err: any) { console.error('Failed to initialize call:', err); setError(err.errorDescription || 'Failed to initialize call'); } finally { setIsLoading(false); } } initializeCall(); }, [sessionId]); useEffect(() => { // Subscribe to call events const controller = new AbortController(); const { signal } = controller; CometChatCalls.addEventListener('onParticipantJoined', (participant) => { console.log('Participant joined:', participant.name); }, { signal }); CometChatCalls.addEventListener('onParticipantLeft', (participant) => { console.log('Participant left:', participant.name); }, { signal }); CometChatCalls.addEventListener('onParticipantListChanged', (participants) => { console.log('Participants:', participants.length); }, { signal }); CometChatCalls.addEventListener('onSessionLeft', () => { handleCallEnd(); }, { signal }); CometChatCalls.addEventListener('onLeaveSessionButtonClicked', () => { console.log('Leave session button clicked'); CometChatCalls.leaveSession(); }, { signal }); CometChatCalls.addEventListener('onSessionTimedOut', () => { console.log('Session timed out'); handleCallEnd(); }, { signal }); CometChatCalls.addEventListener('onRecordingStarted', () => { console.log('Recording started'); }, { signal }); CometChatCalls.addEventListener('onRecordingStopped', () => { console.log('Recording stopped'); }, { signal }); return () => controller.abort(); }, [handleCallEnd]); if (isLoading) { return ( Joining call... ); } if (error) { return ( {error} ); } if (!callToken) { return null; } return ( ); } const styles = StyleSheet.create({ container: { flex: 1, backgroundColor: '#000', }, centered: { flex: 1, justifyContent: 'center', alignItems: 'center', backgroundColor: '#000', }, loadingText: { color: '#fff', marginTop: 16, fontSize: 16, }, errorText: { color: '#ff4444', fontSize: 16, textAlign: 'center', paddingHorizontal: 20, }, }); export default CallScreen; ``` ## One Session at a Time `CometChatCalls` is a singleton that holds a single active session. Render one `CometChatCalls.Component` at a time - joining a second session while one is in progress is not supported. Leave the current session first, wait for `onSessionLeft`, then join the next one. ```tsx theme={null} CometChatCalls.addEventListener('onSessionLeft', async () => { const { token } = await CometChatCalls.generateToken(nextSessionId); setCallToken(token); // Re-renders the component with the new session }, { signal }); CometChatCalls.leaveSession(); ``` This is also why `leaveSession()` and the other [actions](/docs/calls/react-native/actions) take no session ID - they always apply to the session that is currently active. See [Single Active Session](/docs/calls/react-native/overview#single-active-session) for the full behavior. ## Error Handling Common errors when joining a session: | Error Code | Description | | - | - | | `ERROR_SESSION_ID_MISSING` | Session ID is empty or not provided | | `ERROR_AUTH_TOKEN_MISSING` | User is not logged in or auth token is missing | | `ERROR_SDK_NOT_INITIALIZED` | SDK not initialized. Call `init()` first | ```tsx theme={null} try { const { token } = await CometChatCalls.generateToken(sessionId); } catch (error: any) { switch (error.errorCode) { case 'ERROR_SESSION_ID_MISSING': console.error('Please provide a valid session ID'); break; case 'ERROR_AUTH_TOKEN_MISSING': console.error('Please login before generating a token'); break; case 'ERROR_SDK_NOT_INITIALIZED': console.error('Please initialize the SDK first'); break; default: console.error('Error:', error.errorDescription); } } ``` ## Related Documentation * [Session Settings](/docs/calls/react-native/session-settings) - Configure call settings * [Actions](/docs/calls/react-native/actions) - Control the call programmatically * [Events](/docs/calls/react-native/events) - Handle call events # Changelog Source: https://www.cometchat.com/docs/calls/react-native/link/changelog Navigate to Changelog documentation. # GitHub Source: https://www.cometchat.com/docs/calls/react-native/link/github Navigate to GitHub documentation. # Sample Apps Source: https://www.cometchat.com/docs/calls/react-native/link/sample-apps Navigate to Sample Apps documentation. # Migrating from Legacy Ringing Source: https://www.cometchat.com/docs/calls/react-native/migrating-from-legacy-ringing Move a React Native app from Chat SDK call signalling and Push Notifications SDK 1.0 VoIP to ringing with the Calls SDK 5.1 and the Push Notifications SDK 2.0: what to add, what to delete, and how each method maps. Legacy ringing signalled calls through the Chat SDK: `CometChat.initiateCall` created the call, a `CallListener` on the WebSocket told the callee, `acceptCall` and `rejectCall` answered, and the app rang the device itself — usually with `react-native-callkeep` and `react-native-voip-push-notification` wired up by hand. Ringing now runs on the Calls SDK and the Push Notifications SDK's VoIP package. The Chat SDK's calling methods are deprecated. This page is the diff. For the full description of the current flow see [Ringing](/docs/calls/react-native/ringing); for the push side see [Push ringing](/docs/calls/react-native/voip-calling). ## Before you start Ringing with the Calls SDK is opt-in on the client: moving your app to the Calls SDK 5.1 and Push Notifications SDK 2.0 APIs below is the migration. While some of your users are still on legacy ringing, one dashboard setting lets the two flows call each other; see [While some users are still on legacy ringing](#while-some-users-are-still-on-legacy-ringing). If you use the CometChat UI Kit, keep its calling as it is: the Kit's call components still use the Chat SDK (`CometChat.initiateCall`, `CometChat.acceptCall`), so installing these packages doesn't move them to this flow. This guide applies to your own calling screens and handlers. See [Calling integration](/docs/ui-kit/react-native/calling-integration). ## Why it changed | Legacy | Now | | - | - | | Incoming calls arrived on the Chat WebSocket, so a killed or backgrounded app needed a separate push + CallKeep integration to ring | One path: the push rings in every app state, with the app killed included | | Four pieces of app code rang the device (listener, overlay, ringtone, busy check) | The Push SDK rings, draws the incoming screen, handles busy, timeout and missed calls | | `acceptCall` / `rejectCall` / `endCall` were HTTP calls your app had to sequence with the session | Answer = join. Decline, timeout and busy are sent by the Push SDK through a durable queue | | Caller only knew "accepted" or "rejected" | Caller sees "Ringing…" (the callee's device was reached), "answered", and the reason a call ended (`declined`, `timedOut`, `cancelled`, `answeredElsewhere`) | | Chat SDK required for calling | Chat SDK needed for chat only; a calls-only app works | ## Before and after ```mermaid theme={null} sequenceDiagram participant A as Caller participant Chat as Chat SDK (WebSocket) participant B as Callee rect rgb(240,240,240) Note over A,B: Legacy ringing A->>Chat: CometChat.initiateCall(call) Chat-->>B: CallListener.onIncomingCallReceived B->>B: App shows its own incoming UI, CallKeep, ringtone B->>Chat: CometChat.acceptCall(sessionId) Chat-->>A: CallListener.onOutgoingCallAccepted A->>A: start session B->>B: start session A->>Chat: CometChat.endCall(sessionId) Chat-->>B: onCallEndedMessageReceived end ``` ```mermaid theme={null} sequenceDiagram participant A as Caller participant BE as Backend participant P as Callee · Push SDK participant C as Callee · Calls SDK rect rgb(232,244,236) Note over A,C: Ringing now A->>BE: CometChatCalls.initiateCall(uid, options) BE-->>P: push (initiated) P->>P: rings, shows incoming screen / CallKit P->>C: connect(sessionId) C-->>A: onParticipantConnected ("Ringing…") P->>C: Answer → onCallAccepted → mount the call component C-->>A: onParticipantJoined → caller joins A->>A: session.leave() to hang up end ``` ## Step 1: Update dependencies ```bash theme={null} npm install @cometchat/calls-sdk-react-native@^5.1.0 \ @cometchat/push-notifications-react-native@^2.0.0 \ @cometchat/push-notifications-voip-react-native@^2.0.0 cd ios && pod install ``` * `minSdkVersion` 24 or higher on Android, iOS 15.1+. Below API 26 the ring posts a plain notification rather than the channel-backed, full-screen one. * Keep `google-services.json`. `@react-native-firebase/messaging` is optional: if you keep it, forward pushes to the package as in section 4.5 of the [Android push guide](/docs/notifications/react-native-push-notifications-android). * Remove `react-native-callkeep` and `react-native-voip-push-notification` if nothing else uses them; the VoIP package registers with PushKit and CallKit itself. > [!WARNING] > > `callMode` defaults to `'auto'`, which is what this page assumes. Installing the VoIP package is the opt-in: the core package detects it and installs the ringer. ## Step 2: Replace the push configuration > [tab] Before (Push SDK 1.0) > > ```ts theme={null} > // 1.0 had no appId or region of its own: it required the Chat SDK to be > // initialised and logged in first, and read both from it. > await CometChatPushNotifications.init({ > fcmProviderId: FCM_PROVIDER_ID, > apnsProviderId: APNS_PROVIDER_ID, > notificationSmallIcon: 'ic_notification', > voip: true, > }); > > // One package, so the call callbacks lived on it. 1.0 accepted the call > // through the Chat SDK itself; this fired afterwards. > CometChatPushNotifications.onCallAccepted(call => { > navigate('Call', { sessionId: call.sessionId }); > }); > ``` > [tab] After (Push SDK 2.0) > > ```ts theme={null} > await CometChatVoipNotifications.init(); // first, and with no config > > await CometChatPushNotifications.init({ > appId, region, > fcmProviderId: FCM_PROVIDER_ID, > apnsProviderId: APNS_PROVIDER_ID, > notificationSmallIcon: 'ic_notification', > callKitName: 'Acme', > }); > > CometChatVoipNotifications.onCallAccepted(call => { > navigate('Call', { sessionId: call.sessionId }); // no acceptCall to make > }); > ``` > [!WARNING] > > A **calls-only** app passes its configuration to `CometChatVoipNotifications.init(config)` instead and never calls the core's `init`. An app that does both must not pass a config to the VoIP `init()` — that re-runs the core initialisation and drops every chat option. > [!WARNING] > > **`onCallAccepted` and `onCallEnded` moved packages.** In 1.0 they were on `CometChatPushNotifications`; in 2.0 they are on `CometChatVoipNotifications`. The old names are gone rather than deprecated, so a call left on the core object throws `is not a function` — search your app for `CometChatPushNotifications.onCall` and repoint both. If your Chat and Calls SDKs point at a staging or dedicated deployment, pass the same host as `clientHost`. Otherwise the push token registers on the default host and no push ever arrives. ## Step 3: Make `init()` the first thing you await ```ts theme={null} // index.js / App.tsx await CometChatVoipNotifications.init(); // FIRST await CometChatUIKit.init(uiKitSettings); // then everything else await restoreSessionAndLogin(); ``` A cold launch caused by a call push has a ring window measured from the caller's side. Anything awaited before `init()` — a stored-credentials read, a remote config fetch, a login — spends that window, and the call is lost before the ring is wired up. ## Step 4: Register the background task and delete the token code ```js index.js theme={null} import { registerBackgroundCallTask } from '@cometchat/push-notifications-voip-react-native'; registerBackgroundCallTask(); ``` The Push SDK registers the token on login by itself. **Unregistering is not automatic** — this package installs no logout listener, so call `unregister()` before you log out (see Step 7). Remove: * `messaging().getToken()` + `registerPushToken(...)` after login * `VoipPushNotification.addEventListener('register', …)` and the APNs VoIP token plumbing * `unregisterPushToken(...)` before logout — replaced by `CometChatPushNotifications.unregister()`, which must run **before** `logout()` ## Step 5: Delete the app-side ringing Everything in this list is now done by the Push SDK. Remove it, or it will fight the SDK's ring (two ringtones, two screens, a busy reject sent on top of the SDK's). * `CometChat.addCallListener(...)` and its `onIncomingCallReceived` handler * The incoming-call modal, overlay or screen you rendered from it * Your own ringtone or sound player for incoming calls * The "already in a call → reject with busy" check * `RNCallKeep.setup`, `displayIncomingCall`, `answerCall`/`endCall` event wiring, `VoipPushNotification` handlers, and the `READ_PHONE_STATE` / `MANAGE_OWN_CALLS` / `ANSWER_PHONE_CALLS` permission chain * Any foreground check around call pushes Keep `NSMicrophoneUsageDescription`, `NSCameraUsageDescription` and the `voip` background mode in `Info.plist` — those are your app's own and nothing merges them in. You can drop `RECORD_AUDIO`, `CAMERA` and `POST_NOTIFICATIONS` from your Android manifest: the push package declares `POST_NOTIFICATIONS`, the VoIP package declares the other two, and the manifest merger adds them for you. (An app that installs only the push package gets no call permissions at all — that is the point of the split.) ## Step 6: Rewrite the call code | Legacy | Now | Notes | | - | - | - | | `CometChat.initiateCall(new CometChat.Call(uid, type, RECEIVER_TYPE_USER))` | `CometChatCalls.initiateCall(uid, { type, receiverType, sessionSettings })` | Set `sessionSettings.sessionType`, or an audio call opens the camera | | `CometChat.initiateCall(call, timeoutSeconds)` | No client timeout. The ring window is 45 s on both sides (or the push's `ringTimeout`) | Run your own 45 s timer on the caller if you want the screen to close on its own | | `CallListener.onIncomingCallReceived(call)` | Nothing to write; the Push SDK rings. For your own state use `CometChatVoipNotifications.onCallRinging` | Fires whether the call came by push on a killed process or on a live one | | `CallListener.onOutgoingCallAccepted(call)` | `session.addEventListener('onParticipantJoined', …)` on the session `initiateCall` prepared, via `CometChatCalls.getActiveSession()` | New in-between event: `onParticipantConnected` = the callee's device is ringing | | `CallListener.onOutgoingCallRejected(call)` | `CometChatVoipNotifications.onCallEnded` with reason `declined` | `rejected` and `busy` both map to `declined`; read `PNCallInfo.callAction` for the wire value | | `CallListener.onIncomingCallCancelled(call)` | `onCallEnded` with `cancelled`; the Push SDK has already stopped the ring | | | `CallListener.onCallEndedMessageReceived(call)` | `onSessionLeft` / `onConnectionClosed` on the joined session; `onCallEnded` with `timedOut` while ringing | | | `CometChat.acceptCall(sessionId)` then start the session | `onCallAccepted` fires; mount the call component | The Push SDK doesn't ask for the mic or camera. On Android, call `CometChatPNHelper.requestCallPermissions()` after sign-in; on iOS the system asks on first use | | `CometChat.rejectCall(sessionId, CALL_STATUS_REJECTED)` | Push SDK Decline button. Own incoming screen: `CometChatVoipNotifications.declineCall(sessionId)` | Sends `busy` automatically when in another call | | `CometChat.rejectCall(sessionId, CALL_STATUS_BUSY)` | Nothing; the Push SDK decides busy | | | `CometChat.rejectCall(sessionId, CALL_STATUS_CANCELLED)` | `CometChatCalls.endCall(sessionId, 'cancelled')` | | | `CometChatCalls.startSession(...)` / `joinSession(...)` | `CometChatCalls.connect(sessionId)` then `` | The session is already prepared, so the join is near-instant | | `session.leaveSession()` + `CometChat.endCall(sessionId)` | `session.leave()` | No status to send on a hang-up; the room tells the other side and the backend logs it | | `CometChat.getActiveCall()` / `clearActiveCall()` | `CometChatCalls.getActiveSession()` (null when no session is prepared or joined) | | | `CometChat.logout()` | `CometChatCalls.logout()` as well — the UI Kit's `CometChatUIKit.logout` does **not** do it for you — after `CometChatPushNotifications.unregister()` | Otherwise the Calls SDK stays signed in as the old user and a ring is not stopped | ### Caller screen, before and after > [tab] Before > > ```ts theme={null} > CometChat.addCallListener(LISTENER_ID, new CometChat.CallListener({ > onOutgoingCallAccepted: call => startSession(call.getSessionId()), > onOutgoingCallRejected: () => close('rejected'), > onIncomingCallCancelled: () => close('cancelled'), > })); > > const call = await CometChat.initiateCall( > new CometChat.Call(uid, CometChat.CALL_TYPE.AUDIO, CometChat.RECEIVER_TYPE.USER), > ); > setStatus('Calling…'); > ``` > [tab] After > > ```ts theme={null} > const { data: call, error } = await CometChatCalls.initiateCall(uid, { > type: 'audio', > receiverType: 'user', > sessionSettings: { sessionType: 'VOICE' }, // capitals: 'VOICE' / 'VIDEO' > }); > if (error) return showError(error); // { data, error }, not isSuccess > > const session = CometChatCalls.getActiveSession(); > const me = CometChatCalls.getLoggedInUser()?.uid; > setStatus('Calling…'); > > session?.addEventListener('onParticipantConnected', p => { > if (p.uid !== me) setStatus('Ringing…'); // new: the callee's device was reached > }); > session?.addEventListener('onParticipantJoined', p => { > if (p.uid !== me) joinCall(call.sessionId); > }); > > CometChatVoipNotifications.onCallEnded(e => close(e.reason)); // declined / timedOut > ``` ### Callee screen, before and after > [tab] Before > > ```ts theme={null} > CometChat.addCallListener(LISTENER_ID, new CometChat.CallListener({ > onIncomingCallReceived: async call => { > if (inACall) return CometChat.rejectCall(call.getSessionId(), CometChat.CALL_STATUS.BUSY); > playRingtone(); > RNCallKeep.displayIncomingCall(call.getSessionId(), call.getSender().getName()); > showIncomingModal(call); > }, > onIncomingCallCancelled: () => { stopRingtone(); hideIncomingModal(); }, > })); > > async function onAnswerPressed(call) { > stopRingtone(); > await CometChat.acceptCall(call.getSessionId()); > startSession(call.getSessionId()); > } > ``` > [tab] After > > ```ts theme={null} > // Nothing rings here any more: the Push SDK does, in every app state. > CometChatVoipNotifications.onCallAccepted(call => { > navigate('Call', { sessionId: call.sessionId }); > }); > ``` ## Step 7: Change the logout > [tab] Before > > ```ts theme={null} > await CometChat.logout(); > ``` > [tab] After > > ```ts theme={null} > await CometChatPushNotifications.unregister(); // needs the credential; must come first > CometChatVoipNotifications.clearIdentity(); > await CometChatUIKit.logout(); // Chat SDK only > await CometChatCalls.logout(); // the Kit does not do this for you > ``` `unregister()` after `logout()` cannot authenticate the delete, so the token stays registered and the device goes on receiving the departed user's call pushes. Logging out of the Chat SDK alone leaves the Calls SDK signed in, so a ring keeps playing for the old user. ## If you drew your own incoming-call screen You can keep it. Subscribe to `onCallRinging` instead of `CallListener.onIncomingCallReceived`, close it from `onRingEnded`, and answer and decline through `CometChatVoipNotifications.answerCall` / `declineCall`. Tell the SDK your screen is up with `notifyCallScreenOpen(sessionId)` so it does not also show its own. See [Your own incoming-call screen](/docs/calls/react-native/voip-calling#your-own-incoming-call-screen). This replaces the in-app screen only. A push that arrives while your app is killed still rings with the SDK's native screen on Android and CallKit on iOS — neither can be drawn from JavaScript that is not running. ## While some users are still on legacy ringing Your users don't all update at once, so during the rollout one CometChat app has devices on both flows. A device's flow comes from its push registration: a device on the Calls SDK 5.1 and Push Notifications SDK 2.0 receives only the call-initiated push, and a device still on legacy ringing keeps receiving the legacy call events. To let users on the two flows call each other, turn on **Connect legacy ringing** in the CometChat dashboard under **Voice & Video Calls → Settings**. CometChat then also sends calls made on this flow as legacy call events, so devices on either flow ring for calls from the other. * Turn it on before the first users update, and leave it on while any version of your app still in use rings the legacy way. * It can't be turned off from the dashboard. * The six legacy call events (ongoing, cancelled, rejected, unanswered, busy and ended) are under **Show legacy** in **Notifications → Settings → Call Preferences**. They only reach devices on legacy ringing. > [!NOTE] > > This is a server-side bridge, so it needs no code on either side. A device that has been updated does not need the legacy `CallListener` back — keep it deleted. ## What users will notice * Calls now ring with the app killed, and from the lock screen. * The caller sees "Ringing…" once the callee's device has actually been reached, and a reason when a call ends. * A second call rings over a live one instead of being silently rejected. * Missed calls appear as their own notifications. ## Checklist * [ ] Calls SDK 5.1, Push SDK 2.0 core **and** VoIP packages installed; CallKeep and VoIP-push libraries removed * [ ] `CometChatVoipNotifications.init()` is the first `await` on startup, and the chat app passes it **no** config * [ ] `registerBackgroundCallTask()` called at module scope in `index.js` * [ ] All `CometChat.addCallListener` call handling, app-side ringtones and busy checks deleted * [ ] Caller listens on the prepared session for `onParticipantConnected` / `onParticipantJoined` * [ ] `onCallAccepted` and `onCallEnded` repointed from `CometChatPushNotifications` to `CometChatVoipNotifications`, and subscribed before the first call can arrive * [ ] Hang-up uses `session.leave()`, cancel uses `endCall(sessionId, 'cancelled')` * [ ] Logout unregisters push first, then clears the identity, then logs out * [ ] `requestCallPermissions()` called after sign-in; `ensureRingReady()` checked; `NSMicrophoneUsageDescription` present * [ ] Staging or dedicated host passed to the Push SDK as well * [ ] **Connect legacy ringing** turned on in the dashboard before the first users update, if any of your app versions still ring the legacy way * [ ] All three packages installed: Calls SDK 5.1 and both Push Notifications packages at 2.0 # Migration Guide Source: https://www.cometchat.com/docs/calls/react-native/migration-guide-v5 Migrate to CometChat Calls SDK v5 on React Native with updated setup, APIs, call sessions, layouts, and feature changes. This guide covers migrating from Calls SDK v4 to v5 for React Native. ## Drop-in Compatibility Calls SDK v5 is a **drop-in replacement** for v4. All v4 APIs are preserved as deprecated methods that internally delegate to the new v5 implementations. You can update the package version and your existing code will compile and run without changes. ```bash theme={null} npm install @cometchat/calls-sdk-react-native@5 ``` > [!NOTE] > > This installs the latest stable v5. The ringing APIs — `initiateCall`, `endCall`, the prepared session and `session.addEventListener` — arrived in 5.1. 5.1 also requires `react-native-webrtc` 155; see [Calls SDK set up](/docs/calls/react-native/setup). > [!NOTE] > > If you're using CometChat UI Kits, simply updating the Calls SDK version is sufficient. The UI Kit will continue to work with v5 through the deprecated compatibility layer. ## Why Migrate to v5 APIs? While v4 APIs will continue to work, migrating to v5 APIs gives you: * **Granular event listeners** — subscribe to specific events like `onParticipantJoined` or `onSessionLeft` instead of one monolithic `OngoingCallListener` * **Dedicated `login()` method** — the Calls SDK now handles its own authentication instead of depending on the Chat SDK's auth token or REST APIs * **Simplified initialization** — pass plain objects to `init()` instead of using builder classes * **Strongly-typed enums** — `LayoutType`, `SessionType` instead of raw strings *** ## Initialization v5 accepts a plain object instead of requiring `CallAppSettingsBuilder`. > [tab] v4 > > ```javascript theme={null} > const callAppSettings = new CometChatCalls.CallAppSettingsBuilder() > .setAppId("APP_ID") > .setRegion("REGION") > .build(); > > CometChatCalls.init(callAppSettings).then( > () => { /* initialized */ }, > (error) => { /* handle error */ } > ); > ``` > [tab] v5 > > ```javascript theme={null} > const callAppSettings = { > appId: "APP_ID", > region: "REGION", > }; > > CometChatCalls.init(callAppSettings).then( > () => { /* initialized */ }, > (error) => { /* handle error */ } > ); > ``` > [!NOTE] > > `CallAppSettingsBuilder` still works in v5 — it's deprecated but functional. *** ## Authentication In v4, the Calls SDK had no dedicated authentication step. It relied on the Chat SDK's auth token (`CometChat.getUserAuthToken()`) or a REST API to obtain an auth token, which you then passed manually to `generateToken()`. v5 introduces dedicated authentication. Use `login(uid, authKey)` with the user's UID, or `loginWithAuthToken(authToken)` if you already hold an auth token (for example, one obtained from the Chat SDK). After login, the SDK caches the auth token internally. > [tab] v4 > > ```javascript theme={null} > // No dedicated Calls SDK login — relied on Chat SDK for auth token > const authToken = CometChat.getUserAuthToken(); > > // Had to pass authToken manually > CometChatCalls.generateToken(sessionId, authToken).then( > (token) => { /* use token to start session */ }, > (error) => { } > ); > ``` > [tab] v5 > > ```javascript theme={null} > // Login to the Calls SDK once (after your Chat SDK login). > // You already have an auth token here, so use loginWithAuthToken(). > // To log in by UID instead, use CometChatCalls.login(uid, authKey). > CometChatCalls.loginWithAuthToken(authToken).then( > (user) => { /* Calls SDK is now authenticated */ }, > (error) => { } > ); > > // generateToken no longer needs the authToken parameter > CometChatCalls.generateToken(sessionId).then( > (token) => { /* use token */ }, > (error) => { } > ); > ``` > [!NOTE] > > Call `CometChatCalls.login()` (or `CometChatCalls.loginWithAuthToken()`) once after your user authenticates. The SDK stores the auth token internally, so subsequent calls like `generateToken()` use it automatically. *** ## Session Settings `CallSettingsBuilder` is replaced by passing a plain `SessionSettings` object directly. > [tab] v4 > > ```javascript theme={null} > const callSettings = new CometChatCalls.CallSettingsBuilder() > .enableDefaultLayout(true) > .setIsAudioOnlyCall(true) > .showEndCallButton(true) > .showMuteAudioButton(true) > .showPauseVideoButton(true) > .showRecordingButton(true) > .startWithAudioMuted(false) > .startWithVideoMuted(false) > .setMode(CometChatCalls.CALL_MODE.DEFAULT) > .setCallEventListener(new CometChatCalls.OngoingCallListener({ > onCallEnded: () => { }, > onCallEndButtonPressed: () => { }, > onUserJoined: (user) => { }, > onUserLeft: (user) => { }, > onUserListUpdated: (userList) => { }, > onError: (error) => { }, > })) > .build(); > ``` > [tab] v5 > > ```javascript theme={null} > const sessionSettings = { > sessionType: "VIDEO", // or "VOICE" > layout: "TILE", // or "SIDEBAR" or "SPOTLIGHT" > startAudioMuted: false, > startVideoPaused: false, > hideLeaveSessionButton: false, > hideToggleAudioButton: false, > hideToggleVideoButton: false, > hideRecordingButton: false, > hideScreenSharingButton: false, > hideChangeLayoutButton: false, > hideControlPanel: false, > autoStartRecording: false, > }; > ``` ### Settings Property Mapping | v4 Builder Method | v5 Property | Notes | | - | - | - | | `setIsAudioOnlyCall(true)` | `sessionType: "VOICE"` | Use `"VIDEO"` for video calls | | `enableDefaultLayout(bool)` | `hideControlPanel: !bool` | Inverted logic | | `showEndCallButton(bool)` | `hideLeaveSessionButton: !bool` | Inverted logic | | `showMuteAudioButton(bool)` | `hideToggleAudioButton: !bool` | Inverted logic | | `showPauseVideoButton(bool)` | `hideToggleVideoButton: !bool` | Inverted logic | | `showRecordingButton(bool)` | `hideRecordingButton: !bool` | Inverted logic | | `showSwitchCameraButton(bool)` | `hideSwitchCameraButton: !bool` | Inverted logic | | `startWithAudioMuted(bool)` | `startAudioMuted: bool` | Same logic | | `startWithVideoMuted(bool)` | `startVideoPaused: bool` | Same logic | | `setMode(CALL_MODE.DEFAULT)` | `layout: "TILE"` | Enum instead of constant | | `startRecordingOnCallStart(bool)` | `autoStartRecording: bool` | Same logic | | `setCallEventListener(listener)` | Use `addEventListener()` | See [Events](#event-listeners) section | *** ## Joining a Session In React Native, `startSession()` is replaced by rendering ``. There is no `joinSession()` method — generate a call token, then render the component to join. > [tab] v4 > > ```javascript theme={null} > CometChatCalls.generateToken(sessionId, authToken).then((token) => { > CometChatCalls.startSession(token, callSettings); > }); > ``` > [tab] v5 > > ```jsx theme={null} > // 1. Generate the call token > const { token } = await CometChatCalls.generateToken(sessionId); > > // 2. Render the call UI to join the session > callToken={token} > sessionSettings={sessionSettings} > /> > ``` *** ## Session Control (Actions) Static methods remain on `CometChatCalls` but some have been renamed. > [!NOTE] > > **Boolean toggles are now paired methods.** In v4, `muteAudio()` took a boolean: `muteAudio(true)` muted the mic and `muteAudio(false)` unmuted it. In v5 these are two separate, argument-free methods — replace `muteAudio(true)` with `muteAudio()` and `muteAudio(false)` with `unmuteAudio()`. The same split applies to `pauseVideo(true)` / `pauseVideo(false)`, which become `pauseVideo()` and `resumeVideo()`. ```javascript theme={null} // v4 CometChatCalls.muteAudio(true); // mute CometChatCalls.muteAudio(false); // unmute // v5 CometChatCalls.muteAudio(); // mute CometChatCalls.unmuteAudio(); // unmute ``` | v4 Method | v5 Method | | - | - | | `CometChatCalls.endSession()` | `session.leave()` | | `CometChatCalls.switchCamera()` | `CometChatCalls.switchCamera()` | | `CometChatCalls.muteAudio(true)` | `CometChatCalls.muteAudio()` | | `CometChatCalls.muteAudio(false)` | `CometChatCalls.unmuteAudio()` | | `CometChatCalls.pauseVideo(true)` | `CometChatCalls.pauseVideo()` | | `CometChatCalls.pauseVideo(false)` | `CometChatCalls.resumeVideo()` | | `CometChatCalls.setMode(mode)` | `CometChatCalls.setLayout(layout)` | | `CometChatCalls.enterPIPMode()` | `CometChatCalls.enablePictureInPictureLayout()` | | `CometChatCalls.exitPIPMode()` | `CometChatCalls.disablePictureInPictureLayout()` | | `CometChatCalls.startRecording()` | `CometChatCalls.startRecording()` | | `CometChatCalls.stopRecording()` | `CometChatCalls.stopRecording()` | | `CometChatCalls.switchToVideoCall()` | *Deprecated — retained as a no-op, no longer supported* | *** ## Event Listeners The single `OngoingCallListener` is replaced by `addEventListener()` with specific event types. ### v4: Single Listener Object ```javascript theme={null} const callSettings = new CometChatCalls.CallSettingsBuilder() .setCallEventListener(new CometChatCalls.OngoingCallListener({ onCallEnded: () => { }, onCallEndButtonPressed: () => { }, onUserJoined: (user) => { }, onUserLeft: (user) => { }, onUserListUpdated: (userList) => { }, onAudioModesUpdated: (audioModes) => { }, onUserMuted: (muteInfo) => { }, onRecordingStarted: (recordingInfo) => { }, onRecordingStopped: (recordingInfo) => { }, onError: (error) => { }, })) .build(); ``` ### v5: Granular Event Subscriptions ```javascript theme={null} // Session events CometChatCalls.addEventListener("onSessionJoined", () => { }); CometChatCalls.addEventListener("onSessionLeft", () => { }); CometChatCalls.addEventListener("onSessionTimedOut", () => { }); CometChatCalls.addEventListener("onConnectionLost", () => { }); CometChatCalls.addEventListener("onConnectionRestored", () => { }); // Participant events CometChatCalls.addEventListener("onParticipantJoined", (participant) => { }); CometChatCalls.addEventListener("onParticipantLeft", (participant) => { }); CometChatCalls.addEventListener("onParticipantListChanged", (participants) => { }); CometChatCalls.addEventListener("onParticipantAudioMuted", (participant) => { }); CometChatCalls.addEventListener("onParticipantAudioUnmuted", (participant) => { }); // Media events CometChatCalls.addEventListener("onAudioMuted", () => { }); CometChatCalls.addEventListener("onAudioUnMuted", () => { }); CometChatCalls.addEventListener("onRecordingStarted", () => { }); CometChatCalls.addEventListener("onRecordingStopped", () => { }); // Button click events CometChatCalls.addEventListener("onLeaveSessionButtonClicked", () => { }); CometChatCalls.addEventListener("onToggleAudioButtonClicked", () => { }); CometChatCalls.addEventListener("onToggleVideoButtonClicked", () => { }); // Layout events CometChatCalls.addEventListener("onCallLayoutChanged", (layoutType) => { }); CometChatCalls.addEventListener("onPictureInPictureLayoutEnabled", () => { }); CometChatCalls.addEventListener("onPictureInPictureLayoutDisabled", () => { }); ``` > [!NOTE] > > `addEventListener()` returns an unsubscribe function. Call it to remove the listener. ### New Events Require `addEventListener()` The events introduced in v5 are only delivered through `addEventListener()`. Neither of the v4 registration paths — `setCallEventListener()` on `CallSettingsBuilder` and `CometChatCalls.addCallEventListener(name, listener)` — will ever fire them, because `OngoingCallListener` only carries the legacy v4 event set. Events such as `onSessionJoined`, `onConnectionLost`, `onLeaveSessionButtonClicked`, and `onCallLayoutChanged` are unreachable from a v4 listener no matter how it is registered. You don't have to migrate everything at once. `addEventListener()` works alongside an existing v4 listener without breaking it — keep your current `OngoingCallListener` for the legacy events and add `addEventListener()` subscriptions for the new ones. ```javascript theme={null} // Existing v4 listener keeps working CometChatCalls.addCallEventListener("MY_LISTENER", new CometChatCalls.OngoingCallListener({ onCallEnded: () => { }, onUserJoined: (user) => { }, })); // Add v5-only events alongside it CometChatCalls.addEventListener("onConnectionLost", () => { }); CometChatCalls.addEventListener("onCallLayoutChanged", (layoutType) => { }); ``` > [!WARNING] > > **TypeScript: the deprecated listener methods are not on the exported type.** The compatibility layer > above runs correctly, but `addCallEventListener` and `removeCallEventListener` are not declared on the > exported `CometChatCalls` class, so a TypeScript project cannot use this incremental path — it fails to > compile with `TS2551: Property 'addCallEventListener' does not exist on type 'typeof CometChatCalls'`. > Since `npx react-native init` creates a TypeScript app by default, most projects should migrate their > listeners to `addEventListener()` in one step rather than running the two side by side. ### Event Mapping | v4 Event | v5 Event | | - | - | | `onCallEnded` | `onSessionLeft` | | `onCallEndButtonPressed` | `onLeaveSessionButtonClicked` | | `onUserJoined(user)` | `onParticipantJoined(participant)` | | `onUserLeft(user)` | `onParticipantLeft(participant)` | | `onUserListUpdated(userList)` | `onParticipantListChanged(participants)` | | `onAudioModesUpdated(list)` | `onAudioModeChanged(audioMode)` | | `onUserMuted(info)` | `onParticipantAudioMuted(participant)` | | `onRecordingStarted` / `onRecordingStopped` | `onRecordingStarted` / `onRecordingStopped` | | `onError(error)` | Errors returned via Promise rejection | *** ## Deprecated Classes Summary | Deprecated | Replacement | | - | - | | `CometChatCalls.CallAppSettingsBuilder` | Pass plain object to `init()` | | `CometChatCalls.CallSettingsBuilder` | Pass plain `SessionSettings` object to `` | | `CometChatCalls.OngoingCallListener` | `CometChatCalls.addEventListener()` | | `CometChatCalls.startSession()` | Render `` (no `joinSession` in React Native) | | `CometChatCalls.endSession()` | `session.leave()` | | `RTCRecordingInfo` | `onRecordingStarted` / `onRecordingStopped` events | | `CallSwitchRequestInfo` | *Removed (no replacement)* | *** ## 5.0 to 5.1 5.1 moves ringing onto the Calls SDK and the Push Notifications SDK, and supersedes Chat SDK calling: | Superseded in 5.1 | Replacement | | - | - | | Chat SDK calling: `CometChat.initiateCall`, `acceptCall`, `rejectCall`, `endCall`, `getActiveCall`, `clearActiveCall`, `addCallListener`, `CallListener` | `CometChatCalls.initiateCall`, `endCall(sessionId, status)`, the Push Notifications SDK's VoIP package | New in 5.1: `CometChatCalls.initiateCall`, `endCall(sessionId, status)`, `connect`, `getActiveSession`, and `onParticipantConnected` on a prepared session. The step-by-step move from Chat SDK signalling is on [Migrating from Legacy Ringing](/docs/calls/react-native/migrating-from-legacy-ringing). # Calls SDK Source: https://www.cometchat.com/docs/calls/react-native/overview Use CometChat Calls SDK v5 for React Native to add voice and video calling, call sessions, participants, layouts, and in-call features. The CometChat Calls SDK enables real-time voice and video calling capabilities in your React Native application. Built on top of WebRTC, it provides a complete calling solution with built-in UI components and extensive customization options. > [!NOTE] > > **Quick Reference for AI Agents & Developers** > > ```bash theme={null} theme={null} > # The Calls SDK plus its required peer dependencies > npm install @cometchat/calls-sdk-react-native@5 > 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.16.0 react-native-url-polyfill@2.0.0 \ > react-native-webrtc@155.0.1 > ``` > > ```tsx theme={null} theme={null} > import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; > > // 1. init + login once, at app start > await CometChatCalls.init({ appId: APP_ID, region: REGION }); > await CometChatCalls.login(UID, AUTH_KEY); > > // 2. a token for this session > const { token } = await CometChatCalls.generateToken(sessionId); > > // 3. joining IS rendering — React Native has no joinSession() > > callToken={token} > sessionSettings={{ sessionType: 'VIDEO', layout: 'TILE' }} > /> > > ``` > > * **Setup** (permissions, pods, Gradle) → [Setup](/docs/calls/react-native/setup) > * **Authentication** → [Authentication](/docs/calls/react-native/authentication) > * **Join a session** → [Join Session](/docs/calls/react-native/join-session) > * **Session settings** → [Session Settings](/docs/calls/react-native/session-settings) > * **Events** → [Events](/docs/calls/react-native/events) > * **1:1 ringing** → [Ringing](/docs/calls/react-native/ringing) > * **Ring a closed app** → [VoIP Calling](/docs/calls/react-native/voip-calling) > * **Migrating from v4** → [Migration Guide](/docs/calls/react-native/migration-guide-v5) ## Prerequisites Before integrating the Calls SDK, ensure you have: 1. **CometChat Account**: [Sign up](https://app.cometchat.com/signup) and create an app to get your App ID, Region, and API Key 2. **CometChat Users**: Users must exist in CometChat to use calling features. For testing, create users via the [Dashboard](https://app.cometchat.com) or [REST API](/docs/rest-api/users/create). Authentication is handled by the Calls SDK - see [Authentication](/docs/calls/react-native/authentication) 3. **React Native Requirements**: * React Native 0.71 or later (works with both the old architecture and the [New Architecture](/docs/calls/react-native/setup#react-native-new-architecture), including bridgeless mode) * Node.js: what your React Native version requires (22.13+ or 24.3+ for React Native 0.88) * iOS: deployment target 15.1 or later (the minimum for React Native 0.76 and later); Xcode 16.1 or later (required since React Native 0.81) * Android: Minimum SDK API Level 24 (Android 7.0) 4. **Permissions**: Camera and microphone permissions for video/audio calls ## Call Flow ```mermaid theme={null} sequenceDiagram participant App participant CometChatCalls participant Component App->>CometChatCalls: init() App->>CometChatCalls: login() App->>CometChatCalls: generateToken() App->>Component: Render with callToken Component-->>App: Event callbacks App->>CometChatCalls: Actions (mute, pause, etc.) App->>CometChatCalls: leaveSession() ``` ## Features > [card] [Ringing](/docs/calls/react-native/ringing) > > Incoming and outgoing call notifications with accept/reject functionality > [card] [Call Layouts](/docs/calls/react-native/call-layouts) > > Tile, Sidebar, and Spotlight view modes for different call scenarios > [card] [Audio Modes](/docs/calls/react-native/audio-modes) > > Switch between speaker, earpiece, Bluetooth, and headphones > [card] [Recording](/docs/calls/react-native/recording) > > Record call sessions for later playback > [card] [Transcription](/docs/calls/react-native/transcription) > > Transcribe calls, show live closed captions, and retrieve transcripts > [card] [Call Logs](/docs/calls/react-native/call-logs) > > Retrieve call history and details > [card] [Participant Management](/docs/calls/react-native/participant-management) > > Mute, pin, and manage call participants > [card] [Screen Sharing](/docs/calls/react-native/screen-sharing) > > View screen shares from other participants > [card] [Picture-in-Picture](/docs/calls/react-native/picture-in-picture) > > Continue calls while using other apps > [card] [Raise Hand](/docs/calls/react-native/raise-hand) > > Signal to get attention during calls > [card] [Idle Timeout](/docs/calls/react-native/idle-timeout) > > Automatic session termination when alone in a call ## Architecture The SDK is organized around these core components: | Component | Description | | - | - | | `CometChatCalls` | Main entry point for SDK initialization, authentication, and session management | | Init settings object | Plain object (`{ appId, region }`) passed to `init()` to configure the SDK | | `sessionSettings` object | Plain object passed to `CometChatCalls.Component` to configure individual call sessions | | `CometChatCalls.Component` | React component that renders the call UI | | `CometChatCalls.addEventListener` | Subscribe to call events; returns an unsubscribe function | ## Single Active Session `CometChatCalls` is a singleton, and it tracks one active call session at a time. Every session method acts on that current session, which is why methods like `leaveSession()` take no session ID: ```tsx theme={null} // Acts on whatever session is currently active - no session ID needed CometChatCalls.leaveSession(); ``` | Behavior | Detail | | - | - | | One session at a time | The SDK does not support being connected to two sessions simultaneously. Leave the current session before joining another. | | One `Component` at a time | Render a single `CometChatCalls.Component` for the active call. Mounting two at once is not supported. | | Session methods take no session ID | `leaveSession()` and the other [actions](/docs/calls/react-native/actions) apply to the active session only. | | Actions apply to the active session | `muteAudio()`, `pauseVideo()`, `switchCamera()`, and similar methods target the session currently in progress. | | Events are not session-scoped | Listeners registered with `addEventListener` fire for the active session. | To move a user from one call to another, leave the current session, wait for the `onSessionLeft` event, then generate a token for the new session and render the component with the new token: ```tsx theme={null} CometChatCalls.addEventListener('onSessionLeft', async () => { const { token } = await CometChatCalls.generateToken(nextSessionId); setCallToken(token); // Re-renders CometChatCalls.Component with the new session }, { signal }); CometChatCalls.leaveSession(); ``` ## Related Documentation * [Setup](/docs/calls/react-native/setup) - Install and configure the SDK * [Authentication](/docs/calls/react-native/authentication) - Initialize and authenticate users * [Join Session](/docs/calls/react-native/join-session) - Start and join calls ## Sample App > [card] [Sample App](https://github.com/cometchat/calls-sdk-react-native/tree/v5/sample-apps/cometchat-calls-sample-app-react-native) > > Explore the React Native Calls SDK sample app on GitHub > [card] [Changelog](https://github.com/cometchat/calls-sdk-react-native/releases) > > View the latest releases and changes # Participant Management Source: https://www.cometchat.com/docs/calls/react-native/participant-management Manage CometChat Calls SDK v5 participants on React Native with mute, pause video, pinning, permissions, and participant events. Manage call participants by muting, pinning, and monitoring their status during a call. ## Get Participant List Listen for participant list changes: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; CometChatCalls.addEventListener('onParticipantListChanged', (participants) => { console.log('Participants:', participants); participants.forEach((participant) => { console.log(`- ${participant.name} (${participant.uid})`); }); }); ``` ## Participant Object Each participant contains: | Property | Type | Description | | - | - | - | | `pid` | string | Participant ID (unique per session) | | `uid` | string | User ID | | `name` | string | Display name | | `avatar` | string | Avatar URL (optional) | ## Pin Participant Pin a participant to the main view in Sidebar or Spotlight layouts: ```tsx theme={null} // Pin a participant's video CometChatCalls.pinParticipant(participantId, 'human'); // Pin a participant's screen share CometChatCalls.pinParticipant(participantId, 'screen-share'); ``` | Parameter | Type | Description | | - | - | - | | `participantId` | string | The participant's `pid` | | `type` | string | `'human'` for video, `'screen-share'` for screen share | ## Unpin Participant Remove the pinned participant: ```tsx theme={null} CometChatCalls.unpinParticipant(); ``` ## Mute Participant Mute another participant's audio (requires moderator permissions): ```tsx theme={null} CometChatCalls.muteParticipant(participantId); ``` ## Pause Participant Video Pause another participant's video (requires moderator permissions): ```tsx theme={null} CometChatCalls.pauseParticipantVideo(participantId); ``` ## Participant Events ### Join and Leave ```tsx theme={null} CometChatCalls.addEventListener('onParticipantJoined', (participant) => { console.log(`${participant.name} joined the call`); }); CometChatCalls.addEventListener('onParticipantLeft', (participant) => { console.log(`${participant.name} left the call`); }); ``` ### Audio State ```tsx theme={null} CometChatCalls.addEventListener('onParticipantAudioMuted', (participant) => { console.log(`${participant.name} muted their audio`); }); CometChatCalls.addEventListener('onParticipantAudioUnmuted', (participant) => { console.log(`${participant.name} unmuted their audio`); }); ``` ### Video State ```tsx theme={null} CometChatCalls.addEventListener('onParticipantVideoPaused', (participant) => { console.log(`${participant.name} paused their video`); }); CometChatCalls.addEventListener('onParticipantVideoResumed', (participant) => { console.log(`${participant.name} resumed their video`); }); ``` ### Hand Raised ```tsx theme={null} CometChatCalls.addEventListener('onParticipantHandRaised', (participant) => { console.log(`${participant.name} raised their hand`); }); CometChatCalls.addEventListener('onParticipantHandLowered', (participant) => { console.log(`${participant.name} lowered their hand`); }); ``` ### Screen Sharing ```tsx theme={null} CometChatCalls.addEventListener('onParticipantStartedScreenShare', (participant) => { console.log(`${participant.name} started screen sharing`); }); CometChatCalls.addEventListener('onParticipantStoppedScreenShare', (participant) => { console.log(`${participant.name} stopped screen sharing`); }); ``` ### Dominant Speaker ```tsx theme={null} CometChatCalls.addEventListener('onDominantSpeakerChanged', (participant) => { console.log(`Dominant speaker: ${participant.name}`); }); ``` ## Complete Example ```tsx theme={null} import React, { useState, useEffect } from 'react'; import { View, FlatList, Text, TouchableOpacity, StyleSheet } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; interface Participant { pid: string; uid: string; name: string; avatar?: string; } function ParticipantList() { const [participants, setParticipants] = useState([]); const [pinnedId, setPinnedId] = useState(null); useEffect(() => { const controller = new AbortController(); const { signal } = controller; CometChatCalls.addEventListener( 'onParticipantListChanged', (list: Participant[]) => { setParticipants(list); }, { signal } ); CometChatCalls.addEventListener( 'onParticipantJoined', (participant: Participant) => { console.log(`${participant.name} joined`); }, { signal } ); CometChatCalls.addEventListener( 'onParticipantLeft', (participant: Participant) => { console.log(`${participant.name} left`); // Unpin if the pinned participant left if (pinnedId === participant.pid) { setPinnedId(null); } }, { signal } ); return () => controller.abort(); }, [pinnedId]); const handlePin = (participant: Participant) => { if (pinnedId === participant.pid) { CometChatCalls.unpinParticipant(); setPinnedId(null); } else { CometChatCalls.pinParticipant(participant.pid, 'human'); setPinnedId(participant.pid); } }; const handleMute = (participant: Participant) => { CometChatCalls.muteParticipant(participant.pid); }; const renderParticipant = ({ item }: { item: Participant }) => ( {item.name.charAt(0).toUpperCase()} {item.name} handlePin(item)} > {pinnedId === item.pid ? 'Unpin' : 'Pin'} handleMute(item)} > Mute ); return ( Participants ({participants.length}) item.pid} renderItem={renderParticipant} ListEmptyComponent={ No other participants } /> ); } const styles = StyleSheet.create({ container: { flex: 1, backgroundColor: '#1a1a1a', }, header: { color: '#fff', fontSize: 18, fontWeight: '600', padding: 16, borderBottomWidth: 1, borderBottomColor: '#333', }, participantItem: { flexDirection: 'row', alignItems: 'center', padding: 12, borderBottomWidth: 1, borderBottomColor: '#333', }, avatar: { width: 40, height: 40, borderRadius: 20, backgroundColor: '#6851D6', justifyContent: 'center', alignItems: 'center', }, avatarText: { color: '#fff', fontSize: 16, fontWeight: '600', }, name: { flex: 1, color: '#fff', fontSize: 16, marginLeft: 12, }, actions: { flexDirection: 'row', gap: 8, }, actionButton: { backgroundColor: '#333', paddingHorizontal: 12, paddingVertical: 6, borderRadius: 4, }, activeButton: { backgroundColor: '#6851D6', }, actionText: { color: '#fff', fontSize: 12, }, emptyText: { color: '#666', textAlign: 'center', padding: 20, }, }); export default ParticipantList; ``` ## Related Documentation * [Events](/docs/calls/react-native/events) - All participant events * [Call Layouts](/docs/calls/react-native/call-layouts) - Layout options for participants * [Custom Participant List](/docs/calls/react-native/custom-participant-list) - Build custom UI # Picture-in-Picture Source: https://www.cometchat.com/docs/calls/react-native/picture-in-picture Configure picture-in-picture for CometChat Calls SDK v5 on React Native to keep video calls visible while users multitask. Picture-in-Picture (PiP) mode allows users to continue their call in a floating window while using other apps. This feature requires platform-specific configuration. ## Enable Picture-in-Picture Enable PiP mode programmatically: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; CometChatCalls.enablePictureInPictureLayout(); ``` ## Disable Picture-in-Picture Exit PiP mode and return to full-screen: ```tsx theme={null} CometChatCalls.disablePictureInPictureLayout(); ``` ## Listen for PiP Events ```tsx theme={null} CometChatCalls.addEventListener('onPictureInPictureLayoutEnabled', () => { console.log('PiP mode enabled'); }); CometChatCalls.addEventListener('onPictureInPictureLayoutDisabled', () => { console.log('PiP mode disabled'); }); ``` ## iOS Configuration ### Enable Background Modes 1. Open your project in Xcode 2. Select your target and go to **Signing & Capabilities** 3. Add **Background Modes** capability 4. Enable **Audio, AirPlay, and Picture in Picture** ### Info.plist No additional Info.plist entries are required for PiP on iOS. ### Automatic PiP iOS automatically enters PiP mode when: * The user presses the home button during a video call * The user swipes up to go to the app switcher ## Android Configuration ### Enable PiP Support Add PiP support to your main activity in `AndroidManifest.xml`: ```xml theme={null} ``` ### Minimum SDK PiP requires Android 8.0 (API level 26) or higher. Add to your `build.gradle`: ```groovy theme={null} android { defaultConfig { minSdkVersion 26 } } ``` ### Handle PiP Mode Changes In your React Native activity, handle PiP mode changes: ```java theme={null} // MainActivity.java @Override public void onPictureInPictureModeChanged(boolean isInPictureInPictureMode) { super.onPictureInPictureModeChanged(isInPictureInPictureMode); // Notify React Native about PiP state change } ``` ## Complete Example ```tsx theme={null} import React, { useState, useEffect } from 'react'; import { View, TouchableOpacity, Text, StyleSheet, AppState, Platform } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; function PictureInPictureControls() { const [isPiPEnabled, setIsPiPEnabled] = useState(false); const [appState, setAppState] = useState(AppState.currentState); useEffect(() => { const controller = new AbortController(); const { signal } = controller; CometChatCalls.addEventListener( 'onPictureInPictureLayoutEnabled', () => { setIsPiPEnabled(true); }, { signal } ); CometChatCalls.addEventListener( 'onPictureInPictureLayoutDisabled', () => { setIsPiPEnabled(false); }, { signal } ); // Listen for app state changes const subscription = AppState.addEventListener('change', (nextAppState) => { if (appState.match(/active/) && nextAppState === 'background') { // App going to background - enable PiP CometChatCalls.enablePictureInPictureLayout(); } setAppState(nextAppState); }); return () => { controller.abort(); subscription.remove(); }; }, [appState]); const togglePiP = () => { if (isPiPEnabled) { CometChatCalls.disablePictureInPictureLayout(); } else { CometChatCalls.enablePictureInPictureLayout(); } }; return ( {isPiPEnabled ? 'Exit PiP' : 'Enter PiP'} ); } const styles = StyleSheet.create({ button: { backgroundColor: '#333', paddingHorizontal: 16, paddingVertical: 12, borderRadius: 8, }, activeButton: { backgroundColor: '#6851D6', }, buttonText: { color: '#fff', fontSize: 14, fontWeight: '600', }, }); export default PictureInPictureControls; ``` ## Auto-Enable PiP on Background Automatically enable PiP when the app goes to background: ```tsx theme={null} import { useEffect, useRef } from 'react'; import { AppState, AppStateStatus } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; function useAutoPiP(enabled: boolean = true) { const appState = useRef(AppState.currentState); useEffect(() => { if (!enabled) return; const subscription = AppState.addEventListener( 'change', (nextAppState: AppStateStatus) => { if ( appState.current.match(/active/) && nextAppState === 'background' ) { CometChatCalls.enablePictureInPictureLayout(); } else if ( appState.current === 'background' && nextAppState === 'active' ) { CometChatCalls.disablePictureInPictureLayout(); } appState.current = nextAppState; } ); return () => { subscription.remove(); }; }, [enabled]); } export default useAutoPiP; ``` ## Platform Considerations ### iOS * PiP is available on iOS 14.0 and later * Works automatically when the app enters background * User can resize and move the PiP window ### Android * PiP requires Android 8.0 (API level 26) or higher * Must be explicitly enabled in the manifest * PiP window has fixed aspect ratio ## Related Documentation * [Background Handling](/docs/calls/react-native/background-handling) - Keep calls active in background * [Actions](/docs/calls/react-native/actions) - Control the call programmatically * [Events](/docs/calls/react-native/events) - PiP events # Raise Hand Source: https://www.cometchat.com/docs/calls/react-native/raise-hand Add raise hand behavior in CometChat Calls SDK v5 on React Native so participants can request attention during group calls. The raise hand feature allows participants to signal that they want attention during a call, useful for Q\&A sessions or large meetings. ## Raise Hand Signal to other participants that you want attention: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; CometChatCalls.raiseHand(); ``` ## Lower Hand Lower your raised hand: ```tsx theme={null} CometChatCalls.lowerHand(); ``` ## Listen for Hand Raised Events ### Local Events Listen for when the raise hand button is clicked: ```tsx theme={null} CometChatCalls.addEventListener('onRaiseHandButtonClicked', () => { console.log('Raise hand button clicked'); }); ``` ### Participant Events Listen for when other participants raise or lower their hands: ```tsx theme={null} CometChatCalls.addEventListener('onParticipantHandRaised', (participant) => { console.log(`${participant.name} raised their hand`); }); CometChatCalls.addEventListener('onParticipantHandLowered', (participant) => { console.log(`${participant.name} lowered their hand`); }); ``` ## Complete Example ```tsx theme={null} import React, { useState, useEffect } from 'react'; import { View, TouchableOpacity, Text, StyleSheet, FlatList } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; interface Participant { pid: string; name: string; } function RaiseHandFeature() { const [isHandRaised, setIsHandRaised] = useState(false); const [raisedHands, setRaisedHands] = useState([]); useEffect(() => { const controller = new AbortController(); const { signal } = controller; CometChatCalls.addEventListener( 'onParticipantHandRaised', (participant: Participant) => { setRaisedHands((prev) => { if (prev.find((p) => p.pid === participant.pid)) { return prev; } return [...prev, participant]; }); }, { signal } ); CometChatCalls.addEventListener( 'onParticipantHandLowered', (participant: Participant) => { setRaisedHands((prev) => prev.filter((p) => p.pid !== participant.pid) ); }, { signal } ); CometChatCalls.addEventListener( 'onParticipantLeft', (participant: Participant) => { setRaisedHands((prev) => prev.filter((p) => p.pid !== participant.pid) ); }, { signal } ); return () => controller.abort(); }, []); const toggleHand = () => { if (isHandRaised) { CometChatCalls.lowerHand(); setIsHandRaised(false); } else { CometChatCalls.raiseHand(); setIsHandRaised(true); } }; const renderRaisedHand = ({ item }: { item: Participant }) => ( ✋ {item.name} ); return ( {isHandRaised ? '✋' : '🤚'} {isHandRaised ? 'Lower Hand' : 'Raise Hand'} {raisedHands.length > 0 && ( Raised Hands ({raisedHands.length}) item.pid} renderItem={renderRaisedHand} horizontal showsHorizontalScrollIndicator={false} /> )} ); } const styles = StyleSheet.create({ container: { padding: 16, }, button: { flexDirection: 'row', alignItems: 'center', justifyContent: 'center', backgroundColor: '#333', paddingHorizontal: 20, paddingVertical: 12, borderRadius: 8, gap: 8, }, activeButton: { backgroundColor: '#f59e0b', }, buttonIcon: { fontSize: 20, }, buttonText: { color: '#fff', fontSize: 14, fontWeight: '600', }, raisedHandsList: { marginTop: 16, }, listTitle: { color: '#fff', fontSize: 14, fontWeight: '600', marginBottom: 8, }, raisedHandItem: { flexDirection: 'row', alignItems: 'center', backgroundColor: '#333', paddingHorizontal: 12, paddingVertical: 8, borderRadius: 20, marginRight: 8, gap: 6, }, handIcon: { fontSize: 16, }, participantName: { color: '#fff', fontSize: 14, }, }); export default RaiseHandFeature; ``` ## Related Documentation * [Events](/docs/calls/react-native/events) - All raise hand events * [Participant Management](/docs/calls/react-native/participant-management) - Manage participants * [Actions](/docs/calls/react-native/actions) - Available call actions # Recording Source: https://www.cometchat.com/docs/calls/react-native/recording Use CometChat Calls SDK v5 recording on React Native to start, stop, access, and manage recordings for supported call sessions. The CometChat Calls SDK supports recording call sessions. Recordings can be started manually or automatically when the call begins. ## Enable Recording Button Show the recording button in the call UI: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; const sessionSettings = { hideRecordingButton: false, }; ``` ## Auto-Start Recording Start recording automatically when the call begins: ```tsx theme={null} const sessionSettings = { hideRecordingButton: false, autoStartRecording: true, }; ``` ## Start Recording Programmatically Start recording during an active call: ```tsx theme={null} CometChatCalls.startRecording(); ``` ## Stop Recording Stop an active recording: ```tsx theme={null} CometChatCalls.stopRecording(); ``` > [!NOTE] > > **A recording runs until it is stopped.** Whether it was started manually or automatically through `autoStartRecording`, it keeps running until someone stops it. If nobody does, it stops on its own when either: > > * Everyone leaves the session — the recording ends about a minute later. > * Everyone in the session stays muted for 10 minutes. ## Recording Events Listen for recording state changes: ### Using addEventListener ```tsx theme={null} const controller = new AbortController(); CometChatCalls.addEventListener( 'onRecordingStarted', () => { console.log('Recording started'); }, { signal: controller.signal } ); CometChatCalls.addEventListener( 'onRecordingStopped', () => { console.log('Recording stopped'); }, { signal: controller.signal } ); // Cleanup — removes all listeners at once controller.abort(); ``` ### Participant Recording Events Listen when other participants start or stop recording: ```tsx theme={null} CometChatCalls.addEventListener('onParticipantStartedRecording', (participant) => { console.log(`${participant.name} started recording`); }); CometChatCalls.addEventListener('onParticipantStoppedRecording', (participant) => { console.log(`${participant.name} stopped recording`); }); ``` ## Recording Button Click Event Listen for when the recording button is clicked: ```tsx theme={null} CometChatCalls.addEventListener('onRecordingToggleButtonClicked', () => { console.log('Recording button clicked'); }); ``` ## Access Recordings Recordings are available through the call logs after the call ends. Use the Chat SDK to retrieve recordings: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; async function getCallRecordings(sessionId: string) { const callLogRequest = new CometChatCalls.CallLogRequestBuilder() .setAuthToken(CometChatCalls.getUserAuthToken() ?? '') .setLimit(30) .build(); try { const callLogs = await callLogRequest.fetchNext(); const callLog = callLogs.find((log) => log.getSessionID() === sessionId); if (callLog?.getHasRecording()) { console.log('Recordings:', callLog.getRecordings()); return callLog.getRecordings(); } return []; } catch (error) { console.error('Error fetching recordings:', error); throw error; } } ``` ## Recording Object Each recording contains: | Property | Type | Description | | - | - | - | | `rid` | string | Recording ID | | `recordingUrl` | string | URL to download the recording | | `startTime` | number | Recording start timestamp | | `endTime` | number | Recording end timestamp | | `duration` | number | Recording duration in seconds | ## Complete Example ```tsx theme={null} import React, { useState, useEffect } from 'react'; import { View, TouchableOpacity, Text, StyleSheet } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; function RecordingControls() { const [isRecording, setIsRecording] = useState(false); useEffect(() => { const controller = new AbortController(); const { signal } = controller; CometChatCalls.addEventListener( 'onRecordingStarted', () => { setIsRecording(true); }, { signal } ); CometChatCalls.addEventListener( 'onRecordingStopped', () => { setIsRecording(false); }, { signal } ); return () => controller.abort(); }, []); const toggleRecording = () => { if (isRecording) { CometChatCalls.stopRecording(); } else { CometChatCalls.startRecording(); } }; return ( {isRecording ? 'Stop Recording' : 'Start Recording'} ); } const styles = StyleSheet.create({ button: { flexDirection: 'row', alignItems: 'center', backgroundColor: '#333', paddingHorizontal: 16, paddingVertical: 12, borderRadius: 8, gap: 8, }, recordingButton: { backgroundColor: '#ff4444', }, indicator: { width: 12, height: 12, borderRadius: 6, backgroundColor: '#666', }, recordingIndicator: { backgroundColor: '#fff', }, buttonText: { color: '#fff', fontSize: 14, fontWeight: '600', }, }); export default RecordingControls; ``` ## Related Documentation * [Call Logs](/docs/calls/react-native/call-logs) - Access call history and recordings * [Session Settings](/docs/calls/react-native/session-settings) - Configure recording options * [Events](/docs/calls/react-native/events) - Handle recording events # Ringing Source: https://www.cometchat.com/docs/calls/react-native/ringing Ring users on React Native with the CometChat Calls SDK and the Push Notifications SDK: start a call, show it ringing, answer, decline, cancel and end it, with the app in any state. Ringing lets one user call another and lets the callee answer or decline, whether the callee's app is in the foreground, in the background or not running at all. Two SDKs do the work: | SDK | Owns | | - | - | | **Calls SDK** (`@cometchat/calls-sdk-react-native` 5.1+) | Creating the call, the media session, answering, declining, cancelling, ending, and the call events your code listens to | | **Push Notifications SDK, VoIP package** (`@cometchat/push-notifications-voip-react-native` 2.0+) | Ringing the callee's device: the call notification, the full-screen incoming-call screen on Android, CallKit on iOS, the ringtone, the ring timeout, missed calls and busy handling | > [!NOTE] > > **Coming from the earlier ringing flow?** The Chat SDK's calling methods (`CometChat.initiateCall`, `acceptCall`, `rejectCall`, `endCall`, `CallListener`) are deprecated and are replaced by what this page describes. See [Migrating from legacy ringing](/docs/calls/react-native/migrating-from-legacy-ringing) for a method-by-method mapping. ## How ringing works The caller creates the call with the Calls SDK. The CometChat backend sends a push to the callee. The Push SDK rings the callee's device, and when the callee answers, your call screen joins the session. The caller's app learns that the callee is ringing and has answered from the Calls SDK, without joining the session first. ```mermaid theme={null} sequenceDiagram participant A as Caller app participant BE as CometChat backend participant P as Callee · Push SDK participant C as Callee · Calls SDK A->>BE: CometChatCalls.initiateCall(receiverId, options) Note over A: Session prepared, not joined ("Calling…") BE-->>P: Push (callAction = initiated) P->>P: Ring: notification, full-screen screen / CallKit, ringtone P->>C: connect(sessionId) — pre-warms the session C-->>A: onParticipantConnected → "Ringing…" P->>P: Answer → onCallAccepted C->>C: Mount CometChatCalls.Component with the call token C-->>A: onParticipantJoined → caller joins too Note over A,C: In call. Hang up with session.leave() ``` What each side sees: | Stage | Caller | Callee | | - | - | - | | Call created | `initiateCall` resolves; show "Calling…" | Push arrives; the Push SDK rings | | Callee's device reached | `onParticipantConnected` → show "Ringing…" | Ringing | | Callee answers | `onParticipantJoined` → mount the call component | `onCallAccepted` → mount the call component | | Callee declines / is busy / does not answer | `onCallEnded` with reason `declined` / `timedOut` | Ring stops; missed call if nobody answered | | Caller cancels | — (you ended it) | Ring stops; missed call | | Either side hangs up | `onParticipantLeft` / `onSessionLeft` | same | ## Prerequisites * [Calls SDK set up](/docs/calls/react-native/setup) and the user [logged in](/docs/calls/react-native/authentication). * Push notifications configured with the Push Notifications SDK 2.0. The whole push side of ringing is on the [Push ringing](/docs/calls/react-native/voip-calling) page; this page assumes it is done. * Microphone and camera usage strings in `Info.plist`: `NSMicrophoneUsageDescription` and `NSCameraUsageDescription`. These are yours to add — a library cannot supply them. On Android the VoIP package's own manifest already declares `RECORD_AUDIO` and `CAMERA`, and they merge into your app; the SDKs request them at runtime. * React Native 0.78 or later, `minSdkVersion 24` on Android, and an iOS deployment target of 15.1 or later. ```json package.json theme={null} { "dependencies": { "@cometchat/calls-sdk-react-native": "^5.1.0", "@cometchat/push-notifications-react-native": "^2.0.0", "@cometchat/push-notifications-voip-react-native": "^2.0.0" } } ``` > [!NOTE] > > Some ring behaviours degrade below API 26: Android gained notification channels and full-screen intents there, so on API 24–25 the ring posts a plain notification instead of the channel-backed, full-screen one. The packages themselves build and run at 24. > [!WARNING] > > Send call pushes at **high** FCM priority. At normal priority the call still rings, but Android refuses the Push SDK's foreground service, so the process can be killed between the ring and the answer. > [!NOTE] > > **A missing `NSMicrophoneUsageDescription` crashes the app mid-ring on iOS.** The system terminates the process the moment the SDK touches the microphone, which looks exactly like the ring expiring on its own. Declare both usage strings before testing. ## Start a call `CometChatCalls.initiateCall` creates the call on the backend, which rings the callee, and prepares the caller's media session. The caller does **not** join yet. ```ts theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; const { data: call, error } = await CometChatCalls.initiateCall(receiverUid, { type: 'audio', // or 'video' receiverType: 'user', sessionSettings: { sessionType: 'VOICE', // 'VIDEO' for a video call isPeerCall: true, // 1:1: the call ends for both when either leaves }, }); if (error) { console.error('Could not start the call:', error); } else { console.log(`Calling ${call.receiver}, session ${call.sessionId}`); showOutgoingScreen(call); listenOnPreparedSession(call); } ``` > [!NOTE] > > `initiateCall` and `endCall` resolve to `{ data, error }` — one of the two is always `null`. Check `error` first; there is no `isSuccess` or `value`. Others differ: `connect()` and `login()` reject on failure, and `init()` resolves to `{ success, error }`. | Parameter | Description | | - | - | | `receiverUid` | UID of the user to call, or GUID of the group to ring | | `options.type` | `'audio'` or `'video'` | | `options.receiverType` | `'user'` or `'group'` | | `options.sessionSettings` | The settings the caller's session is prepared with. See the warning below. | `InitiatedCall` gives you `sessionId`, `messageId` (the id of the call message in the conversation), `sender`, `receiver`, `receiverType`, `type`, `status`, `initiatedAt`, `conversationId` and `session` — the session already being prepared for this call. > [!WARNING] > > **Always set the session type in `sessionSettings`, and spell it in capitals.** The only accepted values are `'VOICE'` and `'VIDEO'`. The Calls SDK freezes the session settings when it prepares the session and its default is video, so an audio call started without `sessionType: 'VOICE'` opens the caller's camera — and so does a lowercase `'voice'`, which matches neither value and falls through to video. The settings you pass here are the ones the caller later joins with. > [!NOTE] > > `initiateCall` resolves while the prepare is still in flight (`session.prepareStatus === 'pending'`). Await `session.settled` or read `session.prepareStatus` later for the outcome. **A failed prepare does not fail the call** — by then the call exists on the server and the callee is already ringing — and mounting the call component still works, falling back to a normal direct join. > [!NOTE] > > There is no client-side ring timeout. Both sides stop at the ring window the backend sends in the push (45 seconds by default). A caller that wants its own screen to time out can end the call as `unanswered` after the same window, as shown under [Ring timeout](#ring-timeout). > [!NOTE] > > **On iOS, report the outgoing call to CallKit.** Nothing does it for you: without it CallKit does not own the audio session, so a cellular call or another VoIP app can take the microphone and never give it back, and the call never reaches Recents. Incoming calls get this for free because PushKit forces a CallKit report; an outgoing call has to ask. See [Reporting a call you placed yourself](/docs/calls/react-native/voip-calling#reporting-a-call-you-placed-yourself). The methods are safe to call on Android, where they do nothing. ## Show "Ringing…" and detect the answer The caller stays on the session that `initiateCall` prepared and listens to it. Do not join yet: joining only when the callee has joined keeps the caller's media off until there is someone to talk to, and it is what makes the two events below arrive. ```ts theme={null} function listenOnPreparedSession(call) { const session = CometChatCalls.getActiveSession(); if (!session) return; const me = CometChatCalls.getLoggedInUser()?.uid; const offConnected = session.addEventListener('onParticipantConnected', participant => { // The callee's device received the push and is ringing. if (participant.uid === me) return; setStatus('Ringing…'); }); const offJoined = session.addEventListener('onParticipantJoined', participant => { // The callee answered: now the caller joins. if (participant.uid === me) return; joinCall(call.sessionId); }); // The prepared session closed before anyone joined: the call is over. const offClosed = session.addEventListener('onConnectionClosed', closeOutgoingScreen); return () => [offConnected, offJoined, offClosed].forEach(off => off()); } ``` | Event | On the prepared session it means | | - | - | | `onParticipantConnected(callee)` | The callee's phone got the push and the Push SDK pre-warmed the session: it is ringing there | | `onParticipantJoined(callee)` | The callee answered. Join now | | `onConnectionClosed` | The call ended before anyone joined (declined, cancelled from another device, the session died, or nobody joined within 5 minutes). `onSessionTimedOut` isn't part of this: it only reports an idle joined session | `addEventListener` returns an unsubscribe function. Call it when your screen unmounts; listeners survive the session otherwise. > [!WARNING] > > **A participant who has only prepared isn't in the roster.** A callee whose device has prepared the session reaches the caller as `onParticipantConnected`, not `onParticipantJoined`, and that is the only caller-side signal that the callee's device has been reached. Participants who have actually joined are reported as usual, including to a session that is still prepared, so handle a callee who is already there. > [!NOTE] > > **The caller only shows "Ringing…" once the push has reached the callee's device and its session is prepared.** Until then no `onParticipantConnected` reaches the caller, and the screen stays on "Calling…". ## Listen for calls starting and ending On React Native the Push SDK — not the Calls SDK — is where an incoming call announces itself and its end. It fires even when nothing of yours was running when the push arrived, because it buffers natively and drains the buffer at `init()`. ```ts theme={null} import { CometChatVoipNotifications } from '@cometchat/push-notifications-voip-react-native'; // A call for this user is ringing. The Push SDK already shows the ring; // use this for your own state (badge, analytics, refreshing a list). const offRinging = CometChatVoipNotifications.onCallRinging(call => { console.log('ringing', call.sessionId, 'from', call.callerUid); }); // The user answered — open your call screen. const offAccepted = CometChatVoipNotifications.onCallAccepted(call => { openCallScreen(call.sessionId, call.callType); }); // The call ended. On the caller: "declined", "timedOut" or "cancelled". // event.callAction carries the raw push action — "busy" vs "rejected". const offEnded = CometChatVoipNotifications.onCallEnded(event => { if (event.sessionId === currentSessionId) closeOutgoingScreen(event.reason); }); // The ring itself stopped, whatever happened to the call. const offRingEnded = CometChatVoipNotifications.onRingEnded(event => { dismissIncomingUi(event.sessionId); }); // When the screen goes away: [offRinging, offAccepted, offEnded, offRingEnded].forEach(off => off()); ``` | Who | `onCallEnded` reason | | - | - | | Caller | `declined` (callee declined, or was in another call — `callAction` says which), `timedOut` (nobody answered), `cancelled` (you cancelled from another device) | | Callee, still ringing | `cancelled` (caller gave up), `answeredElsewhere` (answered on another device), `declined` (declined here), `timedOut` (ring timed out) | | Callee, answered | Nothing; the joined session reports the end through `onSessionLeft` / `onConnectionClosed` | `PNCallEndEvent` is `{ sessionId, reason?, callAction? }`. `callAction` is the raw push action the `reason` was mapped from, lower-cased, and is **absent** — not empty — when the end was generated locally rather than by a push, so branch on its presence. Treat `reason` as the exhaustive one and keep a fallback for an action this SDK version has not seen. `PNRingEndEvent` carries the same field. > [!NOTE] > > Each `on…` method returns an unsubscribe function, and subscribing late is safe: a call that was answered before your component mounted is held and delivered to the first subscriber. ## Answer a call The Push SDK rings and, on **Answer**, brings your app to the front and emits `onCallAccepted`. It doesn't ask for the microphone or camera, so call `CometChatPNHelper.requestCallPermissions()` after sign-in. There is no separate "accept" call to make. ```tsx theme={null} function App() { const [activeCall, setActiveCall] = useState(null); useEffect(() => CometChatVoipNotifications.onCallAccepted(call => { setActiveCall(call); // call.sessionId, callerUid, callerName, callType }), []); if (activeCall) return ; return ; } ``` `PNCallInfo` carries `sessionId`, `callerUid`, `callerName`, `callerAvatar`, `callType`, `receiverId`, `receiverType`, `expiresAtMs`, `isPeerCall`, `source` and `callAction`. > [!WARNING] > > **Every field of a call payload arrives from Android as a string.** `isPeerCall` is `"true"` / `"false"`, not a boolean, and `expiresAtMs` is a string of digits. Compare against strings or coerce before use. > [!NOTE] > > **On iOS, a programmatic answer from a cold or background launch is refused by CallKit.** The user's own tap on the CallKit screen is the only thing that can answer a call in that state, which also means automated cold-launch answer tests need a real tap. ## Join the session Both sides join the same way: mount the Calls SDK's call component with the token of the prepared session. Because the session was prepared while ringing, the join is near-instant. ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; function CallScreen({ call }) { const { sessionId, callType } = call; // the PNCallInfo from onCallAccepted const [callToken, setCallToken] = useState(null); useEffect(() => { const offs = []; (async () => { // Derived from the call, never hardcoded: `callType` is 'audio' or 'video', and a // video call joined as 'VOICE' comes up with no camera. const sessionType = callType === 'video' ? 'VIDEO' : 'VOICE'; // Hands back the session already prepared for this call, without minting a second token. const session = await CometChatCalls.connect(sessionId, { sessionType }); setCallToken(session.callToken); // The end of the call comes from the session, not from a prop on the component. offs.push(session.addEventListener('onSessionLeft', goBack)); offs.push(session.addEventListener('onConnectionClosed', goBack)); })(); return () => offs.forEach(off => off()); }, [sessionId, callType]); if (!callToken) return ; return ; } ``` > [!WARNING] > > **`CometChatCalls.Component` takes `callToken` or `sessionId`, and no event props.** It has no `onCallEnded`; passing one is silently ignored, so a screen that relies on it never navigates away. Subscribe to `onSessionLeft` / `onConnectionClosed` on the session, as above. See [Join Session](/docs/calls/react-native/join-session) for the component, [Session Settings](/docs/calls/react-native/session-settings) for layouts and controls, and [Events](/docs/calls/react-native/events) for everything the joined session reports. ## Decline a call Declining is handled by the Push SDK: the Decline button on the notification, on its full-screen incoming-call screen and on CallKit sends `endCall(sessionId, 'rejected')` through a queue that survives the process dying, and sends `'busy'` instead when the user is already in another call. The caller receives `onCallEnded` with that reason. You only write decline code when you draw your own incoming-call screen: ```ts theme={null} CometChatVoipNotifications.declineCall(sessionId); ``` Without the Push SDK's VoIP package, decline through the Calls SDK directly: ```ts theme={null} await CometChatCalls.endCall(sessionId, 'rejected'); ``` > [!NOTE] > > **Android can decline from a fully killed app.** Register the background task so the decline survives the process going away: > > ```ts theme={null} > import { registerBackgroundCallTask } from '@cometchat/push-notifications-voip-react-native'; > registerBackgroundCallTask(); // in index.js, at module scope > ``` ## Cancel a call The caller ends a call that is still ringing with `endCall` and the `cancelled` status. The callee's ring stops and a missed call is posted there. ```ts theme={null} async function cancelOutgoingCall(sessionId: string) { const { error } = await CometChatCalls.endCall(sessionId, 'cancelled'); if (error) console.error('Cancel failed:', error); closeOutgoingScreen(); // close locally either way } ``` Disable the End button after the first tap, and ignore an `onParticipantJoined` that arrives after you cancelled: the cancel wins. ## Ring timeout A call that rings out sends nothing from the callee. When the ring window closes (45 seconds unless the push carries a `ringTimeout`) the callee's Push SDK stops the ring and posts a missed call locally — it does not call `endCall`. The caller's `unanswered` comes from the backend when the same window closes there. To close the caller's screen at that moment even if the push is late, run your own timer from `initiateCall`: ```ts theme={null} const timer = setTimeout(async () => { if (!answered) { await CometChatCalls.endCall(sessionId, 'unanswered'); closeOutgoingScreen(); } }, 45_000); // clear it on answer, cancel and unmount ``` ## End a call Hang up by leaving the session. The room tells the other side, which receives `onParticipantLeft` and then `onSessionLeft` or `onConnectionClosed`. No status needs to be sent and the call is logged by the backend. ```ts theme={null} async function hangUp() { await CometChatCalls.getActiveSession()?.leave(); goBack(); } ``` The other participant: ```ts theme={null} const session = CometChatCalls.getActiveSession(); session?.addEventListener('onSessionLeft', goBack); session?.addEventListener('onConnectionClosed', goBack); ``` > [!NOTE] > > Prefer `session.leave()` to `leaveSession()`: it acts on this call's session. Leave only the session your screen owns: after answering a second call over a live one, the first screen's clean-up must not leave the new session. > [!WARNING] > > `leave()` takes the Calls SDK through a re-initialisation. A `connect()` issued inside that window never resolves, so wait for the leave to settle before preparing the next session — which is what the Push SDK does for you when a second call is answered over a live one. ## Second call while in a call Handled by the Push SDK, the same way a phone does it. A call that arrives while the user is in another call rings over it, with the ordinary incoming-call notification and its Answer and Decline buttons. **Answer** leaves the live call, prepares the new one and emits `onCallAccepted` again for the new session — open a fresh screen for it. **Decline** sends `busy` and keeps the live call. > [!NOTE] > > The SDK never decides on its own that the user is busy. A second call rings, and only the user's own Decline sends `busy` — so a call arriving while another is ringing, or while the user's own outgoing call is still ringing, rings too rather than being auto-rejected. ## Group calls To ring a group, call `initiateCall` with the group's GUID and `receiverType: 'group'`, and leave `isPeerCall` off. A group call can also be a session every member joins with a session id you share with them (for example in a custom message). A group call rung through the push rings every member, and letting it ring out sends nothing. ## Logout Log out of the Calls SDK with `CometChatCalls.logout()` when the user signs out — `CometChatUIKit.logout()` covers the Chat SDK only, not this — and unregister push **before** the session goes away: ```ts theme={null} await CometChatPushNotifications.unregister(); // needs the credential; must come first CometChatVoipNotifications.clearIdentity(); await CometChatUIKit.logout(); // Chat SDK only await CometChatCalls.logout(); ``` `unregister()` deletes the token from the backend and needs the logged-in credential, so after `logout()` there is nothing left to authenticate the delete. Skipping it leaves the device receiving the departed user's call pushes. > [!NOTE] > > The Push SDK keeps the ring identity in step with the Calls SDK's login listener: logging in writes the uid, logging out clears it. An app that logs the **Chat** SDK in and out without `CometChatCalls.login` / `logout` must call `clearIdentity()` itself, as above. ## Call status values These are the backend's own call statuses, which arrive as the push payload's `callAction` and are what `PNCallInfo.callAction` carries. **They are a different vocabulary from the `reason` on `onCallEnded` / `onRingEnded`** — the SDK maps one to the other, so read `callAction` when you need the exact wire value and `reason` when you want the event: | `callAction` | → `reason` | | - | - | | `cancelled` | `cancelled` | | `unanswered`, `timed_out` | `timedOut` | | `ongoing` | `answeredElsewhere` | | `rejected`, `busy`, `ended` | `declined` | | anything else | `remoteEnded` | `rejected` and `busy` both map to `declined`, so a caller that must tell them apart reads `event.callAction` on `onCallEnded` — the raw action, lower-cased. The native iOS SDK's `CallEndReason` collapses them the same way; this mapping is a verbatim port of it. | Status | Meaning | Sent by | | - | - | - | | `initiated` | Created, ringing | Backend, on `initiateCall` | | `ongoing` | Answered | Backend, when the callee joins | | `rejected` | Callee declined | Callee's Push SDK | | `busy` | Callee was in another call | Callee's Push SDK | | `cancelled` | Caller ended it before an answer | Caller, `endCall` | | `unanswered` | Nobody answered in the ring window | Backend, when the ring window closes (or the caller's own timer) | | `ended` | Hung up after being answered | Backend, when the session ends | | `missed` | How an unanswered or cancelled incoming call appears in call logs | Call logs | ## Related * [Push ringing](/docs/calls/react-native/voip-calling): dependencies, `PNConfiguration`, the Firebase and PushKit setup, your own incoming-call screen, readiness checks and what happens when the app is killed. * [Migrating from legacy ringing](/docs/calls/react-native/migrating-from-legacy-ringing). * [Events](/docs/calls/react-native/events), [Actions](/docs/calls/react-native/actions), [Call Logs](/docs/calls/react-native/call-logs). # Screen Sharing Source: https://www.cometchat.com/docs/calls/react-native/screen-sharing View screen shares from other participants in CometChat Calls SDK v5 on React Native, including pinning and layout behavior. The CometChat Calls SDK on React Native supports viewing screen shares from other participants. When a participant shares their screen from a web or desktop client, the React Native SDK automatically displays it. > [!NOTE] > > Initiating a screen share from React Native is not currently supported. React Native devices can view screen shares started by participants on other platforms. ## View Screen Shares When a participant shares their screen, the SDK automatically displays it. Listen for screen share events: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; CometChatCalls.addEventListener('onParticipantStartedScreenShare', (participant) => { console.log(`${participant.name} started screen sharing`); }); CometChatCalls.addEventListener('onParticipantStoppedScreenShare', (participant) => { console.log(`${participant.name} stopped screen sharing`); }); ``` ## Pin Screen Share Pin a participant's screen share to the main view: ```tsx theme={null} CometChatCalls.pinParticipant(participantId, 'screen-share'); ``` ## Layout Behavior When a participant starts sharing their screen: * The SDK automatically switches to Sidebar layout * The screen share is displayed in the main view * Other participants appear in the sidebar When screen sharing stops: * The layout returns to the previous state (if it was programmatically set) ## Complete Example ```tsx theme={null} import React, { useState, useEffect } from 'react'; import { View, Text, StyleSheet } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; function ScreenShareIndicator() { const [remoteSharer, setRemoteSharer] = useState(null); useEffect(() => { const controller = new AbortController(); const { signal } = controller; CometChatCalls.addEventListener( 'onParticipantStartedScreenShare', (participant) => { setRemoteSharer(participant.name); }, { signal } ); CometChatCalls.addEventListener( 'onParticipantStoppedScreenShare', () => { setRemoteSharer(null); }, { signal } ); return () => controller.abort(); }, []); if (!remoteSharer) { return null; } return ( {remoteSharer} is sharing their screen ); } const styles = StyleSheet.create({ container: { padding: 16, alignItems: 'center', }, sharingText: { color: '#6851D6', fontSize: 14, }, }); export default ScreenShareIndicator; ``` ## Related Documentation * [Call Layouts](/docs/calls/react-native/call-layouts) - Layout behavior during screen share * [Participant Management](/docs/calls/react-native/participant-management) - Pin screen shares * [Events](/docs/calls/react-native/events) - Screen share events # Session Settings Source: https://www.cometchat.com/docs/calls/react-native/session-settings Configure CometChat Calls SDK v5 session settings on React Native for call behavior, UI options, participant controls, and features. Configure call sessions using a plain `sessionSettings` object. This allows you to customize the call UI, behavior, and features. ## Session Settings Object The `sessionSettings` object is a plain JavaScript object whose properties configure the call session. Pass it to `CometChatCalls.Component` via the `sessionSettings` prop: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; const sessionSettings = { sessionType: 'VIDEO', layout: 'TILE', hideLeaveSessionButton: false, hideToggleAudioButton: false, hideToggleVideoButton: false, hideSwitchCameraButton: false, hideAudioModeButton: false, startAudioMuted: false, startVideoPaused: false, audioMode: 'SPEAKER', hideRecordingButton: true, autoStartRecording: false, hideTranscriptionButton: true, hideClosedCaptionButton: true, autoStartTranscription: false, captionLanguage: 'en-US', idleTimeoutPeriodBeforePrompt: 180000, enableSpotlightSwap: true, enableSpotlightDrag: true, }; ``` ## Configuration Options ### Call Type | Property | Type | Default | Description | | - | - | - | - | | `sessionType` | string | `'VIDEO'` | Set to `'VOICE'` for audio-only calls or `'VIDEO'` for video calls | ```tsx theme={null} // Audio-only call const audioCallSettings = { sessionType: 'VOICE', }; // Video call (default) const videoCallSettings = { sessionType: 'VIDEO', }; ``` ### Layout Mode | Property | Type | Default | Description | | - | - | - | - | | `layout` | string | `'TILE'` | Call layout mode | Available layouts: | Layout | Description | | - | - | | `'TILE'` | Grid layout with all participants visible | | `'SIDEBAR'` | Focus on one participant with others in a sidebar | | `'SPOTLIGHT'` | Focus on one participant with others overlaid | ```tsx theme={null} const sessionSettings = { layout: 'SPOTLIGHT', }; ``` ### UI Controls | Property | Type | Default | Description | | - | - | - | - | | `hideControlPanel` | boolean | `false` | Hide the entire bottom control bar | | `hideLeaveSessionButton` | boolean | `false` | Hide the leave session button | | `hideToggleAudioButton` | boolean | `false` | Hide the mute audio button | | `hideToggleVideoButton` | boolean | `false` | Hide the pause video button | | `hideSwitchCameraButton` | boolean | `false` | Hide the switch camera button | | `hideAudioModeButton` | boolean | `false` | Hide the audio output (route) button | | `hideRecordingButton` | boolean | `true` | Hide the recording button | | `hideTranscriptionButton` | boolean | `true` | Hide the transcription item in the **More** menu | | `hideClosedCaptionButton` | boolean | `true` | Hide the closed-captions item in the **More** menu | | `hideChangeLayoutButton` | boolean | `false` | Hide the layout-switcher button | | `hideParticipantListButton` | boolean | `false` | Hide the button that opens the participant list | | `hideChatButton` | boolean | `true` | Hide the in-call chat button | | `hideRaiseHandButton` | boolean | `false` | Hide the raise-hand button | | `hideShareInviteButton` | boolean | `true` | Hide the share / invite button | ```tsx theme={null} const sessionSettings = { hideControlPanel: false, hideLeaveSessionButton: false, hideToggleAudioButton: false, hideToggleVideoButton: false, hideSwitchCameraButton: false, hideAudioModeButton: false, hideRecordingButton: false, }; ``` ### Initial State | Property | Type | Default | Description | | - | - | - | - | | `startAudioMuted` | boolean | `false` | Start call with audio muted | | `startVideoPaused` | boolean | `false` | Start call with video paused | | `audioMode` | string | - | Set the default audio output mode | Available audio modes: | Mode | Description | | - | - | | `'SPEAKER'` | Phone speaker | | `'EARPIECE'` | Phone earpiece | | `'BLUETOOTH'` | Bluetooth device | | `'HEADPHONES'` | Wired headphones | ```tsx theme={null} const sessionSettings = { startAudioMuted: true, startVideoPaused: false, audioMode: 'SPEAKER', }; ``` ### Recording | Property | Type | Default | Description | | - | - | - | - | | `hideRecordingButton` | boolean | `true` | Hide the recording button | | `autoStartRecording` | boolean | `false` | Auto-start recording when call begins | ```tsx theme={null} const sessionSettings = { hideRecordingButton: false, autoStartRecording: true, }; ``` ### Transcription & Closed Captions *Available since v5.0.5* | Property | Type | Default | Description | | - | - | - | - | | `hideTranscriptionButton` | boolean | `true` | Hide the **Start / Stop Transcription** item in the **More** menu | | `hideClosedCaptionButton` | boolean | `true` | Hide the **Show / Hide Captions** item in the **More** menu. Even when `false`, the item only appears while transcription is running | | `autoStartTranscription` | boolean | `false` | Auto-start transcription when the call begins | | `captionLanguage` | string | `'en-US'` | Language code used for transcription and captions | ```tsx theme={null} const sessionSettings = { hideTranscriptionButton: false, hideClosedCaptionButton: false, autoStartTranscription: true, captionLanguage: 'en-US', }; ``` See [Transcription](/docs/calls/react-native/transcription) for the supported language codes and transcript retrieval. ### Idle Timeout | Property | Type | Default | Description | | - | - | - | - | | `idleTimeoutPeriodBeforePrompt` | number | `60000` | Milliseconds you may remain alone in the call before the idle prompt appears | | `idleTimeoutPeriodAfterPrompt` | number | `180000` | Milliseconds the prompt stays on screen waiting for a response before the session ends | ```tsx theme={null} const sessionSettings = { idleTimeoutPeriodBeforePrompt: 300000, // 5 minutes idleTimeoutPeriodAfterPrompt: 120000, // 2 minutes }; ``` ### Video Tile Interaction | Property | Type | Default | Description | | - | - | - | - | | `enableSpotlightSwap` | boolean | `true` | Enable clicking video tiles to swap in Spotlight mode | | `enableSpotlightDrag` | boolean | `true` | Enable dragging video tiles in Spotlight mode | ```tsx theme={null} const sessionSettings = { enableSpotlightSwap: true, enableSpotlightDrag: true, }; ``` ### Header & Status Indicators | Property | Type | Default | Description | | - | - | - | - | | `title` | string | `''` | Title text shown in the call's header panel (for example, the room name) | | `hideHeaderPanel` | boolean | `false` | Hide the top header bar (title, session timer, etc.) | | `hideSessionTimer` | boolean | `false` | Hide the elapsed-time timer | | `hideNetworkIndicator` | boolean | `true` | Hide the per-participant network-quality indicator | | `hideRecordingStatusIndicator` | boolean | `false` | Hide the "recording in progress" badge (recording itself is unaffected) | ```tsx theme={null} const sessionSettings = { title: 'Team Standup', hideSessionTimer: false, hideNetworkIndicator: false, }; ``` ### Identity & Behavior | Property | Type | Default | Description | | - | - | - | - | | `displayName` | string | `''` | Display name shown for the local user. Falls back to the logged-in user's name when empty | | `initialCameraFacing` | string | - | Which camera to use at call start: `'FRONT'` or `'REAR'`. The user can still switch afterwards | | `enableNotifications` | boolean | `true` | Show the in-call toast notifications surfaced by the SDK (e.g. "X joined the call"). Set `false` to suppress them | | `enableParticipantContextMenu` | boolean | `true` | Enable the per-participant long-press context menu (pin, etc.). Unavailable in `'SPOTLIGHT'` and picture-in-picture layouts | ```tsx theme={null} const sessionSettings = { displayName: 'Alex', initialCameraFacing: 'FRONT', enableNotifications: true, }; ``` ## Event Subscription Subscribe to call events with `CometChatCalls.addEventListener`. Pass an `AbortSignal` to each listener and call `controller.abort()` once to remove them all on cleanup: ```tsx theme={null} const controller = new AbortController(); CometChatCalls.addEventListener('onParticipantJoined', (participant) => { console.log('Participant joined:', participant); }, { signal: controller.signal }); CometChatCalls.addEventListener('onParticipantLeft', (participant) => { console.log('Participant left:', participant); }, { signal: controller.signal }); CometChatCalls.addEventListener('onParticipantListChanged', (participants) => { console.log('Participant list changed:', participants); }, { signal: controller.signal }); CometChatCalls.addEventListener('onSessionLeft', () => { console.log('Session left'); }, { signal: controller.signal }); CometChatCalls.addEventListener('onLeaveSessionButtonClicked', () => { console.log('Leave session button clicked'); }, { signal: controller.signal }); CometChatCalls.addEventListener('onAudioModeChanged', (mode) => { console.log('Audio mode changed:', mode); }, { signal: controller.signal }); CometChatCalls.addEventListener('onRecordingStarted', () => { console.log('Recording started'); }, { signal: controller.signal }); CometChatCalls.addEventListener('onRecordingStopped', () => { console.log('Recording stopped'); }, { signal: controller.signal }); CometChatCalls.addEventListener('onParticipantAudioMuted', (participant) => { console.log('Participant muted:', participant); }, { signal: controller.signal }); CometChatCalls.addEventListener('onSessionTimedOut', () => { console.log('Session timed out'); }, { signal: controller.signal }); // Later, on cleanup controller.abort(); ``` ## Complete Example ```tsx theme={null} import React, { useEffect, useMemo } from 'react'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; function useCallEvents() { useEffect(() => { const controller = new AbortController(); const { signal } = controller; CometChatCalls.addEventListener('onParticipantJoined', (participant) => { console.log('Participant joined:', participant.name); }, { signal }); CometChatCalls.addEventListener('onParticipantLeft', (participant) => { console.log('Participant left:', participant.name); }, { signal }); CometChatCalls.addEventListener('onSessionLeft', () => { console.log('Session left'); // Navigate back or update UI }, { signal }); return () => controller.abort(); }, []); } function createSessionSettings(isAudioOnly: boolean = false) { return { sessionType: isAudioOnly ? 'VOICE' : 'VIDEO', layout: 'TILE', hideControlPanel: false, hideLeaveSessionButton: false, hideToggleAudioButton: false, hideToggleVideoButton: isAudioOnly, hideSwitchCameraButton: isAudioOnly, hideAudioModeButton: false, startAudioMuted: false, startVideoPaused: false, audioMode: 'SPEAKER', hideRecordingButton: false, hideTranscriptionButton: false, hideClosedCaptionButton: false, autoStartTranscription: false, captionLanguage: 'en-US', idleTimeoutPeriodBeforePrompt: 180000, }; } // Create video session settings const videoSessionSettings = createSessionSettings(false); // Create audio session settings const audioSessionSettings = createSessionSettings(true); ``` ## Related Documentation * [Join Session](/docs/calls/react-native/join-session) - Start a call with these settings * [Events](/docs/calls/react-native/events) - Detailed event documentation * [Actions](/docs/calls/react-native/actions) - Control the call programmatically # Setup Source: https://www.cometchat.com/docs/calls/react-native/setup Set up CometChat Calls SDK v5 for React Native with installation, app credentials, initialization, authentication, and a basic calling flow. > [!NOTE] > > **Faster Integration with UI Kits** > > If you're using CometChat UI Kits, voice and video calling can be quickly integrated: > > * Incoming & outgoing call screens > * Call buttons with one-tap calling > * Call logs with history > > 👉 [React Native UI Kit Calling Integration](/docs/ui-kit/react-native/call-features) > > Use this Calls SDK directly only if you need custom call UI or advanced control. > [!NOTE] > > **Quick Reference for AI Agents & Developers** > > ```bash theme={null} theme={null} > # The SDK plus its six peer dependencies, at these versions > npm install @cometchat/calls-sdk-react-native@^5.1.0 > 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.16.0 react-native-url-polyfill@2.0.0 \ > react-native-webrtc@155.0.1 > cd ios && pod install && cd .. > ``` > > ```xml theme={null} theme={null} > > > > > > > ``` > > * Android 6.0+ **also needs a runtime permission request** — a manifest entry alone is not enough > * Works on the old architecture **and** the New Architecture, including bridgeless — no extra setup > * **Next** → [Authentication](/docs/calls/react-native/authentication) → [Join Session](/docs/calls/react-native/join-session) This guide walks you through installing the CometChat Calls SDK and configuring it in your React Native application. ## Add the CometChat Dependency ### Using npm ```bash theme={null} npm install @cometchat/calls-sdk-react-native@^5.1.0 ``` ### Using Yarn ```bash theme={null} yarn add @cometchat/calls-sdk-react-native@^5.1.0 ``` > [!WARNING] > > **5.1 is required for ringing.** `connect(sessionId)`, `getActiveSession()` and `getSessionState()` arrived in 5.1, and the ring-time pre-join that makes the caller show "Ringing…" depends on them. 5.1.0 is on public npm and is its `latest`, so a plain `npm install` resolves it. > [!NOTE] > > **Ringing users?** Incoming calls ring through the Push Notifications SDK's VoIP package. Install > `@cometchat/push-notifications-react-native@^2.0.0` and > `@cometchat/push-notifications-voip-react-native@^2.0.0` as well, and follow [Push Ringing](/docs/calls/react-native/voip-calling). The Calls SDK alone > can start, join and end calls, but it cannot ring a device that is not running your app. > [!WARNING] > > **Initialise once.** If you use the CometChat UI Kit, it initialises the Calls SDK for you from > `UIKitSettings`, so do not call `init()` again yourself. ## Install Peer Dependencies The Calls SDK relies on the following packages. Install them alongside the SDK: | Package | Version | | - | - | | `@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.16.0` | | `react-native-url-polyfill` | `2.0.0` | | `react-native-webrtc` | `155.0.1` | The package accepts `react-native-svg` from `^15.12.0`. Use `^15.16.0`, the first version whose podspec targets iOS 15.1. ### Using npm ```bash theme={null} 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.16.0 react-native-url-polyfill@2.0.0 react-native-webrtc@155.0.1 ``` ### Using Yarn ```bash theme={null} yarn add @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.16.0 react-native-url-polyfill@2.0.0 react-native-webrtc@155.0.1 ``` ## React Native New Architecture The Calls SDK works with both the old architecture and the New Architecture, including bridgeless mode. No extra setup is needed — leave `newArchEnabled` set to whatever your app requires and follow the same integration steps either way. > [!NOTE] > > The SDK ships as a legacy native module rather than a TurboModule/Fabric component. On the New Architecture it runs through React Native's built-in interop layer, so the API and behavior are identical on both architectures. ## Expo The Calls SDK depends on `react-native-webrtc`, which ships its own Android and iOS native code. That has two consequences for Expo projects: > [!WARNING] > > **The Calls SDK cannot run in Expo Go.** Expo Go bundles a fixed set of native modules and cannot load > `react-native-webrtc`. You need a [development build](https://docs.expo.dev/develop/development-builds/introduction/) — > run `npx expo prebuild` and build with `npx expo run:ios` / `npx expo run:android`, or use EAS Build. `react-native-webrtc` ships no Expo config plugin, so declare the native configuration in `app.json` rather than editing `Info.plist` and `AndroidManifest.xml` by hand — a prebuild regenerates those files and discards manual edits: ```json theme={null} theme={null} { "expo": { "ios": { "infoPlist": { "NSCameraUsageDescription": "Camera access is required for video calls", "NSMicrophoneUsageDescription": "Microphone access is required for voice and video calls" } }, "android": { "permissions": ["CAMERA", "RECORD_AUDIO", "MODIFY_AUDIO_SETTINGS", "BLUETOOTH_CONNECT"] } } } ``` ## iOS Configuration ### Install CocoaPods Dependencies Navigate to your iOS directory and install the pods: ```bash theme={null} cd ios pod install cd .. ``` ### Add Permissions Add the required permissions to your `ios/YourApp/Info.plist`: ```xml theme={null} NSCameraUsageDescription Camera access is required for video calls NSMicrophoneUsageDescription Microphone access is required for voice and video calls ``` ### Enable Background Modes For calls to continue when the app is in the background: 1. Open your project in Xcode 2. Select your target and go to **Signing & Capabilities** 3. Click **+ Capability** and add **Background Modes** 4. Enable: * **Audio, AirPlay, and Picture in Picture** * **Voice over IP** (if using VoIP push notifications) ## Android Configuration ### Add Permissions Add the required permissions to your `android/app/src/main/AndroidManifest.xml`: ```xml theme={null}

``` > [!NOTE] > > For Android 6.0 (API level 23) and above, you must request camera and microphone permissions at runtime before starting a call. ### Request Runtime Permissions Use a library like `react-native-permissions` or implement native permission requests: ```tsx theme={null} import { PermissionsAndroid, Platform } from 'react-native'; async function requestCallPermissions(): Promise { if (Platform.OS === 'android') { const granted = await PermissionsAndroid.requestMultiple([ PermissionsAndroid.PERMISSIONS.CAMERA, PermissionsAndroid.PERMISSIONS.RECORD_AUDIO, ]); return ( granted['android.permission.CAMERA'] === PermissionsAndroid.RESULTS.GRANTED && granted['android.permission.RECORD_AUDIO'] === PermissionsAndroid.RESULTS.GRANTED ); } return true; } ``` ## Verify Installation After installation, rebuild your app: ```bash theme={null} # iOS npx react-native run-ios # Android npx react-native run-android ``` ## Related Documentation * [Authentication](/docs/calls/react-native/authentication) - Initialize the SDK and authenticate users * [Join Session](/docs/calls/react-native/join-session) - Start your first call # Share Invite Source: https://www.cometchat.com/docs/calls/react-native/share-invite Add invite sharing in CometChat Calls SDK v5 on React Native so users can share call links and bring participants into sessions. Allow users to share call invite links with others. When the share invite button is clicked, you can generate and share a link that others can use to join the call. ## Listen for Share Invite Button Click Handle when the user clicks the share invite button: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; CometChatCalls.addEventListener('onShareInviteButtonClicked', () => { console.log('Share invite button clicked'); // Generate and share invite link }); ``` ## Generate Invite Link Create an invite link that others can use to join the call: ```tsx theme={null} function generateInviteLink(sessionId: string): string { // Use your app's deep link scheme const baseUrl = 'https://yourapp.com/call'; return `${baseUrl}?sessionId=${encodeURIComponent(sessionId)}`; } ``` ## Share Using React Native Share Use the built-in Share API to share the invite: ```tsx theme={null} import { Share } from 'react-native'; async function shareInvite(sessionId: string) { const inviteLink = generateInviteLink(sessionId); try { const result = await Share.share({ message: `Join my call: ${inviteLink}`, title: 'Join Call', url: inviteLink, // iOS only }); if (result.action === Share.sharedAction) { if (result.activityType) { console.log('Shared with activity type:', result.activityType); } else { console.log('Shared successfully'); } } else if (result.action === Share.dismissedAction) { console.log('Share dismissed'); } } catch (error) { console.error('Error sharing:', error); } } ``` ## Handle Deep Links Configure your app to handle incoming deep links: ### iOS Configuration Add URL scheme to `ios/YourApp/Info.plist`: ```xml theme={null} CFBundleURLTypes CFBundleURLSchemes yourapp ``` ### Android Configuration Add intent filter to `android/app/src/main/AndroidManifest.xml`: ```xml theme={null}

``` ### Handle Incoming Links ```tsx theme={null} import { useEffect } from 'react'; import { Linking } from 'react-native'; function useDeepLinks(onJoinCall: (sessionId: string) => void) { useEffect(() => { // Handle initial URL (app opened via link) Linking.getInitialURL().then((url) => { if (url) { handleDeepLink(url); } }); // Handle URL when app is already open const subscription = Linking.addEventListener('url', (event) => { handleDeepLink(event.url); }); return () => { subscription.remove(); }; }, []); const handleDeepLink = (url: string) => { try { const parsedUrl = new URL(url); const sessionId = parsedUrl.searchParams.get('sessionId'); if (sessionId) { onJoinCall(sessionId); } } catch (error) { console.error('Error parsing deep link:', error); } }; } export default useDeepLinks; ``` ## Complete Example ```tsx theme={null} import React, { useState, useEffect, useCallback } from 'react'; import { View, TouchableOpacity, Text, StyleSheet, Share, Alert } from 'react-native'; import Clipboard from '@react-native-clipboard/clipboard'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; interface ShareInviteProps { sessionId: string; } function ShareInvite({ sessionId }: ShareInviteProps) { const [showOptions, setShowOptions] = useState(false); useEffect(() => { const unsubscribe = CometChatCalls.addEventListener( 'onShareInviteButtonClicked', () => { setShowOptions(true); } ); return () => unsubscribe(); }, []); const generateInviteLink = useCallback(() => { return `https://yourapp.com/call?sessionId=${encodeURIComponent(sessionId)}`; }, [sessionId]); const handleShare = async () => { const inviteLink = generateInviteLink(); try { await Share.share({ message: `Join my video call!\n\n${inviteLink}`, title: 'Join Call', }); } catch (error) { console.error('Error sharing:', error); } setShowOptions(false); }; const handleCopyLink = () => { const inviteLink = generateInviteLink(); Clipboard.setString(inviteLink); Alert.alert('Link Copied', 'The invite link has been copied to your clipboard.'); setShowOptions(false); }; if (!showOptions) { return ( setShowOptions(true)} > 🔗 Share ); } return ( Share Invite 📤 Share via... 📋 Copy Link setShowOptions(false)} > Cancel ); } const styles = StyleSheet.create({ shareButton: { backgroundColor: '#333', paddingHorizontal: 16, paddingVertical: 12, borderRadius: 8, }, shareButtonText: { color: '#fff', fontSize: 14, fontWeight: '600', }, optionsContainer: { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, backgroundColor: 'rgba(0, 0, 0, 0.5)', justifyContent: 'center', alignItems: 'center', }, optionsCard: { backgroundColor: '#1a1a1a', borderRadius: 16, padding: 20, width: '80%', maxWidth: 300, }, optionsTitle: { color: '#fff', fontSize: 18, fontWeight: '600', textAlign: 'center', marginBottom: 20, }, optionButton: { flexDirection: 'row', alignItems: 'center', backgroundColor: '#333', padding: 16, borderRadius: 8, marginBottom: 12, }, optionIcon: { fontSize: 20, marginRight: 12, }, optionText: { color: '#fff', fontSize: 16, }, cancelButton: { padding: 16, alignItems: 'center', }, cancelText: { color: '#6851D6', fontSize: 16, fontWeight: '600', }, }); export default ShareInvite; ``` ## Universal Links (iOS) For a better user experience, configure Universal Links: 1. Create an `apple-app-site-association` file on your server: ```json theme={null} { "applinks": { "apps": [], "details": [ { "appID": "TEAM_ID.com.yourcompany.yourapp", "paths": ["/call/*"] } ] } } ``` 2. Host it at `https://yourapp.com/.well-known/apple-app-site-association` 3. Add Associated Domains capability in Xcode: * `applinks:yourapp.com` ## App Links (Android) Configure App Links for Android: 1. Create a `assetlinks.json` file: ```json theme={null} [{ "relation": ["delegate_permission/common.handle_all_urls"], "target": { "namespace": "android_app", "package_name": "com.yourcompany.yourapp", "sha256_cert_fingerprints": ["YOUR_SHA256_FINGERPRINT"] } }] ``` 2. Host it at `https://yourapp.com/.well-known/assetlinks.json` 3. Update your intent filter with `autoVerify`: ```xml theme={null} ``` ## Related Documentation * [Join Session](/docs/calls/react-native/join-session) - Join calls via invite links * [Events](/docs/calls/react-native/events) - Share invite button events * [Ringing](/docs/calls/react-native/ringing) - Call notifications # Transcription & Closed Captions Source: https://www.cometchat.com/docs/calls/react-native/transcription Use CometChat Calls SDK v5 transcription on React Native to transcribe calls, show live closed captions, and retrieve transcripts after the call. > [!NOTE] > > **Available since v5.0.5** — transcription and closed captions require CometChat Calls SDK v5.0.5 or later for React Native. See [Setup](/docs/calls/react-native/setup) to install or upgrade. Transcribe call sessions in real time and display live closed captions on screen. Transcripts are stored server-side and can be retrieved after the call using `TranscriptRequestBuilder`. > [!WARNING] > > Transcription must be enabled for your CometChat app. Contact support if you need to enable this feature. ## How It Works Transcription and closed captions are two related but separate things: | Concept | What it does | | - | - | | **Transcription** | Server-side speech-to-text for the session. Starting it brings a transcriber into the call, which produces the transcript that is stored for later retrieval. | | **Closed captions** | The on-screen overlay that renders the live transcript as it arrives. Captions are produced from the running transcription, so they only appear while transcription is active. | Starting transcription is a prerequisite for captions — toggling captions on without an active transcription shows nothing. ## Starting Transcription ### Auto-Start Transcription Configure transcription to start automatically when the session begins: ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; const sessionSettings = { autoStartTranscription: true, // ... other settings }; ``` **Default:** `false` ### Manual Transcription Control #### Start Transcription Begin transcribing during an active call: ```tsx theme={null} CometChatCalls.startTranscription(); ``` #### Stop Transcription Stop the current transcription. Any captions currently on screen are cleared: ```tsx theme={null} CometChatCalls.stopTranscription(); ``` ## Built-in UI Controls Both transcription controls live in the control panel's **More** menu and are hidden by default. ### Transcription Menu Item Show the **Start Transcription** / **Stop Transcription** item: ```tsx theme={null} const sessionSettings = { hideTranscriptionButton: false, // ... other settings }; ``` **Default:** `true` The item toggles between **Start Transcription** and **Stop Transcription** based on the current state. > [!NOTE] > > Even with `hideTranscriptionButton: false`, the item is hidden while another participant is running transcription for the session. Only the participant who started transcription can stop it from the menu. ### Closed Captions Menu Item Show the **Show Captions** / **Hide Captions** item, which toggles the on-screen captions overlay: ```tsx theme={null} const sessionSettings = { hideClosedCaptionButton: false, // ... other settings }; ``` **Default:** `true` > [!NOTE] > > Even with `hideClosedCaptionButton: false`, the item only appears once transcription is running for the session, because captions are generated from the live transcript. ### Captions Overlay When captions are shown, the SDK renders a captions panel between the call stage and the control panel. Each caption shows the speaker's avatar, name, and text. The panel keeps the most recent captions, auto-scrolls to the newest one, and shows a jump-to-latest button when the user has scrolled up to read earlier captions. Until someone speaks, it displays *Waiting for people to speak…*. ## Caption Language **Property:** `captionLanguage` Sets the language used for transcription and captions. ```tsx theme={null} const sessionSettings = { captionLanguage: 'en-US', // ... other settings }; ``` **Default:** `en-US` > [!NOTE] > > On React Native there is no in-call language picker. Set `captionLanguage` in the session settings before joining. > [accordion] Supported Language Codes > > | Code | Language | > | - | - | > | `en-US` | English (United States) | > | `de-DE` | German (Germany) | > | `en-GB` | English (United Kingdom) | > | `es-ES` | Spanish (Spain) | > | `fr-FR` | French (France) | > | `hi-IN` | Hindi (India) | > | `hu-HU` | Hungarian (Hungary) | > | `it-IT` | Italian (Italy) | > | `ja-JP` | Japanese (Japan) | > | `ko-KR` | Korean (South Korea) | > | `lt-LT` | Lithuanian (Lithuania) | > | `ms-MY` | Malay (Malaysia) | > | `nl-NL` | Dutch (Netherlands) | > | `pt-PT` | Portuguese (Portugal) | > | `ru-RU` | Russian (Russia) | > | `sv-SE` | Swedish (Sweden) | > | `tr-TR` | Turkish (Turkey) | > | `zh` | Chinese Mandarin (Simplified, China) | > | `zh-TW` | Chinese Mandarin (Traditional, Taiwan) | ## Retrieving Transcripts After a call, use `TranscriptRequestBuilder` to list the transcript artifacts for a session. Each record is a **pointer to a downloadable transcript file**, not the transcript text itself. > [!NOTE] > > The SDK must be initialized with `CometChatCalls.init()` and a user must be logged in. The auth token is read from the logged-in user at fetch time, so it automatically tracks re-logins. ### Building a Request ```tsx theme={null} import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; const request = new CometChatCalls.TranscriptRequestBuilder() .setSessionId('v1.us.2547167fe69871fd.alice') // required .setLimit(10) // optional .build(); const transcripts = await request.fetchNext(); ``` | Method | Required | Description | | - | - | - | | `setSessionId(sessionId: string)` | Yes | The session ID whose transcripts to fetch. An empty value throws `SESSION_ID_REQUIRED` at `build()`. | | `setLimit(limit: number)` | No | Page size. Defaults to `30` and is clamped to the range `1`–`1000`. | | `build()` | Yes | Returns a `TranscriptRequest`. Throws synchronously for pre-flight errors. | ### Paginating A `TranscriptRequest` is a stateful cursor. Create one per session ID and drive it with `fetchNext()` and `fetchPrevious()`: ```tsx theme={null} const request = new CometChatCalls.TranscriptRequestBuilder() .setSessionId(sessionId) .setLimit(10) .build(); let page = await request.fetchNext(); // page 1 while (page.length > 0) { page.forEach((transcript) => console.log(transcript.transcriptUrl)); page = await request.fetchNext(); // page 2, 3, ... then [] at the end } ``` * `fetchNext()` resolves the next page, or `[]` when there are no more pages. A session with no transcripts resolves `[]`. * `fetchPrevious()` resolves the previous page, or `[]` when already on the first page. It never requests a page below `1`. * Only one fetch may be in flight at a time. Calling `fetchNext()` or `fetchPrevious()` while another request is pending rejects with `REQUEST_IN_PROGRESS`; the original call is unaffected and still completes. ### Transcript Properties The `Transcript` type is exported from the package for TypeScript consumers: ```tsx theme={null} import type { Transcript } from '@cometchat/calls-sdk-react-native'; ``` | Property | Type | Description | | - | - | - | | `tid` | string | Transcript ID | | `mid` | string | Meeting ID | | `roomName` | string | Room name of the meeting | | `startTime` | number | Meeting start time, in epoch **seconds** | | `endTime` | number | Meeting end time, in epoch **seconds** | | `url` | string | Meeting URL | | `transcriptDate` | string | Transcript date | | `transcriptUrl` | string | URL of the downloadable transcript JSON | | `metaData` | object | Arbitrary metadata | > [!NOTE] > > Every property is optional. The server omits keys whose value is empty, so sparse records are normal and should not be treated as an error. ### Reading the Transcript Content `transcriptUrl` points at the transcript file. Fetch it yourself to read the actual utterances: ```tsx theme={null} const [transcript] = await request.fetchNext(); if (transcript?.transcriptUrl) { const response = await fetch(transcript.transcriptUrl); const content = await response.json(); console.log(content); } ``` ### Error Handling `build()` throws synchronously; `fetchNext()` and `fetchPrevious()` reject. Both surface a `CometChatCallsException` carrying a `code`: | Condition | Code | Raised by | | - | - | - | | `init()` was not called | `NOT_INITIALIZED` | `build()` | | `sessionId` missing or empty | `SESSION_ID_REQUIRED` | `build()` | | No logged-in user | `NOT_LOGGED_IN` | `fetchNext()` / `fetchPrevious()` | | A fetch is already in flight | `REQUEST_IN_PROGRESS` | `fetchNext()` / `fetchPrevious()` | | Network failure | `NETWORK_ERROR` | `fetchNext()` / `fetchPrevious()` | | Missing or malformed response | `BAD_RESPONSE` | `fetchNext()` / `fetchPrevious()` | | Server-side API error | The server's own code (e.g. `AUTH_ERR_EMPTY_APPID`) | `fetchNext()` / `fetchPrevious()` | ```tsx theme={null} try { const transcripts = await request.fetchNext(); } catch (error) { console.error(error.code, error.message); } ``` ## Transcripts in Call Logs Call logs can be filtered to transcribed calls, which also attaches each call's transcripts to the log: ```tsx theme={null} const callLogRequest = new CometChatCalls.CallLogRequestBuilder() .setLimit(30) .setHasTranscriptions(true) .build(); const callLogs = await callLogRequest.fetchNext(); callLogs.forEach((callLog) => { callLog.getTranscriptions().forEach((transcription) => { console.log(transcription.getTid(), transcription.getTranscriptURL()); }); }); ``` `getTranscriptions()` returns an empty array when the server omitted transcripts, so it never needs a null check. > [accordion] Transcription Methods > > | Method | Returns | Description | > | - | - | - | > | `getTid()` | string | The transcript ID | > | `getMid()` | string | The meeting ID | > | `getRoomName()` | string | The room name of the meeting | > | `getStartTime()` | number | Meeting start time, in epoch seconds | > | `getEndTime()` | number | Meeting end time, in epoch seconds | > | `getTranscriptDate()` | string | The transcript date | > | `getTranscriptURL()` | string | URL of the downloadable transcript JSON | ## Complete Example ```tsx theme={null} import React, { useEffect, useState } from 'react'; import { View, TouchableOpacity, Text, StyleSheet } from 'react-native'; import { CometChatCalls } from '@cometchat/calls-sdk-react-native'; import type { Transcript } from '@cometchat/calls-sdk-react-native'; // 1. Join a session with transcription enabled const sessionSettings = { sessionType: 'VIDEO', autoStartTranscription: true, hideTranscriptionButton: false, hideClosedCaptionButton: false, captionLanguage: 'en-US', }; function CallScreen({ callToken }: { callToken: string }) { const [isTranscribing, setIsTranscribing] = useState(true); // 2. Control transcription during the call const toggleTranscription = () => { if (isTranscribing) { CometChatCalls.stopTranscription(); } else { CometChatCalls.startTranscription(); } setIsTranscribing(!isTranscribing); }; return ( {isTranscribing ? 'Stop Transcription' : 'Start Transcription'} ); } // 3. Retrieve transcripts after the call async function fetchTranscripts(sessionId: string): Promise { const request = new CometChatCalls.TranscriptRequestBuilder() .setSessionId(sessionId) .setLimit(10) .build(); return request.fetchNext(); } const styles = StyleSheet.create({ container: { flex: 1 }, button: { backgroundColor: '#333', paddingHorizontal: 16, paddingVertical: 12, borderRadius: 8, alignSelf: 'center', }, buttonText: { color: '#fff', fontSize: 14, fontWeight: '600' }, }); export default CallScreen; ``` ## Related Documentation * [Session Settings](/docs/calls/react-native/session-settings) - Configure transcription options * [Actions](/docs/calls/react-native/actions) - Start and stop transcription programmatically * [Call Logs](/docs/calls/react-native/call-logs) - Transcripts attached to call history # Troubleshooting Source: https://www.cometchat.com/docs/calls/react-native/troubleshooting Troubleshoot CometChat Calls SDK v5 on React Native for setup, authentication, permissions, call launch, media, and session issues. ## Installation & Setup | Symptom | Cause | Fix | | - | - | - | | `CometChatCalls is not defined` | SDK not installed or not linked | Run `npm install @cometchat/calls-sdk-react-native` and rebuild | | `init()` fails silently | Invalid App ID or Region | Double-check credentials from the [CometChat Dashboard](https://app.cometchat.com/) | | Build fails on iOS | CocoaPods not installed or outdated | Run `cd ios && pod install` after adding the SDK | | Build fails on Android | Missing native dependencies | Run `npx react-native link` or rebuild with `npx react-native run-android` | *** ## Authentication | Symptom | Cause | Fix | | - | - | - | | `login()` fails with invalid UID | UID doesn't exist in CometChat | Create the user via [Dashboard](https://app.cometchat.com/) or [REST API](/docs/rest-api/users/create) first | | Auth token expired | Token has a limited lifetime | Generate a new auth token and call `login()` again | | `login()` called before `init()` | SDK not initialized | Always `await CometChatCalls.init()` before calling `login()` | *** ## Joining a Session | Symptom | Cause | Fix | | - | - | - | | `generateToken()` fails | User not logged in or invalid session ID | Ensure `login()` completes before generating a token | | Session joins but no audio/video | Permissions not granted | Request camera and microphone permissions before joining. See platform permission guides | | Call fails to connect after rendering `` | Invalid or expired `callToken` | Generate a fresh token with `generateToken()` and pass it as the `callToken` prop. There is no `joinSession()` method in React Native — you join by rendering the component | *** ## Audio & Video | Symptom | Cause | Fix | | - | - | - | | No audio from remote participants | Audio routing issue | Check [Audio Modes](/docs/calls/react-native/audio-modes) for speaker/earpiece configuration | | Camera not working | Permission denied or another app using camera | Check app permissions in device settings | | Black video tiles | Camera permission not granted at OS level | Request permissions using `react-native-permissions` or similar library | *** ## Platform-Specific | Symptom | Cause | Fix | | - | - | - | | App crashes on iOS when joining call | Missing microphone usage description | Add `NSMicrophoneUsageDescription` and `NSCameraUsageDescription` to `Info.plist` | | Android build fails with duplicate classes | Conflicting WebRTC dependencies | Exclude duplicate transitive dependencies in `build.gradle` | | VoIP push notifications not working on iOS | Missing VoIP certificate or CallKit setup | See [VoIP Calling](/docs/calls/react-native/voip-calling) for complete setup | | Background call drops on Android | App killed by OS in background | See [Background Handling](/docs/calls/react-native/background-handling) for foreground service setup | *** ## Picture-in-Picture | Symptom | Cause | Fix | | - | - | - | | PiP not working on iOS | iOS version below 15 or missing entitlement | Ensure iOS 15+ and PiP background mode is enabled | | PiP not working on Android | Missing `supportsPictureInPicture` in manifest | Add PiP activity attribute in `AndroidManifest.xml`. See [PiP](/docs/calls/react-native/picture-in-picture) | *** ## Ringing | Symptom | Cause | Fix | | - | - | - | | Nothing rings in any app state | `@cometchat/push-notifications-voip-react-native` not installed, or `CometChatVoipNotifications.init()` never called | Install it and initialise it; `getDiagnostics()` reports `voip: false` when it is missing | | Rings in the foreground only | The app awaited something before `init()`, so the cold-launch ring window was spent | Make `CometChatVoipNotifications.init()` the first `await` in your entry point | | Caller never shows "Ringing…" | The caller joined right after `initiateCall` instead of listening on the prepared session, or the call was delivered over the websocket rather than by push | Listen for `onParticipantConnected` on `getActiveSession()` before joining | | Chat options silently lost after adding calling | A config was passed to `CometChatVoipNotifications.init()` in an app that also calls the core `init` | Pass the config to the core only; call the VoIP `init()` with no arguments | | Incoming calls stop after switching users | The ring identity is stale | Check `hasLoggedInUid` in diagnostics; log out through the Calls SDK or call `clearIdentity()` | | Answering a second call never connects | The new session was prepared before the live one was released | The Push SDK handles this; if you join yourself, wait for `leave()` to settle first | | iOS: the app dies mid-ring | `NSMicrophoneUsageDescription` is missing | Declare it; check the device crash reports before assuming a ring-timeout bug | | Two ringtones or two screens | Legacy app-side ringing still in place | Remove the `CallListener` ring path — see [Migrating from Legacy Ringing](/docs/calls/react-native/migrating-from-legacy-ringing) | # Push Ringing Source: https://www.cometchat.com/docs/calls/react-native/voip-calling Ring incoming CometChat calls on React Native with the Push Notifications SDK 2.0: FCM and PushKit setup, configuration, answering, permissions, busy and missed calls, your own ring screen, and behaviour when the app is killed. The Push Notifications SDK's VoIP package turns a CometChat call push into a ringing phone: on Android a call-style notification with Answer and Decline, a full-screen screen over the lock screen and the ringtone; on iOS a CallKit call. It works with the app in the foreground, in the background or not running at all. This page covers the push side of ringing. Starting, answering and ending calls with the Calls SDK is on the [Ringing](/docs/calls/react-native/ringing) page. ```mermaid theme={null} flowchart LR FCM["FCM data push (Android)
PushKit (iOS)"] --> H["Push SDK native layer"] H --> D{Push SDK decides} D -->|ring| R["Notification + full-screen screen / CallKit"] D -->|in another call, or another call already ringing| W[Rings anyway] W --> R R -->|Answer| A["onCallAccepted → your call screen"] R -->|Decline| Q["endCall(rejected), queued"] R -->|45 s| T["Ring stops + missed call
(nothing sent)"] ``` ## Prerequisites * [Calls SDK 5.1 set up](/docs/calls/react-native/setup) and the user logged in. * **Android**: a Firebase project with your app, `google-services.json` in `android/app/`, and the Google Services plugin applied (Step 1). You don't need `@react-native-firebase`. * **iOS**: an APNs provider with a token-based (`.p8`) key in the CometChat dashboard, and the **Push Notifications** capability plus the **Voice over IP** background mode enabled in Xcode. * Push notifications enabled in the CometChat dashboard with an **FCM** provider (Android) and an **APNs** provider (iOS), and those providers' ids. * React Native 0.78 or later, `minSdkVersion 24` on Android, and an iOS deployment target of 15.1 or later (what current React Native requires, whatever the packages' podspecs allow). Some ring behaviours degrade below API 26, where Android gained notification channels and full-screen intents: on 24–25 the ring posts a plain notification instead of the channel-backed, full-screen one. ## Step 1: Add the dependencies ```bash theme={null} npm install @cometchat/push-notifications-react-native@^2.0.0 \ @cometchat/push-notifications-voip-react-native@^2.0.0 \ @cometchat/calls-sdk-react-native@^5.1.0 cd ios && pod install ``` ```json package.json theme={null} { "dependencies": { "@cometchat/calls-sdk-react-native": "^5.1.0", "@cometchat/push-notifications-react-native": "^2.0.0", "@cometchat/push-notifications-voip-react-native": "^2.0.0" } } ``` Installing the VoIP package is the whole opt-in: the core package detects it and installs the ringer. The Chat SDK is optional for both packages; a calls-only app works. > [!NOTE] > > The Calls SDK is a dependency of the VoIP package, not a peer: the package calls into it to pre-warm and leave sessions, and a version mismatch there is a silent failure rather than a build error. ### Native setup **Android:** apply the Google Services plugin. The push package already depends on `firebase-messaging`, so don't add it yourself. ```groovy android/build.gradle lines theme={null} buildscript { dependencies { classpath("com.google.gms:google-services:4.4.2") } } ``` ```groovy android/app/build.gradle lines theme={null} apply plugin: "com.google.gms.google-services" ``` **iOS:** register for VoIP pushes before React Native starts, and hand the APNs token to the package. When a call wakes a killed app, iOS terminates the app unless the call reaches CallKit within a few seconds. ```swift ios/YourApp/AppDelegate.swift lines theme={null} import react_native_cometchat_push_notifications import react_native_cometchat_push_notifications_voip // In application(_:didFinishLaunchingWithOptions:), before startReactNative: CometChatPushNotificationsAppDelegate.registerForVoIPPushes() // In your AppDelegate: func application( _ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data ) { CometChatPushNotificationsAppDelegate.didRegisterAPNsToken(deviceToken) } ``` The [iOS push guide](/docs/notifications/react-native-push-notifications-ios) has the full `AppDelegate`. ## Step 2: Initialise once Run this once per app start, as early as you can — the configuration is saved natively, so a push that wakes a cold process still finds it. There are two shapes, and which one you use matters. **A calls-only app** passes its configuration to the VoIP package and calls nothing else. Calling still needs a push token, and the core package is what registers it, so this initialises the core for you: ```ts theme={null} import { CometChatVoipNotifications } from '@cometchat/push-notifications-voip-react-native'; await CometChatVoipNotifications.init({ appId: APP_ID, region: REGION, fcmProviderId: FCM_PROVIDER_ID, apnsProviderId: APNS_PROVIDER_ID, callKitName: 'Acme', }); ``` **An app that also does chat** calls the VoIP `init()` **first and with no arguments**, then initialises the core with its own chat settings: ```ts theme={null} import { CometChatPushNotifications } from '@cometchat/push-notifications-react-native'; import { CometChatVoipNotifications } from '@cometchat/push-notifications-voip-react-native'; // 1. Calling first. With no config this only subscribes to the call events — // it does not initialise the core, so it cannot overwrite your chat settings. await CometChatVoipNotifications.init(); // 2. Then the core, with your own settings. await CometChatPushNotifications.init({ appId: APP_ID, region: REGION, fcmProviderId: FCM_PROVIDER_ID, apnsProviderId: APNS_PROVIDER_ID, notificationSmallIcon: 'ic_notification', androidChannelId: 'chat_messages', callKitName: 'Acme', }); ``` > [!WARNING] > > **This order is not a style choice — reversing it loses the cold-launch ring.** A call that woke the process is reported to CallKit and emitted before JavaScript exists, so native buffers it. The **core's** `init()` is what drains that buffer. Initialise the core first and the ring is delivered while nothing is subscribed to it yet, and it is gone: on iOS the app rings on CallKit but never prepares the session, so the caller is never told the callee is ringing. > [!WARNING] > > **`CometChatVoipNotifications.init()` must be the first thing you `await` on startup.** Anything awaited before it — a stored-credentials read, a chat login, a remote config fetch — eats the cold-launch ring window. > [!NOTE] > > **Don't pass a config to `CometChatVoipNotifications.init()` in a chat app.** With a config it initialises the core for you, using only what you passed — so `notificationSmallIcon`, `androidChannelId` and every other chat-side setting is never set. Pass a config there only in a **calls-only** app, which calls nothing else. | Option | Default | What it does | | - | - | - | | `appId`, `region` | none | Your CometChat app; required unless the Chat SDK already initialised | | `fcmProviderId` / `apnsProviderId` | none | The dashboard providers the token is registered under | | `callMode` | `'auto'` | `'auto'` rings. `'manual'` only parses and forwards; see [manual mode](#manual-mode) | | `notificationSmallIcon` | none | Status-bar icon for every notification (Android) | | `androidChannelId` / `androidChannelName` | SDK defaults | The channel chat notifications are posted on | | `defaultRingTimeoutMs` | `45000` | Ring window when the push carries no `ringTimeout` | | `showMissedCallNotification` | `true` | Post a missed-call notification | | `ringInForeground` | `true` | Ring even when your app is in the foreground | | `showInForeground` | `false` | Show chat notifications while the app is in the foreground | | `callKitName` | `"Calls"` | The name CallKit shows in the system call log (iOS) | | `callKitIconName`, `callKitRingtone`, `callKitSupportsVideo`, `callKitIncludeInRecents` | SDK defaults | CallKit appearance and behaviour (iOS) | | `clientHost` | none | Same value as the Chat SDK's host override; see [Staging deployments](#staging-or-dedicated-deployments) | | `enableBadgeCount`, `sendDeliveryReceipts` | `true` | Chat notification behaviour | | `tokenRegistrar`, `authToken` | auto | Token registration; leave the defaults | ## Step 3: Register the background task Android can send a decline while your app is fully killed. Register the background task at module scope in `index.js`, before `AppRegistry.registerComponent`: ```js index.js theme={null} import { registerBackgroundCallTask } from '@cometchat/push-notifications-voip-react-native'; registerBackgroundCallTask(); ``` Without it, a decline tapped on a killed app is never delivered and the caller rings on to `unanswered`. ## Step 4: Firebase delegation (only if you own the transport) **You normally skip this step.** The package ships its own Firebase messaging service and registers it in its manifest, so call pushes reach it without any code of yours. Declaring your own service in addition is what breaks delivery, not what fixes it. Delegate only if your app already owns a `setBackgroundMessageHandler`: ```js index.js theme={null} import messaging from '@react-native-firebase/messaging'; import { CometChatPushNotifications } from '@cometchat/push-notifications-react-native'; messaging().setBackgroundMessageHandler(async remoteMessage => { // A background handler is a fresh JS runtime with none of your app's state: // initialise CometChat here before handling. const handled = await CometChatPushNotifications.handlePushNotification( remoteMessage.data ?? {}, remoteMessage.sentTime, ); if (!handled) { /* not a CometChat push: your own handling */ } }); ``` > [!WARNING] > > **Pass `sentTime` and hand over every push.** Firebase queues pushes while a device dozes; without the sent time a push delivered late looks fresh and rings for a call that is already over. And do not skip call pushes when the app is in the foreground: the push is the only signal that a call is coming in, in every app state. > [!WARNING] > > **Send call pushes at high FCM priority.** Android lets a background app start a foreground service only with the temporary allowlist that a high-priority data message grants. At normal priority the call still rings, but the process can be killed between the ring and the answer. > [!NOTE] > > **More than one messaging service is not a conflict.** Every app that includes Firebase declares `FirebaseMessagingService` at priority −500; what matters is the service Android actually resolves to. The SDK reports that in `getDiagnostics()` as `competingMessagingService`, which is `null` when all is well. ## Step 5: Answer and join On **Answer** the SDK stops the ring, brings your app to the front and emits `onCallAccepted`. It doesn't ask for the microphone or camera; request them after sign-in (Step 6). There is nothing to "accept". ```tsx theme={null} function App() { const [activeCall, setActiveCall] = useState(null); useEffect(() => { const off = CometChatVoipNotifications.onCallAccepted(call => setActiveCall(call)); const offEnded = CometChatVoipNotifications.onCallEnded(() => setActiveCall(null)); return () => { off(); offEnded(); }; }, []); if (activeCall) return ; return ; } ``` `PNCallInfo` fields: `sessionId`, `callerUid`, `callerName`, `callerAvatar`, `callType`, `receiverId`, `receiverType`, `expiresAtMs`, `isPeerCall`, `source` (`push` for a call the package received, `app` for one handed over with `showIncomingCall`) and `callAction`. `expiresAtMs` is an absolute instant anchored to the caller's own start, not a duration from now, so both sides stop ringing together however late the push arrived — read it rather than starting a timer of your own. > [!WARNING] > > **Every field arrives from Android as a string**, including `isPeerCall` (`"true"` / `"false"`) and `expiresAtMs`. Coerce before use. > [!NOTE] > > A call answered before your JavaScript existed — the killed-app case this package is for — is buffered natively and replayed to the first `onCallAccepted` subscriber. Subscribing late is safe; not subscribing at all means the user answers and nothing happens. ## Step 6: Permissions and ring readiness **On Android there is nothing to declare.** `POST_NOTIFICATIONS` comes from the push package's manifest, and `RECORD_AUDIO`, `CAMERA` and `BLUETOOTH_CONNECT` from the VoIP package's; the manifest merger adds them to your app. The SDK requests the runtime prompts for you — `CometChatPNHelper.requestNotificationPermission()` and `requestCallPermissions()`. **On iOS you do declare these**, because `Info.plist` keys are your app's own and nothing merges them in from a pod: ```xml ios/YourApp/Info.plist theme={null} NSMicrophoneUsageDescription Used for voice and video calls. NSCameraUsageDescription Used for video calls. UIBackgroundModes voipaudio ``` Everything else on Android (full-screen intent, foreground service of type `phoneCall`, `MANAGE_OWN_CALLS`, wake lock, vibrate, the ring activity and the ring service) comes from the packages' own manifests too, and CallKit and PushKit are linked by the VoIP pod. See [the Android permissions breakdown](/docs/notifications/react-native-push-notifications-android) for which package declares what, and what a chat-only app gets. > [!WARNING] > > **A missing `NSMicrophoneUsageDescription` terminates the app mid-ring on iOS.** It looks exactly like the ring expiring early. Check the device's crash reports before treating a short ring as an SDK bug. **Microphone and camera — ask for these yourself.** On React Native the package does **not** prompt when the user answers; it dismisses the ring and hands the call straight to your JavaScript. Call `CometChatPNHelper.requestCallPermissions()` once after sign-in, so the permission is already granted by the time a call arrives. > [!WARNING] > > **A user who declined the microphone answers into a call with no audio, and nothing re-asks.** On Android 14+ the Calls SDK's ongoing-call foreground service also needs `RECORD_AUDIO`. Check `CometChatPNHelper.requestCallPermissions()` succeeded before relying on calls, and ask again from your own call screen if it did not. The native Android SDK re-asks at the moment of answering; the React Native package does not yet. **Ring readiness.** Several device settings silence a call with no error anywhere. Check once after sign-in and tell the user: ```ts theme={null} const readiness = await CometChatPushNotifications.ensureRingReady(); if (readiness !== 'ready') { showBanner(`Incoming calls may not ring: ${readiness}`); await CometChatPushNotifications.openRingSettings(); } ``` | Result | Meaning | | - | - | | `ready` | Nothing in the way | | `notificationsOff` | The app cannot post notifications | | `channelMuted` | The user muted or downgraded the incoming-call channel | | `fullScreenIntentRevoked` | Android 14+ revoked full-screen intents: no ring screen on a locked device, only the heads-up notification | | `dndBlocking` | Do Not Disturb is filtering | | `overlayDenied` | The ring screen cannot be drawn over other apps | | `batteryOptimised` | The process may be frozen before the push arrives | | `autostartDisabled` | An OEM autostart restriction blocks the push wake | | `voipBackgroundModeMissing` | iOS: the `voip` background mode is not declared | | `voipTokenMissing` | iOS: PushKit never issued a token, so no call push can arrive | | `microphoneDenied` | The user refused the microphone; calls still ring but join muted | **Diagnostics for a bug report.** `getDiagnostics()` returns a redacted snapshot (whether a provider id exists, never what it is; never a token or payload): | Key | Read it as | | - | - | | `voip` | `false`: the VoIP package was never initialised, nothing will ring | | `hasLoggedInUid` | `false`: the ring gates have no identity, and a user's own outgoing call can ring their own phone | | `competingMessagingService` | non-`null`: another service is resolving ahead of the SDK's | | `canUseFullScreenIntent` | `false` on Android 14+: no ring screen on a locked device | | `callChannelImportance` | below `IMPORTANCE_HIGH`: no heads-up and no sound | | `interruptionFilter` | anything but `1`: Do Not Disturb is filtering | | `ringReadiness`, `ignoringBatteryOptimizations`, `canDrawOverlays` | Why a push may never reach the device | | `callMode`, `ringInForeground`, `defaultRingTimeoutMs` | `'manual'` explains a phone that never rings by design | | `aggressiveOem`, `manufacturer`, `model`, `sdkInt`, `platform` | OEM background restrictions | `verifyPushSetup()` registers the token and reports one of seven values: `ok`, `notInitialised` (no `init()` yet), `notLoggedIn`, `notificationsDisabled` (the OS permission is off, so nothing can be shown), `tokenNotRegistered`, `testPushUnavailable` (registration worked, the loopback test push is not available on the backend yet: a warning, not a failure) or `testPushTimeout` (the test push never arrived: delivery is broken). The token value is never logged, only its length and a short prefix. ## How a ring ends Every way out is handled by the SDK and needs no code in your app. | What happened | On the callee's device | What the caller learns | | - | - | - | | The user answers | Ring stops, `onCallAccepted` | `onParticipantJoined` | | The user declines | Ring stops; `endCall(sessionId, 'rejected')` is queued and retried across process death | `onCallEnded` with `declined` | | The user declines while in another call | Same, but the status sent is `busy` | `declined` — the same reason; `event.callAction` on `onCallEnded` is `busy` | | The caller cancels | Ring stops on the `cancelled` push, or sooner when the prepared session closes; missed-call notification | Nothing; the caller ended it | | Nobody answers | At the ring window the ring stops and a missed call is posted; **nothing is sent** | `timedOut`, from the backend's own ring window | | Answered on another device | Ring stops on the `ongoing` push, no missed call | `onParticipantJoined` | | The user logs out while ringing | Ring stops, nothing sent, no missed call | Rings to its own window, then `timedOut` | Once the session is prepared, the Calls SDK reporting it ended also stops the ring immediately, without waiting for a terminal push. > [!NOTE] > > **An `ongoing` push is addressed to the CALLER, not the callee.** Its `sender` is whoever performed the action — the callee who answered — so neither a sender nor a receiver comparison can tell you whether it concerns you. The SDK gates it on local ring state instead. ## A call while in a call Call waiting, the way the phone app does it. "In a call" means the Calls SDK is joined to a session, or a call answered here is still joining; a session that is only prepared while it rings does not count. | Situation | Behaviour | | - | - | | Call while in a call | Rings over the live call with the ordinary incoming-call notification and its Answer and Decline buttons. The live call is untouched | | Answer (End & accept) | Leaves the live call, waits for the Calls SDK to release it, prepares the new session, emits `onCallAccepted` for it | | Decline | `busy` is sent, so the caller sees `declined`; the live call continues | | No action | the caller sees `timedOut`, missed call; the live call continues | | Call while another one is already ringing here | It rings too. There is one ring slot, so the newer call takes it and the first ring is replaced | | Call while the user's own outgoing call is ringing | It rings. The user's own outgoing call is unaffected | > [!NOTE] > > **The SDK never decides on its own that the user is busy.** A second call always rings; `busy` is sent only when the user taps Decline on it. The one thing the SDK does suppress is a call's own push arriving back on the caller's device — that is filtered out rather than rung, and nothing is sent to anyone. > [!NOTE] > > End & accept waits for the new session's prepare to settle, up to 5 seconds, before handing the call to your screen. Joining before the previous session has been released is what silently never completes. ## Missed calls Posted as "Missed call" / "Missed group call" with the caller's name and call type, one per session, grouped under the SDK's own summary so Android never folds them into your other notifications. Posted when: nobody answers in the ring window; a `cancelled`, `unanswered` or `timed_out` push ends a ring here; such a push arrives for a call that never rang here (the `initiated` push was lost or overtaken); an `initiated` push arrives already expired. Not posted when: answered here or on another device; declined (`rejected` or `busy`) here; ended; the user's own outgoing call; logout while ringing. Turn missed calls off with `showMissedCallNotification: false`. This is a notification only; call history comes from [Call Logs](/docs/calls/react-native/call-logs). ## When the app is killed This is the case the push exists for. 1. The high-priority data push (Android) or the PushKit push (iOS) starts the app process. 2. The native layer finds no in-memory configuration and restores it from disk. 3. The ring runs on a foreground service of type `phoneCall` on Android, so the system keeps the process alive through the answer; on iOS CallKit holds the call. An alarm backs up the ring timeout. 4. On Answer, the SDK launches your app and buffers the answered call until your JavaScript subscribes. It does not ask for the microphone here — request it after sign-in instead (see Step 6). 5. A **decline** is sent through the background task, so it goes out even if the process dies right after the tap. A ring that simply times out sends nothing — the ring stops, a missed call is posted locally, and the caller's `unanswered` comes from the backend's own ring window. Call `CometChatVoipNotifications.init()` as the first `await` in your app's entry point — **before** reading stored credentials or restoring the session, not from them. It needs no login to wire up the ring; awaiting a credentials read first spends the cold-launch ring window, which is what the warning in step 2 is about. Restore the session straight afterwards, and the answered call is delivered once your JavaScript subscribes. > [!NOTE] > > **On iOS, APNs and VoIP pushes really are delivered to the Simulator** and will cold-launch a killed app. Only CallKit's own call presentation does not appear there, so test the ring on a device and the delivery path anywhere. ## Staging or dedicated deployments If your Chat and Calls SDKs point at a staging or dedicated host, give the Push SDK the same one. Otherwise the token is registered on the default production host, where your app id does not exist, and no push ever arrives. ```ts theme={null} await CometChatVoipNotifications.init({ appId: APP_ID, region: REGION, clientHost: `${APP_ID}.apiclient-us.cometchat-staging.com/v3.0`, }); ``` > [!WARNING] > > **The host override shapes differ between SDKs.** The Chat SDK wants a bare host, the Calls SDK a full URL, and giving one the other's shape hangs login forever rather than failing. The Calls SDK also has three base URLs — admin, client and calls — and setting only one splits call start and call end across environments. ## Tokens You do not register the push token. The SDK fetches it from Firebase or PushKit and registers it on login, under the Chat auth token when there is one and the Calls auth token otherwise. **Unregistering is yours to call.** Unlike the native Android and iOS SDKs, this package installs no logout listener, so nothing deletes the token on its own — see below. Unregister **before** the session goes away: ```ts theme={null} await CometChatPushNotifications.unregister(); // needs the credential; must come first CometChatVoipNotifications.clearIdentity(); await CometChatUIKit.logout(); ``` `unregister()` deletes the token from the backend and needs the logged-in credential, so after `logout()` there is nothing left to authenticate the delete, and the device goes on receiving the departed user's call pushes. > [!NOTE] > > The SDK keeps its ring identity in step with the Calls SDK's login listener: logging in writes the uid, logging out clears it, and `init()` re-reads it to heal a login it missed. An app that logs the **Chat** SDK in and out without `CometChatCalls.login` / `logout` must call `clearIdentity()` itself. > [!WARNING] > > In a calls-only app, `logout()` needs the Chat SDK — so use `clearIdentity()` and `unregister()` instead, and call `init()` again before the next login or the device stays silent. ## Your own incoming-call screen Subscribe to `onCallRinging` and draw your own UI. The SDK still owns the ringtone, the pre-warm, the timeout, the keep-alive and the decline queue; only the UI is yours. ```tsx theme={null} function IncomingCallOverlay() { const [call, setCall] = useState(null); useEffect(() => { const off = CometChatVoipNotifications.onCallRinging(setCall); // Close when the ring ends elsewhere: caller cancelled, answered on another device, timed out. const offEnd = CometChatVoipNotifications.onRingEnded(e => { setCall(c => (c?.sessionId === e.sessionId ? null : c)); }); return () => { off(); offEnd(); }; }, []); if (!call) return null; return ( {call.callerName}

CometChat Video Calls

CometChat Calls

CometChat Calls

CometChat Video Calls