From cd41ed9dfc4011290c0f22748e5686c3e25576fa Mon Sep 17 00:00:00 2001 From: INS201 Date: Thu, 29 Jan 2026 13:52:58 +0530 Subject: [PATCH 1/4] docs: add unreadMessageCount field to push notification payloads - Added unreadMessageCount to push payload example in push-integration.mdx - Added unreadMessageCount to all custom provider payload examples (chat, call, reaction, group action) - Documented 'Include badge count in payload' toggle in preferences.mdx Linear: ENG-28864 --- notifications/custom-providers.mdx | 4 ++++ notifications/preferences.mdx | 1 + notifications/push-integration.mdx | 4 ++++ 3 files changed, 9 insertions(+) diff --git a/notifications/custom-providers.mdx b/notifications/custom-providers.mdx index 36ce0ee5..bb496c77 100644 --- a/notifications/custom-providers.mdx +++ b/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. } }, diff --git a/notifications/preferences.mdx b/notifications/preferences.mdx index 1c7acdcd..115ad594 100644 --- a/notifications/preferences.mdx +++ b/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. diff --git a/notifications/push-integration.mdx b/notifications/push-integration.mdx index 57de2233..c34ff53e 100644 --- a/notifications/push-integration.mdx +++ b/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. } From 03cc8112f846438472af0123f97a73d77d968f68 Mon Sep 17 00:00:00 2001 From: INS201 Date: Thu, 29 Jan 2026 15:03:58 +0530 Subject: [PATCH 2/4] docs: add Badge Count documentation page - Create new badge-count.mdx page with comprehensive documentation - Add to navigation in docs.json under Push tab - Include payload examples for FCM, APNs, and custom providers - Add client-side implementation examples for iOS, Android, React Native, Flutter - Document message type filtering settings and best practices --- docs.json | 1 + notifications/badge-count.mdx | 233 ++++++++++++++++++++++++++++++++++ 2 files changed, 234 insertions(+) create mode 100644 notifications/badge-count.mdx diff --git a/docs.json b/docs.json index 39b0b774..aca723c3 100644 --- a/docs.json +++ b/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", diff --git a/notifications/badge-count.mdx b/notifications/badge-count.mdx new file mode 100644 index 00000000..e28c0a54 --- /dev/null +++ b/notifications/badge-count.mdx @@ -0,0 +1,233 @@ +--- +title: "Badge Count" +--- + +Use this guide to understand and configure 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. + +### Quick flow + +1. Enable the feature in your plan settings (contact support if not available). +2. The badge count is automatically included in push notification payloads. +3. Handle the `unreadMessageCount` field in your app to update the badge. + +### 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 +} +``` + +### Client-side implementation + +#### iOS (Swift) + +Update the badge when receiving a push notification: + +```swift theme={null} +func userNotificationCenter(_ center: UNUserNotificationCenter, + didReceive response: UNNotificationResponse, + withCompletionHandler completionHandler: @escaping () -> Void) { + let userInfo = response.notification.request.content.userInfo + + // Get badge count from payload + if let payload = userInfo["payload"] as? [String: Any], + let badgeCount = payload["unreadMessageCount"] as? Int { + // Update app badge + UIApplication.shared.applicationIconBadgeNumber = badgeCount + } + + completionHandler() +} +``` + +#### Android (Kotlin) + +Update the badge when receiving a push notification: + +```kotlin theme={null} +class MyFirebaseMessagingService : FirebaseMessagingService() { + override fun onMessageReceived(remoteMessage: RemoteMessage) { + val data = remoteMessage.data + + // Get badge count from payload + val badgeCount = data["unreadMessageCount"]?.toIntOrNull() ?: 0 + + // Update badge using ShortcutBadger or similar library + ShortcutBadger.applyCount(applicationContext, badgeCount) + + // Show notification + showNotification(remoteMessage) + } +} +``` + +#### React Native + +Handle badge count in your notification handler: + +```javascript theme={null} +import messaging from '@react-native-firebase/messaging'; +import PushNotificationIOS from '@react-native-community/push-notification-ios'; + +messaging().onMessage(async remoteMessage => { + const badgeCount = parseInt(remoteMessage.data?.unreadMessageCount || '0', 10); + + // iOS + PushNotificationIOS.setApplicationIconBadgeNumber(badgeCount); + + // Android - use a badge library +}); +``` + +#### Flutter + +Handle badge count in your notification handler: + +```dart theme={null} +import 'package:flutter_app_badger/flutter_app_badger.dart'; + +FirebaseMessaging.onMessage.listen((RemoteMessage message) { + final badgeCount = int.tryParse(message.data['unreadMessageCount'] ?? '0') ?? 0; + + // Update badge + FlutterAppBadger.updateBadgeCount(badgeCount); +}); +``` + +### Clearing the badge + +Clear the badge when the user opens the app or marks messages as read: + + + + ```swift theme={null} + // Clear badge when app becomes active + func applicationDidBecomeActive(_ application: UIApplication) { + UIApplication.shared.applicationIconBadgeNumber = 0 + } + ``` + + + + ```kotlin theme={null} + // Clear badge when app opens + override fun onResume() { + super.onResume() + ShortcutBadger.removeCount(applicationContext) + } + ``` + + + + ```javascript theme={null} + import { AppState } from 'react-native'; + import PushNotificationIOS from '@react-native-community/push-notification-ios'; + + AppState.addEventListener('change', (state) => { + if (state === 'active') { + PushNotificationIOS.setApplicationIconBadgeNumber(0); + } + }); + ``` + + + + ```dart theme={null} + import 'package:flutter_app_badger/flutter_app_badger.dart'; + + @override + void didChangeAppLifecycleState(AppLifecycleState state) { + if (state == AppLifecycleState.resumed) { + FlutterAppBadger.removeBadge(); + } + } + ``` + + + +### Message type filtering + +Not all message types increment the badge count. The following settings control which messages affect the count: + +| Setting | Default | Description | +|---------|---------|-------------| +| Replies | Off | Thread replies do not increment count by default | +| Call Activity | On | Call-related messages increment count | +| Custom Messages | On | Custom message types increment count | +| Group Actions | On | Group membership changes increment count | +| Message Actions | Off | Edit/delete actions do not increment count | + +These settings are configured at the plan level and cannot be changed from the dashboard. + +### Best practices + +1. **Always handle missing values** - The `unreadMessageCount` field may be undefined if the feature is disabled or on error. + +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 | Verify the feature is enabled in your plan settings | +| 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 | +| Android badge not working | Some Android launchers don't support badges; use a library like ShortcutBadger | From ac0b5b2c8c56647dd137088a829ec49a1f73948b Mon Sep 17 00:00:00 2001 From: INS201 Date: Thu, 29 Jan 2026 15:11:21 +0530 Subject: [PATCH 3/4] docs: simplify badge count page - remove assumptions - Add note that users need to contact CometChat team to enable feature - Remove message type filtering section - Update troubleshooting to direct users to contact CometChat --- notifications/badge-count.mdx | 26 +++++--------------------- 1 file changed, 5 insertions(+), 21 deletions(-) diff --git a/notifications/badge-count.mdx b/notifications/badge-count.mdx index e28c0a54..a107a2ee 100644 --- a/notifications/badge-count.mdx +++ b/notifications/badge-count.mdx @@ -8,11 +8,9 @@ Use this guide to understand and configure the **unread message badge count** fe 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. -### Quick flow - -1. Enable the feature in your plan settings (contact support if not available). -2. The badge count is automatically included in push notification payloads. -3. Handle the `unreadMessageCount` field in your app to update the badge. + +This is a premium feature. To enable badge count for your application, please [contact the CometChat team](https://www.cometchat.com/contact). + ### How it works @@ -199,23 +197,9 @@ Clear the badge when the user opens the app or marks messages as read: -### Message type filtering - -Not all message types increment the badge count. The following settings control which messages affect the count: - -| Setting | Default | Description | -|---------|---------|-------------| -| Replies | Off | Thread replies do not increment count by default | -| Call Activity | On | Call-related messages increment count | -| Custom Messages | On | Custom message types increment count | -| Group Actions | On | Group membership changes increment count | -| Message Actions | Off | Edit/delete actions do not increment count | - -These settings are configured at the plan level and cannot be changed from the dashboard. - ### Best practices -1. **Always handle missing values** - The `unreadMessageCount` field may be undefined if the feature is disabled or on error. +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. @@ -227,7 +211,7 @@ These settings are configured at the plan level and cannot be changed from the d | Issue | Solution | |-------|----------| -| Badge count not appearing | Verify the feature is enabled in your plan settings | +| 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 | | Android badge not working | Some Android launchers don't support badges; use a library like ShortcutBadger | From 7d73f9f1843ee7520febedb06c91712bfc2bbdf0 Mon Sep 17 00:00:00 2001 From: INS201 Date: Thu, 29 Jan 2026 17:06:03 +0530 Subject: [PATCH 4/4] docs: simplify badge-count page - remove platform-specific client code --- notifications/badge-count.mdx | 131 +--------------------------------- 1 file changed, 1 insertion(+), 130 deletions(-) diff --git a/notifications/badge-count.mdx b/notifications/badge-count.mdx index a107a2ee..f2edc7a7 100644 --- a/notifications/badge-count.mdx +++ b/notifications/badge-count.mdx @@ -2,7 +2,7 @@ title: "Badge Count" --- -Use this guide to understand and configure the **unread message badge count** feature in push notifications. +Use this guide to understand the **unread message badge count** feature in push notifications. ### Overview @@ -69,134 +69,6 @@ When badge count is enabled, the push notification payload includes the `unreadM } ``` -### Client-side implementation - -#### iOS (Swift) - -Update the badge when receiving a push notification: - -```swift theme={null} -func userNotificationCenter(_ center: UNUserNotificationCenter, - didReceive response: UNNotificationResponse, - withCompletionHandler completionHandler: @escaping () -> Void) { - let userInfo = response.notification.request.content.userInfo - - // Get badge count from payload - if let payload = userInfo["payload"] as? [String: Any], - let badgeCount = payload["unreadMessageCount"] as? Int { - // Update app badge - UIApplication.shared.applicationIconBadgeNumber = badgeCount - } - - completionHandler() -} -``` - -#### Android (Kotlin) - -Update the badge when receiving a push notification: - -```kotlin theme={null} -class MyFirebaseMessagingService : FirebaseMessagingService() { - override fun onMessageReceived(remoteMessage: RemoteMessage) { - val data = remoteMessage.data - - // Get badge count from payload - val badgeCount = data["unreadMessageCount"]?.toIntOrNull() ?: 0 - - // Update badge using ShortcutBadger or similar library - ShortcutBadger.applyCount(applicationContext, badgeCount) - - // Show notification - showNotification(remoteMessage) - } -} -``` - -#### React Native - -Handle badge count in your notification handler: - -```javascript theme={null} -import messaging from '@react-native-firebase/messaging'; -import PushNotificationIOS from '@react-native-community/push-notification-ios'; - -messaging().onMessage(async remoteMessage => { - const badgeCount = parseInt(remoteMessage.data?.unreadMessageCount || '0', 10); - - // iOS - PushNotificationIOS.setApplicationIconBadgeNumber(badgeCount); - - // Android - use a badge library -}); -``` - -#### Flutter - -Handle badge count in your notification handler: - -```dart theme={null} -import 'package:flutter_app_badger/flutter_app_badger.dart'; - -FirebaseMessaging.onMessage.listen((RemoteMessage message) { - final badgeCount = int.tryParse(message.data['unreadMessageCount'] ?? '0') ?? 0; - - // Update badge - FlutterAppBadger.updateBadgeCount(badgeCount); -}); -``` - -### Clearing the badge - -Clear the badge when the user opens the app or marks messages as read: - - - - ```swift theme={null} - // Clear badge when app becomes active - func applicationDidBecomeActive(_ application: UIApplication) { - UIApplication.shared.applicationIconBadgeNumber = 0 - } - ``` - - - - ```kotlin theme={null} - // Clear badge when app opens - override fun onResume() { - super.onResume() - ShortcutBadger.removeCount(applicationContext) - } - ``` - - - - ```javascript theme={null} - import { AppState } from 'react-native'; - import PushNotificationIOS from '@react-native-community/push-notification-ios'; - - AppState.addEventListener('change', (state) => { - if (state === 'active') { - PushNotificationIOS.setApplicationIconBadgeNumber(0); - } - }); - ``` - - - - ```dart theme={null} - import 'package:flutter_app_badger/flutter_app_badger.dart'; - - @override - void didChangeAppLifecycleState(AppLifecycleState state) { - if (state == AppLifecycleState.resumed) { - FlutterAppBadger.removeBadge(); - } - } - ``` - - - ### Best practices 1. **Always handle missing values** - The `unreadMessageCount` field may be undefined if the feature is not enabled. @@ -214,4 +86,3 @@ Clear the badge when the user opens the app or marks messages as read: | 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 | -| Android badge not working | Some Android launchers don't support badges; use a library like ShortcutBadger |