Unread Message Count

The unread message count is a default feature provided by IMKit, which informs users of the number of unread messages in each conversation.

The unread count is displayed in the RCConversationCell of the RCConversationListViewController class. For each conversation, the unread count appears in the top-right corner of the conversation icon. If the count exceeds 100, it is displayed as 99+.

tip

To use the unread message count feature, you must first build the conversation list page. By default, IMKit does not implement displaying the unread count in the Tab Bar. For reference, check the SealTalk project (GitHub · Gitee).

Usage

The IMKit SDK has already implemented the logic for fetching and displaying unread message counts by default. When using the default conversation list and chat UI, no additional API calls are required.

IMKit automatically clears the unread count when users enter one-to-one chat, group chat, or system conversation pages. For multi-device login scenarios, IMKit synchronizes the read status across devices. You can disable this feature based on your business needs. For details, see Multi-Device Read Status Sync.

Customization

If the default implementation does not meet your requirements, you can use the relevant APIs in IMKit or IMLib SDK.

Fetch or Clear Unread Count

IMKit does not directly provide APIs for fetching or clearing unread counts. For custom needs, use the IMLib SDK methods. For example:

• Fetch unread counts for all conversations
• Fetch unread counts by conversation type
• Clear unread count for a single conversation

For core classes, APIs, and usage, refer to the IMLib documentation: Handling Unread Message Count.

tip

IMLib methods do not refresh the UI automatically. You need to implement custom notification mechanisms for UI updates based on business requirements.

Display Only a Red Dot

If you want to show only a red dot on the RCConversationCell without the numeric count, override the willDisplayConversationTableCell:atIndexPath: method in RCConversationListViewController and set the isShowNotificationNumber property to NO.

- (void)willDisplayConversationTableCell:(RCConversationBaseCell *)cell atIndexPath:(NSIndexPath *)indexPath {  
    // When new messages arrive, show a numeric badge. Set to NO to display only a red dot.  
    ((RCConversationCell *)cell).isShowNotificationNumber = NO;  
}  

Customize Unread Badge UI

The unread badge UI on the RCConversationCell is controlled by the bubbleTipView property of RCConversationListViewController. Override the willDisplayConversationTableCell:atIndexPath: method to customize it.

Method Prototype

/// Callback before displaying a cell.  
/// - Parameter cell:        The cell to be displayed.  
/// - Parameter indexPath:   The index of the conversation data model in the data source.  
/// You can modify the cell's display properties in this callback.  
- (void)willDisplayConversationTableCell:(RCConversationBaseCell *)cell atIndexPath:(NSIndexPath *)indexPath;  

Parameter Description

Below are some properties of bubbleTipView. For the full list, refer to RCMessageBubbleTipView in the API documentation.

Item	Property	Type	Default Value
Badge Position	bubbleTipAlignment	RCMessageBubbleTipViewAlignment	RC_MESSAGE_BUBBLE_TIP_VIEW_ALIGNMENT_TOP_RIGHT
Badge Text Color	bubbleTipTextColor	UIColor	whiteColor
Badge Background Color	bubbleTipBackgroundColor	UIColor	redColor

Replace Read/Unread Icons with Text

By default, the SDK displays a "checkmark" icon for read text messages. To replace it with Read or Unread text, remove the default icon when the cell is displayed.

For implementation steps, refer to the Customize Message Cell Display section in the Conversation Page documentation.

Multi-Device Read Status Sync

tip

For SDK versions ≤ 5.6.2, read/unread status sync is not supported for system conversations.

In IM scenarios, a user account may be logged in on multiple devices. While RongCloud synchronizes message data across devices when Multi-Device Message Sync is enabled, the read/unread status of messages in conversations is stored locally on each device.

The IMKit SDK enables multi-device read status sync by default. When sync is initiated on one device, other devices receive notifications and sync the status accordingly. You can enable or disable this feature based on business needs. It is enabled by default.

RCKitConfigCenter.message.enableSyncReadStatus = YES;  

Unread Message Bubble Reminder

IMKit supports displaying unread message bubble reminders in the RCConversationViewController.

Display Unread Count Reminder

If a conversation has more than 10 unread messages, a reminder bubble appears in the bottom-right corner when entering the conversation page. Clicking the bubble jumps to the first unread message.

This feature is disabled by default. To enable it, set the enableUnreadMessageIcon property of the RCConversationViewController subclass to YES before entering the conversation page.

@property (nonatomic, assign) BOOL enableUnreadMessageIcon;  

Display Unread Mention Count Reminder

When a conversation receives many messages (more than can fit on one screen) and includes @mentions, an unread @mention count reminder appears in the top-right corner. Clicking it jumps to the earliest unread @mention, and the count decreases by 1. Subsequent clicks reduce the count based on the number of @mentions visible on the screen.

This feature is enabled by default. To disable it, set the enableUnreadMentionedIcon property of the RCConversationViewController subclass to NO before entering the conversation page.

@property (nonatomic, assign) BOOL enableUnreadMentionedIcon;  

Display New Message Reminder

If a user is viewing historical messages and the latest messages are not visible, a reminder (e.g., 15 new messages) appears in the bottom-right corner when new messages arrive. Clicking it scrolls to the latest messages.

This feature is disabled by default. To enable it, set the enableNewComingMessageIcon property of the RCConversationViewController subclass to YES before entering the conversation page.

@property (nonatomic, assign) BOOL enableNewComingMessageIcon;  

Customize Top-Right Bubble Reminder

After enabling the unread message reminder, if a conversation has many unread messages (more than can fit on one screen), a reminder appears in the top-right corner when entering the conversation. Clicking it jumps to the first unread message. You can customize the control.

• UILabel for the reminder:

  Displays the unread count when unReadMessage > 10.

  @property (nonatomic, strong) UILabel *unReadMessageLabel;  

• UIButton for the reminder:

  @property (nonatomic, strong) UIButton *unReadButton;  

• Customization:

  Customize the font color, background image, and arrow of the unread message control. Add the following method to the conversation page subclass, replacing image names as needed.

  - (void)viewWillAppear:(BOOL)animated {  
      [super viewWillAppear:animated];  
  
      // Modify text color  
      [self.unReadMessageLabel setTextColor:[UIColor redColor]];  
  
      // Modify button background image  
      [self.unReadButton setBackgroundImage:[UIImage imageNamed:@"custom_image_name"]  
                                  forState:UIControlStateNormal];  
  
      // Modify arrow image  
      [self.unReadButton.subviews enumerateObjectsUsingBlock:^(__kindof UIView * _Nonnull obj, NSUInteger idx, BOOL * _Nonnull stop) {  
          if ([obj isKindOfClass:[UIImageView class]]) {  
              UIImageView *imageView = (UIImageView *)obj;  
              UIImage *image = [UIImage imageNamed:@"custom_arrow_image"];  
              image = [image resizableImageWithCapInsets:UIEdgeInsetsMake(image.size.width * 0.2, image.size.width * 0.8,  
                                                                        image.size.width * 0.2, image.size.width * 0.2)  
                                          resizingMode:UIImageResizingModeStretch];  
              imageView.image = image;  
              *stop = YES;  
          }  
      }];  
  }  

Customize Bottom-Right Bubble Reminder

When the new message reminder is enabled and the user scrolls away from the latest messages, a reminder (e.g., 15 new messages) appears in the bottom-right corner when new messages arrive. Clicking it scrolls to the latest messages.

• UILabel for the reminder:

  @property (nonatomic, strong) UILabel *unReadNewMessageLabel;  

• Customization:

  Customize the font color and other properties of the new message reminder:

  - (void)viewWillAppear:(BOOL)animated {  
      [super viewWillAppear:animated];  
      // Modify text color  
      [self.unReadNewMessageLabel setTextColor:[UIColor redColor]];  
  }