Docs/docs gap 1

calls/javascript/virtual-background.mdx

@@ -79,5 +79,19 @@ Virtual backgrounds use machine learning for background segmentation. Performanc
 - Browser version
 - Camera resolution
 
-For best results, use a modern browser on a device with adequate processing power.
+### Browser Compatibility
+
+| Platform | Browser | Supported |
+|----------|---------|-----------|
+| Desktop (Windows, macOS, Linux) | Chrome | ✅ Yes |
+| Desktop (Windows, macOS, Linux) | Firefox | ✅ Yes |
+| Desktop | Safari, Edge, others | ❌ Not supported |
+| iOS (iPhone, iPad) | Safari, Chrome, any browser | ❌ Not supported |
+| Android | Chrome | ❌ Not supported |
+
+<Warning>
+Virtual background is **only supported on desktop Chrome and Firefox**. All browsers on iOS use WKWebView under the hood, which does not provide the APIs required for real-time background segmentation.
+</Warning>
+
+For best results, use desktop Chrome or Firefox on a device with adequate processing power.
 

calls/v4/javascript/virtual-background.mdx

@@ -16,6 +16,10 @@ description: "CometChat Calling SDK v4 - Stable Release - Virtual Background for
 
 This section will guide you to implement virtual background feature in video calls.
 
+<Warning>
+**Browser Compatibility:** Virtual background is supported on **desktop Chrome only**. It is **not supported on iOS device browsers** (Safari, Chrome for iOS, or any browser) because all iOS browsers use WKWebView, which does not provide the APIs required for real-time background segmentation.
+</Warning>
+
 ## Implementation
 
 Once you have decided to implement [Ringing](/calls/v4/javascript/ringing) or [Call Session](/calls/v4/javascript/call-session) calling and followed the steps to implement them. Just few additional methods will help you quickly implement virtual background.

notifications/flutter-push-notifications-ios.mdx

@@ -63,6 +63,10 @@ Keep the provider IDs—you’ll set them in `CometChatConfig`.
 2. Enable Push Notifications plus Background Modes → *Remote notifications* and *Voice over IP* on the bundle ID.
 3. Create a VoIP Services certificate/key if you want separate credentials.
 
+<Warning>
+**`.p12` certificates are deprecated.** Apple recommends using `.p8` Auth Keys for push notifications. `.p8` keys never expire and work across all your apps. Migrate to `.p8` if you haven't already.
+</Warning>
+
 ### 2.2 Firebase Console
 
 1. Register the same bundle ID and download `GoogleService-Info.plist` into `ios/Runner`.
@@ -204,6 +208,17 @@ This registers the device token against the APNs provider selected in `CometChat
 - `FlutterCallkitIncoming.onEvent` is already wired inside `APNSService` to accept or end calls initiated by CallKit.
 - When native CallKit UI accepts/ends a call, Swift invokes `onCallAcceptedFromNative` / `onCallEndedFromNative` on the MethodChannel; `APNSService` then calls `FlutterCallkitIncoming.setCallConnected` or `CometChat.endCall()` to keep both stacks synchronized.
 
+<Warning>
+**Cold-start VoIP call handling:** When the app is killed (not running) and a VoIP push arrives, the standard CometChat call listeners (`onOutgoingCallAccepted`, `onIncomingCallReceived`, etc.) will **not** fire because the Flutter engine is not yet initialized. In this scenario, you need a **native-to-Flutter bridge** that:
+
+1. Handles the VoIP push entirely in native Swift code (`AppDelegate` / `PushKit` handler).
+2. Presents the CallKit UI natively.
+3. When the user accepts, initializes the CometChat SDK from the native side using `CometChat.generateToken()` and `CometChat.startSession()`.
+4. Bridges the call state back to Flutter via a MethodChannel once the Flutter engine is ready.
+
+The standard `CometChatCallingExtension` call listeners only work when the app is already running (foreground or background with an active Flutter engine). See the [sample app's `AppDelegate.swift`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app_push_notifications/ios/Runner/AppDelegate.swift) for a reference implementation of this native bridge pattern.
+</Warning>
+
 ## 7. Badge count using `unreadMessageCount`
 
 CometChat's Enhanced Push Notification payload includes an `unreadMessageCount` field representing the total unread messages across all conversations for the logged-in user. On iOS the badge can be updated from both the client side and the server side.

notifications/ios-apns-push-notifications.mdx

@@ -46,6 +46,10 @@ description: "Implement APNs push notifications with CometChat UIKit for iOS, in
    - Add an **APNs Device** provider (alerts) using your `.p8` key, Team ID, Key ID, and Bundle ID; copy the Provider ID.
    - Add an **APNs VoIP** provider (calls) with the same `.p8` (recommended for CallKit reliability); copy the Provider ID.
 
+<Warning>
+**`.p12` certificates are deprecated.** Apple recommends using `.p8` Auth Keys for push notifications. `.p8` keys are simpler to manage (one key works for all your apps), never expire, and are the only format actively supported going forward. If you are still using `.p12`, migrate to `.p8` at your earliest convenience.
+</Warning>
+
 <Frame>
   <img
     src="/images/1133421a-add-apns-credentials-f8c2fd747ab4cf3905c6d13cf215b4c1.png"

notifications/push-overview.mdx

@@ -28,6 +28,10 @@ CometChat listens for chat and call events, assembles payloads from your templat
 - Group membership changes (join/leave/ban).
 - Call invites, missed calls, and ongoing call updates.
 
+<Note>
+**Call notifications and group calls:** Call-related push notifications (e.g., initiated calls, missed calls) are sent as **custom messages**, not as group action messages. The **production mode toggle** in the dashboard only affects APNs endpoint routing (sandbox vs production) — it does not change how the Notification Engine constructs the push payload. If you experience APNs errors (e.g., 400 status) for call pushes, check your APNs provider credentials and certificate configuration rather than the production mode toggle.
+</Note>
+
 ## Before you integrate
 
 1. **Dashboard setup**: Enable Push Notifications, add providers (FCM for Android/iOS, APNs + optional APNs VoIP for iOS), and copy Provider IDs.

notifications/react-native-push-notifications-ios.mdx

@@ -109,6 +109,10 @@ For iOS we use Apple Push Notification service (APNs) for both standard and VoIP
     2. Enter a key name, check **Apple Push Notification service (APNs)**, then **Continue** → **Register**.  
     3. Download the `.p8` file and note the **Key ID**, **Team ID**, and your **Bundle ID**—you’ll enter these in CometChat.  
     4. *(Optional)* If you still use `.p12`, export it from the downloaded key without an export password; keep it handy for upload.
+
+    <Warning>
+    **`.p12` certificates are deprecated.** Apple recommends using `.p8` Auth Keys for push notifications. `.p8` keys are simpler to manage (one key works for all your apps), never expire, and are the only format actively supported going forward. Migrate to `.p8` if you haven't already.
+    </Warning>
   </Step>
 </Steps>
 

notifications/templates-and-sounds.mdx

@@ -385,6 +385,14 @@ Use this sparingly to avoid surprising users. Set only the preferences that chan
 - Use `sender@group` style for group titles to disambiguate conversations.
 - Avoid placeholders in fallback text to prevent unresolved values.
 
+### Group call notifications
+
+<Note>
+Group call notifications (e.g., "User started a group call") are sent as **custom messages** (`category: "custom"`), not as group action messages. This means they are governed by the [custom message templates](#5-custom-message-templates) above, and the `GROUP_ACTIONS_PREFERENCE` setting does **not** affect group call notifications.
+
+If you want to suppress or customize group call notifications independently, configure the custom message template or handle them in your client-side notification logic.
+</Note>
+
 ### Sounds
 
 Include sound files in your app bundle and set the `sound` field in the push payload to the filename (omit extension if your platform expects that).

rest-api/users/delete.mdx

@@ -4,3 +4,7 @@ description: "Deletes a user for the specified UID"
 ---
 
 For the complete error reference, see [Error Guide](/articles/error-guide).
+
+<Warning>
+**Permanent deletion:** By default, deleting a user only deactivates them. To **permanently** delete a user along with all their messages, conversations, and associated data, you must include `permanent: true` in the request body. This action is irreversible.
+</Warning>

sdk/flutter/3.0/overview.mdx

@@ -80,6 +80,10 @@ end
 
 </Tabs>
 
+<Warning>
+**Apple Silicon (M1/M2/M3) users:** Excluding `arm64` from the simulator build prevents the app from running natively on Apple Silicon Macs. If you are developing on an Apple Silicon Mac, consider excluding only `i386` instead of `arm64 i386` to enable native simulator builds.
+</Warning>
+
 4. For iOS navigate to your iOS folder in terminal or CMD and do `pod install` . For apple chip system use rosetta terminal.
 5. import CometChat SDK using the following code in dart.
 

sdk/flutter/3.0/setup.mdx

@@ -64,6 +64,10 @@ end
 
 </Tab>
 
+
+<Warning>
+**Apple Silicon (M1/M2/M3) users:** Excluding `arm64` from the simulator build prevents the app from running natively on Apple Silicon Macs. If you are developing on an Apple Silicon Mac, consider excluding only `i386` instead of `arm64 i386` to enable native simulator builds.
+</Warning>
 </Tabs>
 
 3. For iOS, change the deployment target to `11` or higher.

sdk/flutter/setup.mdx

@@ -97,6 +97,10 @@ end
 </Tab>
 </Tabs>
 
+<Warning>
+**Apple Silicon (M1/M2/M3) users:** Excluding `arm64` from the simulator build prevents the app from running natively on Apple Silicon Macs. If you are developing on an Apple Silicon Mac, consider excluding only `i386` instead of `arm64 i386` to enable native simulator builds.
+</Warning>
+
 2. Change the deployment target to `11` or higher.
 3. Navigate to your iOS folder in terminal and run `pod install`. For Apple Silicon systems, use a Rosetta terminal.
 4. Set **Enabled Bitcode** to **NO** in the Build Settings of your Xcode project.

sdk/flutter/user-management.mdx

@@ -74,7 +74,7 @@ CometChat.createUser(user, authKey, onSuccess: (User user) {
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `user` | `User` | A `User` object containing the details of the user to be created. The `uid` and `name` fields are required. |
+| `user` | `User` | A `User` object containing the details of the user to be created. The `uid` and `name` fields are **required**. |
 | `authKey` | `String` | Your CometChat Auth Key. Use only for development — never expose in production client code. |
 | `onSuccess` | `Function(User user)` | Callback triggered on successful user creation, returning the created `User` object. |
 | `onError` | `Function(CometChatException excep)` | Callback triggered on failure, returning a `CometChatException` with error details. |

sdk/flutter/v5/setup.mdx

@@ -78,6 +78,10 @@ end
 
 </Tabs>
 
+<Warning>
+**Apple Silicon (M1/M2/M3) users:** Excluding `arm64` from the simulator build prevents the app from running natively on Apple Silicon Macs. If you are developing on an Apple Silicon Mac, consider excluding only `i386` instead of `arm64 i386` to enable native simulator builds.
+</Warning>
+
 3. For iOS, change the deployment target to `11` or higher.
 4. For iOS, navigate to your iOS folder in terminal or CMD and do `pod install` . For apple chip system use rosetta terminal.
 5. For iOS you can set the Enabled Bitcode settings to **NO** present in build settings of XCODE project

ui-kit/react-native/call-features.mdx

@@ -162,6 +162,10 @@ end
 
 </Tabs>
 
+<Warning>
+**Apple Silicon (M1/M2/M3) users:** Excluding `arm64` from the simulator build prevents the app from running natively on Apple Silicon Macs. If you are developing on an Apple Silicon Mac, consider excluding only `i386` instead of `arm64 i386` to enable native simulator builds.
+</Warning>
+
 ## Add the Call Listeners
 
 In addition to CallButtons, the Calls UI Kit offers fully functional UI components for handling Incoming, Outgoing, and Ongoing calls. To receive call events in your desired component or screen, you must register a call listener using the `addCallListener()` method. The `onIncomingCallReceived()` event is triggered whenever an incoming call is received.

ui-kit/react-native/calling-integration.mdx

@@ -100,6 +100,10 @@ post_install do |installer|
 end
 ```
 
+<Warning>
+**Apple Silicon (M1/M2/M3) users:** Excluding `arm64` from the simulator build prevents the app from running natively on Apple Silicon Macs. If you are developing on an Apple Silicon Mac, consider excluding only `i386` instead of `arm64 i386` to enable native simulator builds.
+</Warning>
+
 ## Set Up Call Listeners
 
 Register a call listener to receive call events in your component:

ui-kit/react-native/conversations.mdx

@@ -921,6 +921,10 @@ function StyledConversations() {
 | `itemStyle` | `object` | Style for list items (includes `avatarStyle`, `badgeStyle`, `titleStyle`, `subtitleStyle`) |
 | `searchStyle` | `object` | Style for the search bar |
 
+<Note>
+**Avatar style override in Conversations:** `CometChatConversations` generates its own internal avatar style that overrides the base theme's `avatarStyle`. To customize avatar appearance specifically within the conversation list, you must set `avatarStyle` through the `itemStyle` prop on `CometChatConversations` (i.e., `style.itemStyle.avatarStyle`). Setting `avatarStyle` at the theme level via `CometChatThemeProvider` will not take effect for the conversation list.
+</Note>
+
 ---
 
 ## Props

ui-kit/react-native/v4/call-features.mdx

@@ -143,6 +143,10 @@ end
 
 </Tabs>
 
+<Warning>
+**Apple Silicon (M1/M2/M3) users:** Excluding `arm64` from the simulator build prevents the app from running natively on Apple Silicon Macs. If you are developing on an Apple Silicon Mac, consider excluding only `i386` instead of `arm64 i386` to enable native simulator builds.
+</Warning>
+
 ## Add the Call Listeners
 
 Apart from Call Buttons, the Calls UI Kit also provides fully functional UI components for Incoming, Outgoing and Ongoing Calls.

widget/html/overview.mdx

@@ -27,6 +27,10 @@ The widget connects to CometChat's SDK and infrastructure, which manages message
 The Chat Widget is not customizable beyond the configuration options available in the Widget Builder in dashboard. If you require deeper customization, consider using our [UI Kits](/ui-kit/react/overview) instead.
 </Warning>
 
+<Note>
+**Legacy Widget (v3):** If you previously used the legacy CometChat Widget (v3), the legacy widget section in the Dashboard is only visible for apps that had legacy widgets configured before the migration to Widget Builder. New apps will not see the legacy widget section. For migration guidance, see the [Migration Guide](/articles/migration-guide).
+</Note>
+
 ---
 
 ## Widget Builder Features

widget/shopify/integration.mdx

@@ -68,6 +68,7 @@ Add the CometChat Widget with a single snippet inside your Shopify theme. Choose
     //chatType: "user" | "group",
     //defaultChatID: "uid_or_guid",
     //dockedAlignment: "left" | "right"
+    //autoOpenFirstItem: false,
   };
 
   CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);
@@ -78,7 +79,7 @@ Add the CometChat Widget with a single snippet inside your Shopify theme. Choose
 - `appID`, `region`, `authKey`: Copy from the CometChat Dashboard (use an **App Auth Key**, not REST API key).  
 - `user.name`, `user.avatar`, `user.link`: Optional guest display info.  
 - `width`, `height`, `isDocked`: Size/placement (`isDocked = true` shows a docked bubble).  
-- `variantID`, `chatType`, `defaultChatID`, `dockedAlignment`: Optional widget targeting/placement controls.
+- `variantID`, `chatType`, `defaultChatID`, `dockedAlignment`, `autoOpenFirstItem`: Optional widget targeting/placement controls. Set `autoOpenFirstItem: false` to prevent the widget from automatically opening the first conversation on load.
 
 ---
 

widget/squarespace/integration.mdx

@@ -69,6 +69,7 @@ Add the CometChat Widget by pasting one small code snippet. It drops in like any
     width: "400px",
     height: "80vh",
     isDocked: true,
+    //autoOpenFirstItem: false,
   };
 
   const startWidget = () => CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);
@@ -175,6 +176,7 @@ function initializeCometChat() {
         isDocked: true,
         width: "400px",
         height: "80vh",
+        //autoOpenFirstItem: false,
       });
     } catch {}
   };
@@ -232,6 +234,7 @@ Full walkthrough: [How to properly log in and create users in CometChat](https:/
     width: "400px",
     height: "80vh",
     isDocked: true,
+    //autoOpenFirstItem: false,
   };
 
   const startWidget = () => CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);

widget/webflow/integration.mdx

@@ -84,6 +84,7 @@ Click **Save**, publish the site, then **Visit Website** to confirm the widget a
     //chatType: "user" | "group",
     //defaultChatID: "uid_or_guid",
     //dockedAlignment: "left" | "right"
+    //autoOpenFirstItem: false,
   };
 
   const startWidget = () => CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);
@@ -107,6 +108,7 @@ Click **Save**, publish the site, then **Visit Website** to confirm the widget a
 | `chatType` | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat). |
 | `defaultChatID` | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads. |
 | `dockedAlignment` | Controls the position of the docked widget interface on the page (left side or right side). |
+| `autoOpenFirstItem` | When set to false, the widget does not automatically open the first conversation on load. Defaults to true. |
 
 ---
 
@@ -152,6 +154,7 @@ Click **Save**, publish the site, then **Visit Website** to confirm the widget a
     //chatType: "user" | "group",
     //defaultChatID: "uid_or_guid",
     //dockedAlignment: "left" | "right"
+    //autoOpenFirstItem: false,
   };
 
   const startWidget = () => CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);
@@ -177,6 +180,7 @@ Click **Save**, publish the site, then **Visit Website** to confirm the widget a
 | `chatType` | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat). |
 | `defaultChatID` | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads. |
 | `dockedAlignment` | Controls the position of the docked widget interface on the page (left side or right side). |
+| `autoOpenFirstItem` | When set to false, the widget does not automatically open the first conversation on load. Defaults to true. |
 
 ### Memberstack auto-login (Webflow + Memberstack, still UID flow)
 
@@ -402,6 +406,7 @@ Full walkthrough: [How to properly log in and create users in CometChat](https:/
     //chatType: "user" | "group",
     //defaultChatID: "uid_or_guid",
     //dockedAlignment: "left" | "right"
+    //autoOpenFirstItem: false,
   };
 
   const startWidget = () => CometChatApp.CometChatAuth.start(COMETCHAT_WIDGET_CONFIG);
@@ -426,6 +431,7 @@ Full walkthrough: [How to properly log in and create users in CometChat](https:/
 | `chatType` | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat). |
 | `defaultChatID` | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads. |
 | `dockedAlignment` | Controls the position of the docked widget interface on the page (left side or right side). |
+| `autoOpenFirstItem` | When set to false, the widget does not automatically open the first conversation on load. Defaults to true. |
 
 ---