> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Badge Count

> Badge Count — CometChat documentation.

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} theme={null}
{
  "message": {
    "data": {
      "title": "George Alan",
      "body": "Hello! How are you?",
      "unreadMessageCount": "5",
      // ... other fields
    }
  }
}
```

**APNs (iOS)**

```json theme={null} 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} 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                                                |