Setting and Using Conversation Tags
- The SDK supports the conversation tag feature starting from version 5.1.1, and the related interfaces are only available in
RCCoreClient.- Before setting tags for a conversation, ensure that the tag information has been created. For details, see Managing Tag Information Data.
- This feature is not applicable to chatrooms and ultra groups.
Each user can create up to 20 tags, and each tag can contain up to 1000 conversations. If a tag already contains 1000 conversations, adding more conversations to it will still succeed, but the earliest tagged conversation will be removed from the tag.
Scenario Description
Conversation tags are often used to meet the need for grouping conversations in an app. After creating tag information (RCTagInfo), app users can set one or more tags for a conversation.
Once tags are set, the tag data of conversations can be used to implement features such as grouped retrieval, display, and deletion of conversations. Additionally, you can retrieve the total unread message count for all conversations under a specific tag or pin a conversation within a specific tag.
- Scenario 1: Tagging each conversation in the conversation list, similar to the external group, department group, and personal group tags in the WeCom conversation list.
- Scenario 2: Grouping the address book by tags, similar to the family, friends, and colleagues groups in the QQ friends list.
- Scenario 3: A combination of the first two scenarios, grouping the conversation list by tags, similar to the conversation list grouping in Telegram.
Tagging Conversations
After creating tag information (RCTagInfo), app users can tag conversations. The SDK considers the act of tagging a conversation as adding the conversation to a tag.
The following operations are supported:
- Tagging a conversation, i.e., 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 SDK considers 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 passed in when specifying the tag.
RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];
[[RCCoreClient sharedCoreClient] addConversationsToTag:@"tagId" conversationIdentifiers:@[iden] success:^{
} error:^(RCErrorCode errorCode) {
}];
| Parameter | Type | Description |
|---|---|---|
| tagId | NSString | The tag ID. |
| conversationIdentifiers | NSArray | The list of conversations, where each element is an RCConversationIdentifier. |
| successBlock | Block | The success callback. |
| errorBlock | Block | The failure callback. The errorCode parameter returns an RCErrorCode. |
Removing Conversations from a Specified Tag
App users may need to remove one or more conversations from all conversations tagged with a specific tag. For example, removing the private chat with "Tom" from all conversations tagged with "Training Class." The SDK considers this operation as removing conversations from a specified tag. After successful removal, the conversations still exist but no longer carry the tag.
RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];
[[RCCoreClient sharedCoreClient] removeConversationsFromTag:@"tagId" conversationIdentifiers:@[iden] success:^{
} error:^(RCErrorCode errorCode) {
}];
| Parameter | Type | Description |
|---|---|---|
| tagId | NSString | The tag ID. |
| conversationIdentifiers | NSArray | The list of conversations, where each element is an RCConversationIdentifier. |
| successBlock | Block | The success callback. |
| errorBlock | Block | The failure callback. The errorCode parameter returns an RCErrorCode. |
Removing Tags from a Specified Conversation
App users may have added multiple tags to a specified conversation. The SDK supports removing one or more tags at a time. When removing tags, pass in the tagId list of all RCTagInfo to be removed.
RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];
[[RCCoreClient sharedCoreClient] removeTagsFromConversation:iden tagIds:@[@"tagId1",@"tagId2"] success:^{
} error:^(RCErrorCode errorCode) {
}];
| Parameter | Type | Description |
|---|---|---|
| tagIds | NSArray | The list of tag IDs. |
| conversationIdentifiers | NSArray | The list of conversations, where each element is an RCConversationIdentifier. |
| successBlock | Block | The success callback. |
| errorBlock | Block | The failure callback. The errorCode parameter returns an RCErrorCode. |
Retrieving All Tags of a Specified Conversation
Starting from version 5.3.0 of RCCoreClient, it is recommended to use the asynchronous interface below, and the original synchronous interface is deprecated.
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 the pin status (whether the conversation is pinned among all conversations carrying this tag).
RCConversationIdentifier *iden = [[RCConversationIdentifier alloc] initWithConversationIdentifier:ConversationType_PRIVATE targetId:@"targetId"];
[[RCCoreClient sharedCoreClient] getTagsFromConversation:iden completion:^(NSArray<RCConversationTagInfo *> *){
//Asynchronous callback, returns the tag list
}];
| Parameter | Type | Description |
|---|---|---|
| conversationIdentifier | RCConversationIdentifier | The conversation identifier, which requires specifying the conversation type (RCConversationType) and Target ID. |
| completion | Block | The asynchronous callback, returning a list of tag information (RCConversationTagInfo). |
RCConversationTagInfo Description:
| Parameter | Type | Description |
|---|---|---|
| tagInfo | RCTagInfo | The tag information. |
| isTop | BOOL | Whether the conversation is pinned. |
Multi-Device Synchronization of Conversation Tag Modifications
Instant Messaging supports multi-device login for the same user account. If your app user modifies conversation tags on the current device, the SDK will notify the user's other devices. Upon receiving the notification, other devices can call getTagsFromConversation to retrieve the latest tag data for the specified conversation from the RC server.
After setting the delegate, the current device can receive conversation tag modification notifications from other devices.
- Call this method after initialization but before connection.
- Modifying tag information on the current device will not trigger this callback method. The server will only notify the SDK to trigger the callback on other devices logged in with the same user account.
Setting the Delegate
//RCCoreClient.h
@property (nonatomic, weak) id<RCConversationTagDelegate> conversationTagDelegate;
Delegate Method
@protocol RCConversationTagDelegate <NSObject>
/*!
Conversation tag changes
@discussion Adding, removing, or updating conversation tags on the local device will not trigger this callback method. The callback will be directly triggered in the block of the related method.
*/
- (void)onConversationTagChanged;
@end
When the app user adds, removes, or edits tags on conversations from another device, the SDK will trigger the onConversationTagChanged callback. Upon receiving the notification, call getTagsFromConversation to retrieve the latest tag data for the specified conversation from the RC server.
Operating on Conversation Data by Tag
The SDK supports operations on conversations tagged with a specific tag. After app users add tags to conversations, the following operations can be performed:
- Using the Conversation Pin feature, you can pin a conversation among all conversations tagged with a specific tag
- Retrieve the conversation list by tag, i.e., retrieve all conversations tagged with a specific tag
- Retrieve the unread message count by tag
- Clear the unread message count for conversations tagged with a specific tag
- Delete conversations tagged with a specific tag
Pinning a Conversation Among Conversations Tagged with a Specific Tag
Apps can use conversation tags to classify and display conversations according to business needs. If you need to pin a conversation for display within a category of conversations (all conversations tagged with the same tag), you can use the conversation pin feature.
For detailed implementation, refer to Conversation Pin's Pinning a Conversation Under a Tag.
Paginated Retrieval of Local Conversations Tagged with a Specific Tag
Starting from version 5.3.0 of RCCoreClient, it is recommended to use the asynchronous interface below, and the original synchronous interface is deprecated.
Paginated retrieval of local conversations tagged with a specific tag, bounded by the timestamp of the last message in the conversation. This method only retrieves 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 that the conversation is pinned under the current tagId.
[[RCCoreClient sharedCoreClient] getConversationsFromTagByPage:texts[0] timestamp:0 count:20 completion:^(NSArray<RCConversation *> *){
//Asynchronous callback, returns the conversation list
}];
| Parameter | Type | Description |
|---|---|---|
| tagId | NSString | The tag ID. |
| timestamp | long long | The timestamp of the conversation. Retrieves the conversation list before this timestamp. For the first call, you can pass 0. For subsequent calls, you can use the sentTime or operationTime property value of the returned RCConversation object as the startTime for the next query. It is recommended to use operationTime (this property is only available in version 5.6.8 and later). |
| count | int | The number of conversations to retrieve. If the number of conversations retrieved is less than the count value, it indicates that all data has been retrieved. |
| completion | Block | The asynchronous callback, returning a list of conversations (RCConversation). |
Retrieving Unread Message Count by Tag
Starting from version 5.3.0 of RCCoreClient, it is recommended to use the asynchronous interface below, and the original synchronous interface is deprecated.
Retrieve the total unread message count for all conversations tagged with a specific tag.
[[RCCoreClient sharedCoreClient] getUnreadCountByTag:@"tagId" containBlocked:isBlocked completion:^(int count){
//Asynchronous callback
}];
| Parameter | Type | Description |
|---|---|---|
| tagId | NSString | The tag ID. |
| isContain | BOOL | Whether to include muted conversations. |
| completion | Block | The asynchronous callback, returning the unread message count. |
Clearing Unread Message Count for Conversations Tagged with a Specific Tag
- This feature is supported starting from version 5.1.5.
- Starting from version 5.3.0 of
RCCoreClient, it is recommended to use the asynchronous interface below, and the original synchronous interface is deprecated.
Clear the unread message count for all conversations tagged with a specific tag.
[[RCCoreClient sharedCoreClient] clearMessagesUnreadStatusByTag:@"tagId" completion:^(BOOL){
//Asynchronous callback
}];
| Parameter | Type | Description |
|---|---|---|
| tagId | NSString | The tag ID. |
| completion | Block | The asynchronous callback, returning whether the clearing was successful. |
Deleting Conversations Tagged with a Specific Tag
- This feature is supported starting from version 5.1.5.
- Starting from version 5.3.0 of
RCCoreClient, it is recommended to use the asynchronous interface below, and the original synchronous interface is deprecated.
Delete all conversations tagged with a specific tag and unbind these conversations from the tag. After successful deletion, the conversations no longer carry the specified tag. When these conversations receive new messages, new conversations will be created.
RCClearConversationOption *option = [[RCClearConversationOption alloc] init];
option.isDeleteMessage = YES;
[[RCCoreClient sharedCoreClient] clearConversationsByTag:@"tagId" option:option success:^{
} error:^(RCErrorCode errorCode) {
}];
| Parameter | Type | Description |
|---|---|---|
| tagId | NSString | The tag ID. |
| option | RCClearConversationOption | The configuration for clearing conversations. |
| successBlock | Block | The success callback. |
| errorBlock | Block | The failure callback. The errorCode parameter returns an RCErrorCode. |
You can configure whether to simultaneously clear the local messages corresponding to these conversations using the isDeleteMessage property of the option parameter.
- If the local messages corresponding to the conversations are not deleted, historical chat records can be viewed when new messages are received.
- If the 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 the message history. If you need to delete it, use the Delete Server History Messages API.