> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/llms.txt
> Use this file to discover all available pages before exploring further.

# Channel Unread Count

> Read per-channel and total chat unread counts from SDK channel objects.

Use channel unread count when your app needs inbox badges, mention indicators, or total chat unread state. The SDK exposes unread state on channel models and provides an aggregate total for channels known to the current user.

## Platform Surface

| Surface                         | TypeScript                                           | iOS                                          | Android                                     | Flutter                    |
| ------------------------------- | ---------------------------------------------------- | -------------------------------------------- | ------------------------------------------- | -------------------------- |
| Channel count                   | `channel.unreadCount`                                | `channel.unreadCount`                        | `channel.getUnreadCount()`                  | `channel.unreadCount`      |
| Channel mention                 | `channel.isMentioned`                                | `channel.isMentioned`                        | `channel.isMentioned()`                     | `channel.isMentioned`      |
| Support flag                    | `channel.isUnreadCountSupport`                       | `channel.isUnreadCountSupported`             | `channel.isUnreadCountSupport()`            | Not exposed                |
| Subchannel aggregate on channel | `channel.subChannelsUnreadCount`                     | `channel.subChannelsUnreadCount`             | `channel.getSubChannelsUnreadCount()`       | Not exposed                |
| Total channel unread            | `ChannelRepository.getTotalChannelsUnread(callback)` | `channelRepository.getTotalChannelsUnread()` | `channelRepository.getTotalChannelUnread()` | `getChannelTotalUnreads()` |

## Parameters

| Parameter                         | Required                     | Description                                                                                  |
| --------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------- |
| `channelId`                       | Yes for single-channel reads | Channel ID used to retrieve or observe a channel model.                                      |
| Channel object                    | Yes                          | Read `unreadCount` and `isMentioned` from the latest channel model returned by the SDK.      |
| Aggregate observer                | Yes for total unread         | Subscribe to the total-unread API for cross-channel badge state.                             |
| Unsubscriber / token / disposable | Yes for live observers       | Keep the returned handle while observing and release it when the UI no longer needs updates. |

## Read Channel Unread State

Read unread count and mention state from the channel object. If the platform exposes a support flag, check it before showing unread count for channel types that do not support markers.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { ChannelRepository } from '@amityco/ts-sdk';

  const unsubscribe = ChannelRepository.getChannel(
    channelId,
    ({ data: channelSnapshot, loading, error }) => {
      if (error) {
        handleError(error);
        return;
      }

      if (!loading && channelSnapshot?.isUnreadCountSupport) {
        renderResults({
          unreadCount: channelSnapshot.unreadCount,
          isMentioned: channelSnapshot.isMentioned,
          subChannelsUnreadCount: channelSnapshot.subChannelsUnreadCount,
        });
      }
    },
  );

  unsubscribe();
  ```

  ```swift iOS theme={null}
  token = channelRepository.getChannel(channelId).observe { liveObject, error in
      if let error {
          handleError(error)
          return
      }

      guard let channel = liveObject.snapshot else { return }

      if channel.isUnreadCountSupported {
          showSuccessMessage([
              "unreadCount": channel.unreadCount,
              "isMentioned": channel.isMentioned,
              "subChannelsUnreadCount": channel.subChannelsUnreadCount
          ])
      }
  }
  ```

  ```kotlin Android theme={null}
  val currentChannel = channel ?: return

  if (currentChannel.isUnreadCountSupport()) {
      showSuccessMessage(
          mapOf(
              "unreadCount" to currentChannel.getUnreadCount(),
              "isMentioned" to currentChannel.isMentioned(),
              "subChannelsUnreadCount" to currentChannel.getSubChannelsUnreadCount(),
          ),
      )
  }
  ```

  ```dart Flutter theme={null}
  final fetchedChannel = await AmityChatClient.newChannelRepository()
      .getChannel(channelId);

  final unreadCount = fetchedChannel.unreadCount ?? 0;
  final isMentioned = fetchedChannel.isMentioned;
  ```
</CodeGroup>

## Observe Total Channel Unread

Use total unread APIs for app-level badges or global chat navigation. The aggregate contains the unread count and whether any unread message mentions the current user.

<Note>
  The total unread count is calculated from the channels the SDK has already synced into its local cache. It is a live observation, not a one-time server fetch, so it starts at `0` and only reflects an accurate total after the channel list has been queried at least once. To show a total unread badge before the chat list screen appears, fetch the channel list first (for example, run a channel query in the background) so the SDK has the data to calculate from, then observe the total unread count.
</Note>

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { ChannelRepository } from '@amityco/ts-sdk';

  const unsubscribe = ChannelRepository.getTotalChannelsUnread(
    ({ data: unread, loading, error }) => {
      if (error) {
        handleError(error);
        return;
      }

      if (!loading && unread) {
        renderResults({
          unreadCount: unread.unreadCount,
          isMentioned: unread.isMentioned,
        });
      }
    },
  );

  unsubscribe();
  ```

  ```swift iOS theme={null}
  var cancellables = Set<AnyCancellable>()

  channelRepository.getTotalChannelsUnread()
      .sink { unread in
          showSuccessMessage([
              "unreadCount": unread.unreadCount,
              "isMentioned": unread.isMentioned
          ])
      }
      .store(in: &cancellables)
  ```

  ```kotlin Android theme={null}
  val disposable = channelRepository
      .getTotalChannelUnread()
      .subscribe(
          { unread ->
              showSuccessMessage(
                  mapOf(
                      "unreadCount" to unread.unreadCount,
                      "isMentioned" to unread.isMentioned,
                  ),
              )
          },
          { error -> handleGeneralError(error) },
      )
  ```

  ```dart Flutter theme={null}
  AmityChatClient.newChannelRepository()
      .getChannelTotalUnreads()
      .listen((unread) {
    final totalUnreadCount = unread.unreadCount;
    final hasMention = unread.isMentioned;
  });
  ```
</CodeGroup>

## Implementation Notes

<CardGroup cols={2}>
  <Card title="Model Source" icon="database">
    Per-channel values come from channel or subchannel models, so update the UI from SDK observations instead of maintaining a separate unread counter.
  </Card>

  <Card title="Cache-Based Total" icon="database">
    Total channel unread is derived from locally synced channels. Fetch the channel list at least once before the count reflects an accurate total.
  </Card>

  <Card title="Mention Priority" icon="at">
    Use `isMentioned` to visually prioritize channels where the current user has unread mentions.
  </Card>

  <Card title="Subchannel Mode" icon="layer-group">
    When your app uses subchannels directly, read subchannel unread fields from the subchannel model where the platform exposes them.
  </Card>

  <Card title="Read Marking" icon="check">
    Mark messages as read from the message model to update unread state.
  </Card>
</CardGroup>

## Related Topics

<CardGroup cols={3}>
  <Card title="Message Read Status" href="./message-read-status" icon="eye">
    Mark messages as read.
  </Card>

  <Card title="Message Receipt Sync" href="./message-receipt-sync" icon="rotate">
    Subscribe to receipt topics while a chat screen is open.
  </Card>

  <Card title="Message Preview" href="/social-plus-sdk/chat/engagement-features/message-preview" icon="message">
    Show latest-message previews beside unread badges.
  </Card>
</CardGroup>