Chat UIKit iOS UIKit v3
Chat UIKit iOS UIKit
Chat UIKit
iOS UIKit
Version 3

Mention

Copy link

Mention is a feature that allows users to call out each other in a message within a group channel. Users can mention other members in the group channel to get their attention and directly notify that they've been mentioned in a message.


Limitations

Copy link

The mention feature currently has the following limitations:

  • Mention is available for group channels only.
  • User is the only mention type that Sendbird UIKit provides.
  • Users can only mention other users in the same channel.
  • Users can have up to 10 mentions in a single message.

How to use

Copy link

To turn on the feature, refer to the code below:

SBUGlobals.isUserMentionEnabled = true

Configure mention settings

Copy link

The mention feature has basic settings that you can customize when implementing it in your client app. Once isUserMentionEnabled is set to true, a new SBUUserMentionConfiguration instance is created. userMentionConfig, a property in the SBUGlobals class, must be set to the SBUUserMentionConfiguration instance in order to use the feature. The following customizable properties of SBUUserMentionConfiguration should also be configured prior to mentioning users in a channel.

SBUUserMentionConfiguration

Copy link
PropertyTypeDescription

mentionLimit

Int

Specifies the maximum number of times users can mention another user in a single message. (Default: 10)

suggestionLimit

Int

Specifies the maximum number of users shown in a suggested mention list. (Default: 15)

The maximum number of times you can mention the same user or multiple users in one message is 10. The maximum number of users shown in a suggested mention list is set to 15 by default. These numbers are customizable through userMentionConfig, which contains mentionLimit and suggestionLimit properties.

let customConfig = SBUUserMentionConfiguration()
customConfig.mentionLimit = 5
customConfig.suggestionLimit = 3
SBUGlobals.userMentionConfig = customConfig

Mention a user

Copy link

Users can mention other users in the same channel by either searching for the channel member or typing in the user's nickname. When a user types @ in the inputComponent of SBUGroupChannelViewController, a suggested mention list appears in the listComponent of the group channel view. The SBUSuggestedMentionList class contains a scrollable list of suggested channel members by their nickname or user ID. The list also appears while the user types the nickname of a channel member. As the nickname is being typed, the list sorts the nicknames in an alphabetical order in real-time.

Suggested mention list

Copy link

The suggested mention list shows an alphabetical list of all channel members that you can mention in a message. For each member in the list, the profile image, nickname, and user ID are shown by default. You can choose to display either just the nickname or both nickname and user ID. The suggested mention list disappears once a user has been successfully mentioned in a message or when there's no matching nickname found in the list. If there's a typo while typing in a user's nickname or if the user's not a member of the current group channel, the mention list also disappears.

If a user reaches the value of mentionLimit, a warning guide appears in the suggested mention list view. To show the guide, the isLimitGuideEnabled property of SBUSuggestedMentionList must be set to true. Then the customizable limitGuideCell of the guide is displayed in the suggested mention list view.

Customize the UI of limit guide

Copy link

The following tables show customizable properties and method used to modify the UI of the limit guide in the suggested mention list view.

SBUSuggestedMentionList

Copy link
Property nameTypeDescription

limitGuideCell

UITableViewCell

Specifies the UI displaying the limit guide cell in the suggested mention list view.

MethodTypeDescription

isLimitGuideEnabled

Bool

Determines whether to turn on the guide that appears when a user reaches the set value of mentionLimit.

SBUMentionLimitGuideCell

Copy link
Property nameTypeDescription

limitGuideLabel

UILabel

Specifies the UILabel displaying a text that indicates a user has reached the set value of mentionLimit.

Mention input

Copy link

When you type @ and a user nickname in the inputComponent of SBUGroupChannelViewController, the suggested mention list appears. While the list can display both nickname and user ID, you can only type nicknames in the message input field to mention a user. The same user can be mentioned up to 10 times per message by default and the text of each user mention is bolded.

To display the suggested mention list view, SBUSuggestedMentionList uses SBUChannelTheme and SBUUserCellTheme. The following table shows customizable theme properties of SBUChannelTheme and SBUUserCellTheme.

SBUChannelTheme

Copy link
CategoryPropertyDescription

Channel

mentionLimitGuideTextFont

The text font of the limit guide. (Default: SBUFontSet.body1)

Channel

mentionLimitGuideTextColor

The text color of the limit guide. (Default: SBUColorSet.onlight02)

Channel

separatorColor

The color of the line that separates the suggested mention list from the listComponent. (Default: SBUColorSet.onlight04)

SBUUserCellTheme

Copy link
CategoryPropertyDescription

User cell

nicknameTextFont

The text font of the user nickname in the suggested mention list. (Default: SBUFontSet.subtitle2)

User cell

nicknameTextColor

The text color of the user nickname in the suggested mention list. (Default: SBUColorSet.onlight01)

User cell

nonameTextColor

The text color of a mentioned user who doesn't have a nickname. (Default: SBUColorSet.onlight03)

User cell

userIdTextFont

The text font of the user's user ID in the suggested mention list. (Default: SBUFontSet.body3)

User cell

userIdTextColor

The text color of the user's user ID in the suggested mention list. (Default: SBUColorSet.onlight02)

The SBUMessageInputView class uses SBUMessageInputTheme to customize the UI of the user mentions in the message input field. The following table shows theme properties of SBUMessageInputTheme.

SBUMessageInputTheme

Copy link
CategoryPropertyDescription

Message input

mentionTextFont

The text font of the mentioned user. (Default: SBUFontSet.body2)

Message input

mentionTextColor

The text color of the mentioned user. (Default: SBUColorSet.onlight01)

Message input

mentionTextBackgroundColor

The background color of the mentioned user. (Default: UIColor.clear)

Customize SBUStringSet

Copy link

The following table shows a customizable property of SBUStringSet that appears in the suggested mention list view. The SBUStringSet class is a set of strings used to compose a view. You need to modify the stringSet values in advance if you wish to make changes to the view.

Property nameDescription

Mention.Limit_Guide

A text in the limitGuideLabel that indicates a user has reached the maximum number of mentions they can make in a single message.

Customize SBUIconSet

Copy link

The following table shows a customizable icon in the suggested mention list view.

IconImageDescription

iconInfo

An icon used to indicate that the user has reached the maximum mention count in a single message.


Receive a mention

Copy link

When a user is mentioned in a message, the unread message count in the listComponent of SBUGroupChannelListViewController increases by the number of unread mentioned messages. A mention badge also appears to the left of the unread message count number to indicate that the user has been mentioned in one of the unread messages. Regardless of the number of unread mentioned messages, if there's at least one unread mentioned message in the channel, the mention badge appears in the channel list.

When the most recently sent message in a channel mentions the current user, the unread mentioned message is displayed in the channel list view through the unreadMentionLabel property of SBUGroupChannelCell.

Once the user taps on the channel with the unread mentioned message, they can see all the messages in the listComponent of SBUGroupChannelViewController where the highlighted user's nickname appears. The nickname is highlighted only in messages that mention the current user.

Customize the UI of unread mentioned message

Copy link

The following table shows a customizable property used to modify the UI of the unread mentioned message in a channel list view.

SBUGroupChannelCell

Copy link
Property nameTypeDescription

unreadMentionLabel

UILabel

Specifies the UILabel displaying the unread mentioned message and the mention badge.

User profile

Copy link

Users can tap on each mentioned nickname in a message to see the user profile of the mentioned channel member. The user profile includes a profile image, nickname, and user ID.

To display the unread mentioned message in a channel cell, the channel list view uses SBUChannelCellTheme. The following table shows customizable theme properties of SBUChannelCellTheme.

SBUChannelCellTheme

Copy link
CategoryPropertyDescription

Channel cell

unreadMentionTextFont

The text font of the unread mentioned message. (Default: SBUFontSet.h3)

Channel cell

unreadMentionTextColor

The text color of the unread mentioned message. (Default: SBUColorSet.primary300)

To display the user mention in a message cell, the group channel view uses SBUMessageCellTheme. The following table shows customizable theme properties of SBUMessageCellTheme.

SBUMessageCellTheme

Copy link
CategoryPropertyDescription

Message cell

mentionTextFont

The text font of the user mention. (Default: SBUFontSet.body4)

Message cell

mentionLeftTextColor

The text color of the user mention in messages sent by other channel members. (Default: SBUColorSet.onlight01)

Message cell

mentionRightTextColor

The text color of the user mention in messages sent by the current user. (Default: SBUColorSet.ondark01)

Message cell

mentionLeftTextBackgroundColor

The background color of the user mention in messages sent by other channel members. (Default: UIColor.clear)

Message cell

mentionRightTextBackgroundColor

The background color of the user mention in messages sent by the current user. (Default: UIColor.clear)


Push notifications for mentions

Copy link

The option to turn on notifications for mentions only has been added to the listComponent of SBUGroupChannelSettingsViewController. If you turn on push notifications for the channel using the toggle button, two options will appear below: all new messages and mentions only. All new messages include notifications for both non-mentioned messages and mentioned messages, whereas mentions only refer to notifications for just mentioned messages.

Customize SBUStringSet

Copy link

The following table shows a customizable property of SBUStringSet that appears in the notification settings menu. The SBUStringSet class is a set of strings used to compose a view. You need to modify the stringSet values in advance if you wish to make changes to the view.

Property nameDescription

ChannelSettings_Notifications_Mentions_Only

A text indicating the current notification settings for the channel. The string is set to Mentions only by default.

ChannelPushSettings_Notification_Title

A text indicating that the toggle button refers to push notifications. The string is set to Notifications by default.

ChannelPushSettings_Notification_Description

A text indicating that turning on the toggle button allows the user to to be notified when messages are delivered to the channel. The string is set to Turn on to receive notifications when messages are delivered to this channel. by default.

ChannelPushSettings_Item_All

A text indicating that if this radio button is selected, the user will receive notifications for all messages sent to the channel. The string is set to All new messages by default.

ChannelPushSettings_Item_Mentions_Only

A text indicating that if this radio button is selected, the user will receive notifications for mentions only. The string is set to Mentions only by default.

Customize SBUIconSet

Copy link

The following table shows a customizable icon in the notification settings menu.

IconImageDescription

iconRadioButtonOn

An icon used to indicate that either All new messages or Mentions only is turned on for receiving push notifications.

iconRadioButtonOff

An icon used to indicate that either All new messages or Mentions only is turned off for receiving push notifications.