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.

This is a premium feature. To enable badge count for your application, please contact the CometChat team.

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)

{
  "message": {
    "data": {
      "title": "George Alan",
      "body": "Hello! How are you?",
      "unreadMessageCount": "5",
      // ... other fields
    }
  }
}

APNs (iOS)

{
  "aps": {
    "alert": {
      "title": "George Alan",
      "body": "Hello! How are you?"
    },
    "badge": 5
  },
  "payload": {
    "unreadMessageCount": 5,
    // ... other fields
  }
}

Custom Provider Webhook

{
  "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 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