Skip to main content

Setting and Using Conversation Tags

  • The SDK supports conversation tags starting from version 5.1.1, with related interfaces provided exclusively in the RCCoreClient class.
  • Starting from SDK version 5.3.0, it's recommended to use interfaces with asynchronous results, while the original synchronous interfaces are deprecated.
  • Before setting tags for conversations, ensure you've created tag information. See [Managing Tag Information Data] for details.
  • This feature is not applicable to chatrooms or ultra groups.

Each user can create up to 20 tags, with each tag containing a maximum of 1,000 conversations. If a tag already contains 1,000 conversations, adding more conversations to it will still succeed but will result in the earliest tagged conversation being removed from the tag.

Use Case Description​

Conversation tags typically fulfill the need for app users to group conversations. After creating tag information ([RCTagInfo]), app users can assign one or more tags to conversations.

Once tags are set, you can leverage conversation tag data to implement features like grouped retrieval, display, and deletion of conversations. You can also obtain the unread message count for all conversations under a specific tag or pin a conversation within a particular tag.

  • Use Case 1: Tagging each conversation in the conversation list, similar to external groups, department groups, and personal group tags in WeCom's conversation list.
  • Use Case 2: Grouping contacts by tags, similar to family, friends, and colleagues groupings in QQ's contact list.
  • Use Case 3: A combination of the first two use cases, grouping conversation lists by tags, similar to Telegram's conversation list grouping.

Using Tags to Mark Conversations​

After creating tag information ([RCTagInfo]), app users can use tags to mark conversations. The SDK treats the act of tagging a conversation as adding the conversation to a tag.

Supported operations include:

  • Tagging conversations (adding one or more conversations to a specified tag)
  • Removing one or more conversations from a tag
  • Removing one or more tags from a specified conversation

Adding One or More Conversations to a Specified Tag​

The IMLib SDK treats the act of tagging a conversation as adding the conversation to a tag. You can add multiple conversations to a single tag. Only the tagId from [RCTagInfo] needs to be specified when tagging.

Method Prototype​

- (void)addConversationsToTag:(NSString *)tagId
      conversationIdentifiers:(NSArray<RCConversationIdentifier *> *)conversationIdentifiers
                      success:(nullable void (^)(void))successBlock
                        error:(nullable void (^)(RCErrorCode errorCode))errorBlock;

Parameter Description​

ParameterTypeDescription
tagIdNSStringTag ID.
conversationIdentifiersNSArrayConversation list, with array elements being [RCConversationIdentifier].
successBlockBlockSuccess callback.
errorBlockBlockFailure callback. The errorCode parameter returns an [RCErrorCode].

Example Code​

RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];

[[RCCoreClient sharedCoreClient] addConversationsToTag:@"tagId" conversationIdentifiers:@[iden] success:^{

        } error:^(RCErrorCode errorCode) {

        }];

Removing Conversations from a Specified Tag​

You may need to remove one or more conversations from all conversations tagged with a specified tag. For example, removing a private chat with Tom from all conversations tagged as Training Class. The IMLib SDK treats this operation as removing conversations from a specified tag. After successful removal, the conversation still exists but no longer carries the tag.

Interface Prototype​

- (void)removeConversationsFromTag:(NSString *)tagId
           conversationIdentifiers:(NSArray<RCConversationIdentifier *> *)conversationIdentifiers
                           success:(nullable void (^)(void))successBlock
                             error:(nullable void (^)(RCErrorCode errorCode))errorBlock;

Parameter Description​

ParameterTypeDescription
tagIdNSStringTag ID.
conversationIdentifiersNSArrayConversation list, with array elements being [RCConversationIdentifier].
successBlockBlockSuccess callback.
errorBlockBlockFailure callback. The errorCode parameter returns an [RCErrorCode].

Example Code​

RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];

[[RCCoreClient sharedCoreClient] removeConversationsFromTag:@"tagId" conversationIdentifiers:@[iden] success:^{

} error:^(RCErrorCode errorCode) {

}];

Removing Tags from a Specified Conversation​

You can add multiple tags to a specified conversation. The IMLib SDK supports removing one or multiple tags at once. When removing tags, provide a list of tagIds for all [RCTagInfo] to be removed.

Interface Prototype​

- (void)removeTagsFromConversation:(RCConversationIdentifier *)conversationIdentifier
                            tagIds:(NSArray<NSString *> *)tagIds
                           success:(nullable void (^)(void))successBlock
                             error:(nullable void (^)(RCErrorCode errorCode))errorBlock;

Parameter Description​

ParameterTypeDescription
tagIdsNSArrayList of tag IDs.
conversationIdentifiersNSArrayConversation list, with array elements being [RCConversationIdentifier].
successBlockBlockSuccess callback.
errorBlockBlockFailure callback. The errorCode parameter returns an [RCErrorCode].

Example Code​

RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];

[[RCCoreClient sharedCoreClient] removeTagsFromConversation:iden tagIds:@[@"tagId1",@"tagId2"] success:^{

        } error:^(RCErrorCode errorCode) {

        }];

Retrieving All Tags for a Specified Conversation​

You can retrieve all tags associated with a specified conversation. Upon success, the callback returns a list of [RCConversationTagInfo]. Each [RCConversationTagInfo] contains the corresponding tag information [RCTagInfo] and pin status (whether the conversation is pinned among all conversations carrying this tag).

Interface Prototype​

- (void)getTagsFromConversation:(RCConversationIdentifier *)conversationIdentifier
                     completion:(nullable void(^)(NSArray<RCConversationTagInfo *> *_Nullable results))completion;

Parameter Description​

ParameterTypeDescription
conversationIdentifier[RCConversationIdentifier]Conversation identifier, requiring specification of conversation type ([RCConversationType]) and Target ID.
completionBlockAsynchronous callback, returning a list of tag information ([RCConversationTagInfo]).

RCConversationTagInfo Description:

ParameterTypeDescription
tagInfo[RCTagInfo]Tag information.
isTopBOOLWhether the conversation is pinned.

Example Code​

RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];

[[RCCoreClient sharedCoreClient] getTagsFromConversation:iden completion:^(NSArray<RCConversationTagInfo *> *){
        // Asynchronous callback, returning the tag list
        }];

Multi-Device Synchronization of Conversation Tag Modifications​

RC supports multi-device login for the same user account. After setting up the conversation tag change listener conversationTagDelegate, when users add, remove, or edit tags on conversations from other devices, the onConversationTagChanged callback will be triggered, allowing the current device to receive conversation tag modification notifications from other devices. Upon receiving the notification, call the getTagsFromConversation method to fetch the latest tag data for the specified conversation from the RC server.

tip

  • Call this method after initialization but before connection.

  • Modifying tag information on the current device will not trigger this callback method. The server only notifies SDKs on other devices logged in with the same user account to trigger the callback.

Setting the Delegate​

//RCCoreClient.h
@property (nonatomic, weak) id<RCConversationTagDelegate> conversationTagDelegate;
[RCCoreClient sharedCoreClient].conversationTagDelegate = self;

Delegate Method​

@protocol RCConversationTagDelegate <NSObject>
/*!
 Conversation tag changes

 @discussion Adding, deleting, or updating conversation tags on the local device will not trigger this callback method. The related method's block will directly return the result.
 */


- (void)onConversationTagChanged;
@end

Operating on Conversation Data by Tags​

The IMLib SDK supports operations on conversations with specified tags. After app users add tags to conversations, the following operations can be performed:

  • Combined with the [Conversation Pinning] feature, conversations can be pinned within those carrying specified tags

  • Retrieve conversation lists by tag, i.e., all conversations carrying a specified tag

  • Get unread message counts by tag

  • Clear unread message counts for conversations corresponding to a tag

  • Delete conversations corresponding to a tag

Pinning Conversations Within Specified Tags​

You can use conversation tags to categorize and display conversations according to business needs. To pin conversations within the same category (all conversations carrying the same tag), use the conversation pinning feature.

For detailed implementation, refer to [Conversation Pinning]'s Pinning Conversations Under Tags.

Paginated Retrieval of Local Conversation Lists Under Specified Tags​

You can paginate the retrieval of local conversation lists under specified tags, using operationTime as the boundary. This method only fetches data from the local database. Starting from version 5.6.4, the [RCConversation] object returned by this interface includes a new isTopForTag property. If YES, it indicates the conversation is pinned under the current tagId.

Interface Prototype​



- (void)getConversationsFromTagByPage:(NSString *)tagId
                            timestamp:(long long)timestamp
                                count:(int)count
                           completion:(nullable void(^)(NSArray<RCConversation *> *_Nullable results))completion;

Parameter Description​

ParameterTypeDescription
tagIdNSStringTag ID.
timestamplong longConversation timestamp. Retrieves conversation lists before this timestamp. For the first call, pass 0. Subsequent calls can use the sentTime or operationTime property values of the returned [RCConversation] object as the startTime for the next query. operationTime is recommended (this property is only available in version 5.6.8 and later).
countintNumber of items to retrieve. If the actual number of conversations retrieved is less than count, it indicates all data has been fetched.
completionBlockAsynchronous callback, returning the conversation ([RCConversation]) list.

Example Code​

[[RCCoreClient sharedCoreClient] getConversationsFromTagByPage:texts[0] timestamp:0 count:20 completion:^(NSArray<RCConversation *> *){
      //Asynchronous callback, returning the conversation list
}];

Paginated Retrieval of Local Untagged Conversation Lists​

tip

Available starting from version 5.24.0 in RCCoreClient.

You can use the getUntaggedConversationListByPage:count:topPriority:completionHandler: interface to retrieve untagged conversation lists.

Parameter Description​

ParameterTypeDescription
timestamplong longConversation timestamp (retrieves conversation lists before this timestamp, 0 indicates starting from the latest, unit: milliseconds)
countNSIntegerNumber of items to retrieve, valid range [1, 100]. (If the actual number of conversations retrieved is less than count, it indicates all data has been fetched).
topPriorityBOOLSorting method for query results, whether pinned conversations take priority. Pass YES to return pinned conversations first; otherwise, results are sorted only by conversation time.
completionHandlerblockResult callback, conversation list and error code.

Example Code​

[[RCCoreClient sharedCoreClient] getUntaggedConversationListByPage:0 count:10 topPriority:YES completionHandler:^(NSArray<RCConversation *> * _Nonnull conversations, RCErrorCode code) {
    // TODO Business processing
}];

Getting Unread Message Counts by Tag​

You can retrieve the unread message count for all conversations carrying a specified tag.

Interface Prototype​



- (void)getUnreadCountByTag:(NSString *)tagId
             containBlocked:(BOOL)isContain
                 completion:(nullable void(^)(int count))completion;

Parameter Description​

ParameterTypeDescription
tagIdNSStringTag ID.
isContainBOOLWhether to include muted conversations.
completionBlockAsynchronous callback, returning the unread message count for conversations.

Example Code​

[[RCCoreClient sharedCoreClient] getUnreadCountByTag:@"tagId" containBlocked:isBlocked completion:^(int count){
        //Asynchronous callback
}];

Clearing Unread Message Counts for Conversations Corresponding to a Tag​

You can clear the unread message counts for all conversations carrying a specified tag.

Interface Prototype​



- (void)clearMessagesUnreadStatusByTag:(NSString *)tagId
                            completion:(nullable void(^)(BOOL ret))completion;

Parameter Description​

ParameterTypeDescription
tagIdNSStringTag ID.
completionBlockAsynchronous callback, returning whether the clearing was successful.

Example Code​

[[RCCoreClient sharedCoreClient] clearMessagesUnreadStatusByTag:@"tagId" completion:^(BOOL){
        //Asynchronous callback
}];

Deleting Conversations Corresponding to a Tag​

You can delete all conversations under a specified tag, simultaneously removing the binding relationship between these conversations and the tag. After successful deletion, the conversations will no longer carry the specified tag. When these conversations receive new messages, new conversations will be generated.

Interface Prototype​



- (void)clearConversationsByTag:(NSString *)tagId
                         option:(RCClearConversationOption *)option
                        success:(nullable void (^)(void))successBlock
                          error:(nullable void (^)(RCErrorCode errorCode))errorBlock;

Parameter Description​

ParameterTypeDescription
tagIdNSStringTag ID.
optionRCClearConversationOptionConfiguration for clearing conversations.
successBlockBlockSuccess callback.
errorBlockBlockFailure callback. The errorCode parameter returns [RCErrorCode].

Example Code​

RCClearConversationOption *option = [[RCClearConversationOption alloc] init];
option.isDeleteMessage = YES;
[[RCCoreClient sharedCoreClient] clearConversationsByTag:@"tagId" option:option success:^{

} error:^(RCErrorCode errorCode) {

}];

You can configure whether to simultaneously clear the local messages corresponding to these conversations using the isDeleteMessage property of the option parameter.

  • If local messages corresponding to the conversations are not deleted, historical chat records can be viewed when new messages are received.

  • If local messages corresponding to the conversations are deleted, historical chat records cannot be viewed when new messages are received. If the Cloud Storage for One-to-One and Group Messages service is enabled, the server still retains message history. To delete, use the Delete Server Historical Messages API.

Last updated on