docs: Add Badge Count documentation for Push Notifications

docs.json

@@ -5157,6 +5157,7 @@
                 "pages": [
                   "notifications/preferences",
                   "notifications/templates-and-sounds",
+                  "notifications/badge-count",
                   "notifications/custom-providers",
                   "notifications/logs",
                   "notifications/constraints-and-limits",

notifications/badge-count.mdx

@@ -0,0 +1,88 @@
+---
+title: "Badge Count"
+---
+
+Use this guide to understand the **unread message badge count** feature in push notifications.
+
+### Overview
+
+The badge count feature displays the total number of unread messages for a user as a badge on the app icon. When enabled, each push notification includes an `unreadMessageCount` field that your app can use to update the badge.
+
+<Note>
+This is a premium feature. To enable badge count for your application, please [contact the CometChat team](https://www.cometchat.com/contact).
+</Note>
+
+### How it works
+
+- When a new message is sent, the unread count is incremented for all receivers.
+- When a user reads a message (read receipt), the count is decremented.
+- The count is included in the push notification payload as `unreadMessageCount`.
+- Your app uses this value to set the badge on the app icon.
+
+### Payload structure
+
+When badge count is enabled, the push notification payload includes the `unreadMessageCount` field:
+
+**FCM (Android)**
+
+```json theme={null}
+{
+  "message": {
+    "data": {
+      "title": "George Alan",
+      "body": "Hello! How are you?",
+      "unreadMessageCount": "5",
+      // ... other fields
+    }
+  }
+}
+```
+
+**APNs (iOS)**
+
+```json theme={null}
+{
+  "aps": {
+    "alert": {
+      "title": "George Alan",
+      "body": "Hello! How are you?"
+    },
+    "badge": 5
+  },
+  "payload": {
+    "unreadMessageCount": 5,
+    // ... other fields
+  }
+}
+```
+
+**Custom Provider Webhook**
+
+```json theme={null}
+{
+  "appId": "your-app-id",
+  "receiverUid": "user-123",
+  "title": "George Alan",
+  "body": "Hello! How are you?",
+  "unreadMessageCount": 5,
+  // ... other fields
+}
+```
+
+### Best practices
+
+1. **Always handle missing values** - The `unreadMessageCount` field may be undefined if the feature is not enabled.
+
+2. **Clear badge on app open** - Reset the badge when users open the app to avoid stale counts.
+
+3. **Sync with read receipts** - The badge count automatically decrements when read receipts are sent, so ensure your app sends read receipts properly.
+
+4. **Test across platforms** - Badge behavior varies between iOS and Android; test thoroughly on both.
+
+### Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Badge count not appearing | Ensure the feature is enabled for your app. [Contact CometChat team](https://www.cometchat.com/contact) to enable it. |
+| Count not updating | Ensure read receipts are being sent when messages are read |
+| Badge shows wrong number | Clear the badge on app open and let it sync from the next notification |

notifications/custom-providers.mdx

@@ -81,6 +81,7 @@ Below are sample payloads for different events:
       "conversationId": "cometchat-uid-1_user_cometchat-uid-2", // The ID of the conversation that the message belongs to.
       "type": "chat",
       "sentAt": "1741847453000",
+      "unreadMessageCount": 5, // Optional - only present when "Include badge count in payload" is enabled
       "message": {CometChat Message Object}, // Present if "Include message object" is enabled. The message object is present for new messages or in case a message was edited or deleted.
       "custom": {Custom JSON} // Custom JSON object is added in case it is configured in the preferences.
     }
@@ -127,6 +128,7 @@ Below are sample payloads for different events:
       "sessionId": "v1.123.aik2", // The unique sessionId of the call that can be used as an identifier in CallKit or ConnectionService.
       "callType": "audio", // "audio" or "video"
       "sentAt": "1741847453000",
+      "unreadMessageCount": 5, // Optional - only present when "Include badge count in payload" is enabled
       "custom": {Custom JSON} // Custom JSON object is added in case it is configured in the preferences.
     }
   },
@@ -167,6 +169,7 @@ Below are sample payloads for different events:
       "conversationId": "cometchat-uid-1_user_cometchat-uid-2",
       "type": "chat",
       "sentAt": "1741847453000",
+      "unreadMessageCount": 5, // Optional - only present when "Include badge count in payload" is enabled
       "custom": {Custom JSON} // Custom JSON object is added in case it is configured in the preferences.
     }
   },
@@ -206,6 +209,7 @@ Below are sample payloads for different events:
       "conversationId": "group_cometchat-guid-1",
       "type": "chat",
       "sentAt": "1741847453000",
+      "unreadMessageCount": 5, // Optional - only present when "Include badge count in payload" is enabled
       "custom": {Custom JSON} // Custom JSON object is added in case it is configured in the preferences.
     }
   },

notifications/preferences.mdx

@@ -32,6 +32,7 @@ These control what CometChat includes in push payloads. All are optional toggles
 - Include sender's metadata in payload
 - Include receiver's metadata in payload
 - Trim CometChat message object (strip down to stay within provider limits)
+- Include badge count in payload (Premium feature - adds `unreadMessageCount` field with total unread messages for the user)
 - Additional data in payload (JSON you add)
 
 Use a minimal combination to stay under ~4 KB for FCM/APNs.

notifications/push-integration.mdx

@@ -376,6 +376,10 @@ The push payload delivered to the user's device includes the following informati
   "sessionId": "v1.123.aik2", // The unique sessionId of the said call that can be used as unique identifier in CallKit or ConnectionService.
   "callType": "audio", // Values can be "audio" or "video"
   "sentAt": "1741847453000",
+
+  // Badge count (optional - only present when "Include badge count in payload" is enabled)
+  "unreadMessageCount": 5,
+
   "message": {CometChat Message Object}, // Present if "Include message object" is enabled. The message object is present for new messages or in case a message was edited or deleted.
   "custom": {Custom JSON} // Custom JSON object is added in case it is configured in the preferences.
 }