Setting and Using Conversation Tags
- SDK version 5.6.11 and above supports the conversation tag feature.
- Before setting tags for conversations, ensure that 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, with each tag containing a maximum of 1,000 conversations. If a tag already has 1,000 conversations, adding more conversations to the tag 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 (RCIMIWTagInfo), app users can set one or more tags for a conversation.
Once tags are set, the tag data can be used to implement features such as grouping, displaying, and deleting conversations. It is also possible to retrieve the unread message count for all conversations under a specific tag or pin a conversation within a particular tag.
- Scenario 1: Tagging each conversation in the conversation list, similar to external groups, department groups, and personal groups in the conversation list of Enterprise WeChat.
- Scenario 2: Grouping contacts in the address book based on tags, similar to family, friends, and colleagues in the QQ contact list.
- Scenario 3: Combining the first two scenarios, grouping the conversation list by tags, similar to the conversation list grouping in Telegram.
After creating tag information (RCIMIWTagInfo), app users can use tags to mark conversations. The SDK considers the act of tagging a conversation as adding the conversation to a tag.
The following operations are supported:
- Tagging conversations, 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 RCIMIWTagInfo needs to be passed when specifying the tag.
Method
Future<int> addConversationToTag(String tagId, RCIMIWConversationType type, String targetId, {IRCIMIWAddConversationToTagCallback? callback});
Parameter Description
| Parameter | Type | Description |
|---|
| tagId | String | The unique identifier of the tag, a string of no more than 10 characters. |
| type | RCIMIWConversationType | The type of conversation. |
| targetId | String | The conversation ID. |
| callback | IRCIMIWAddConversationToTagCallback | The event callback. |
Return Value
| Return Value | Description |
|---|
| Future<int> | The status code of the current operation. 0 indicates success, and the specific result needs to be implemented in the callback; non-zero indicates that the current operation failed, and the callback will not be triggered. Refer to the error codes for detailed errors. |
Code Example
IRCIMIWAddConversationToTagCallback? callback = IRCIMIWAddConversationToTagCallback(onConversationToTagAdded: (int? code) {
});
int? ret = await engine?.addConversationToTag(tagId, type, targetId, callback:callback);
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 the conversation from the specified tag. After successful removal, the conversation still exists but no longer carries the tag.
Method
Future<int> removeConversationFromTag(String tagId, RCIMIWConversationType type, String targetId, {IRCIMIWRemoveConversationFromTagCallback? callback});
Parameter Description
| Parameter | Type | Description |
|---|
| tagId | String | The unique identifier of the tag, a string of no more than 10 characters. |
| type | RCIMIWConversationType | The type of conversation. |
| targetId | String | The conversation ID. |
| callback | IRCIMIWRemoveConversationFromTagCallback | The event callback. |
Return Value
| Return Value | Description |
|---|
| Future<int> | The status code of the current operation. 0 indicates success, and the specific result needs to be implemented in the callback; non-zero indicates that the current operation failed, and the callback will not be triggered. Refer to the error codes for detailed errors. |
Code Example
IRCIMIWRemoveConversationFromTagCallback? callback = IRCIMIWRemoveConversationFromTagCallback(onConversationFromTagRemoved: (int? code) {
});
int? ret = await engine?.removeConversationFromTag(tagId, type, targetId, callback:callback);
App users may have added multiple tags to a specific conversation. The SDK supports removing one or more tags at a time. When removing, pass a list of tagIds from all RCIMIWTagInfos to be removed.
Method
Future<int> removeTagsFromConversation(RCIMIWConversationType type, String targetId, List<String> tagIds, {IRCIMIWRemoveTagsFromConversationCallback? callback});
Parameter Description
| Parameter | Type | Description |
|---|
| type | RCIMIWConversationType | The type of conversation. |
| targetId | String | The conversation ID. |
| tagIds | List<String> | The collection of tags. |
| callback | IRCIMIWRemoveTagsFromConversationCallback | The event callback. |
Return Value
| Return Value | Description |
|---|
| Future<int> | The status code of the current operation. 0 indicates success, and the specific result needs to be implemented in the callback; non-zero indicates that the current operation failed, and the callback will not be triggered. Refer to the error codes for detailed errors. |
Code Example
IRCIMIWRemoveTagsFromConversationCallback? callback = IRCIMIWRemoveTagsFromConversationCallback(onTagsFromConversationRemoved: (int? code) {
});
int? ret = await engine?.removeTagsFromConversation(type, targetId, tagIds, callback:callback);
Retrieve all tags associated with a specified conversation. Upon success, the callback returns a list of RCConversationTagInfo. Each RCConversationTagInfo contains the corresponding tag information RCIMIWTagInfo and the pin status (whether the conversation is pinned among all conversations carrying the tag information).
Method
Future<int> getTagsFromConversation(RCIMIWConversationType type, String targetId, {IRCIMIWGetTagsFromConversationCallback? callback});
Parameter Description
| Parameter | Type | Description |
|---|
| type | RCIMIWConversationType | The type of conversation. |
| targetId | String | The conversation ID. |
| callback | IRCIMIWGetTagsFromConversationCallback | The event callback. |
Return Value
| Return Value | Description |
|---|
| Future<int> | The status code of the current operation. 0 indicates success, and the specific result needs to be implemented in the callback; non-zero indicates that the current operation failed, and the callback will not be triggered. Refer to the error codes for detailed errors. |
Code Example
IRCIMIWGetTagsFromConversationCallback? callback = IRCIMIWGetTagsFromConversationCallback(onSuccess: (List<RCIMIWConversationTagInfo>? t) {
}, onError: (int? code) {
});
int? ret = await engine?.getTagsFromConversation(type, targetId, callback:callback);
Operating Conversation Data by Tag
The SDK supports operations on conversations carrying a specified tag. After app users add tags to conversations, the following operations can be performed:
- Combined with the [Conversation Pinning] feature, conversations can be pinned within the set of conversations carrying a specified tag.
- Retrieve the conversation list by tag, i.e., retrieve all conversations carrying a specified tag.
- Retrieve the unread message count by tag.
- Clear the unread message count for conversations corresponding to a tag.
- Delete conversations corresponding to a tag.
Pinning Conversations Within a Specified Tag
Apps can use conversation tags to categorize and display conversations according to business needs. If you need to pin a conversation within a category of conversations (all conversations carrying the same tag), you can use the conversation pinning feature.
Method
Future<int> changeConversationTopStatusInTag(String tagId, RCIMIWConversationType type, String targetId, bool top, {IRCIMIWChangeConversationTopStatusInTagCallback? callback});
Parameter Description
| Parameter | Type | Description |
|---|
| tagId | String | The unique identifier of the tag, a string of no more than 10 characters. |
| type | RCIMIWConversationType | The type of conversation. |
| targetId | String | The conversation ID. |
| top | bool | Whether to pin the conversation. |
| callback | IRCIMIWChangeConversationTopStatusInTagCallback | The event callback. |
Return Value
| Return Value | Description |
|---|
| Future<int> | The status code of the current operation. 0 indicates success, and the specific result needs to be implemented in the callback; non-zero indicates that the current operation failed, and the callback will not be triggered. Refer to the error codes for detailed errors. |
Code Example
IRCIMIWChangeConversationTopStatusInTagCallback? callback = IRCIMIWChangeConversationTopStatusInTagCallback(onConversationTopStatusInTagChanged: (int? code) {
});
int? ret = await engine?.changeConversationTopStatusInTag(tagId, type, targetId, top, callback:callback);
Paginated Retrieval of Local Conversations Under a Specified Tag
Retrieve the local conversation list under a specified tag in paginated form, using the timestamp of the last message in the conversation as the boundary.
Method
Future<int> getConversationsFromTagByPage(String tagId, int timestamp, int count, {IRCIMIWGetConversationsCallback? callback});
Parameter Description
| Parameter | Type | Description |
|---|
| tagId | String | The unique identifier of the tag, a string of no more than 10 characters. |
| timestamp | int | The timestamp of the conversation. Retrieve the conversation list before this timestamp. For the first query, you can pass 0. For subsequent queries, use the operationTime property value of the returned RCConversation object as the startTime. |
| count | int | The number of conversations to retrieve. If the actual number of conversations retrieved is less than count, it indicates that all data has been retrieved. |
| callback | IRCIMIWGetConversationsCallback | The event callback. |
Return Value
| Return Value | Description |
|---|
| Future<int> | The status code of the current operation. 0 indicates success, and the specific result needs to be implemented in the callback; non-zero indicates that the current operation failed, and the callback will not be triggered. Refer to the error codes for detailed errors. |
Code Example
IRCIMIWGetConversationsCallback? callback = IRCIMIWGetConversationsCallback(onSuccess: (List<RCIMIWConversation>? t) {
}, onError: (int? code) {
});
int? ret = await engine?.getConversationsFromTagByPage(tagId, timestamp, count, callback:callback);
Retrieving Unread Message Count by Tag
Retrieve the unread message count for all conversations carrying a specified tag.
Method
Future<int> getUnreadCountByTag(String tagId, bool contain, {IRCIMIWGetUnreadCountCallback? callback});
Parameter Description
| Parameter | Type | Description |
|---|
| tagId | String | The unique identifier of the tag, a string of no more than 10 characters. |
| contain | bool | Whether to include conversations with Do Not Disturb enabled. |
| callback | IRCIMIWGetUnreadCountCallback | The event callback. |
Return Value
| Return Value | Description |
|---|
| Future<int> | The status code of the current operation. 0 indicates success, and the specific result needs to be implemented in the callback; non-zero indicates that the current operation failed, and the callback will not be triggered. Refer to the error codes for detailed errors. |
Code Example
IRCIMIWGetUnreadCountCallback? callback = IRCIMIWGetUnreadCountCallback(onSuccess: (int? t) {
}, onError: (int? code) {
});
int? ret = await engine?.getUnreadCountByTag(tagId, contain, callback:callback);
Clearing Unread Message Count for Conversations Corresponding to a Tag
Clear the unread message count for all conversations carrying a specified tag.
Method
Future<int> clearMessagesUnreadStatusByTag(String tagId, {IRCIMIWClearMessagesUnreadStatusByTagCallback? callback});
Parameter Description
| Parameter | Type | Description |
|---|
| tagId | String | The unique identifier of the tag, a string of no more than 10 characters. |
| callback | IRCIMIWClearMessagesUnreadStatusByTagCallback | The event callback. |
Return Value
| Return Value | Description |
|---|
| Future<int> | The status code of the current operation. 0 indicates success, and the specific result needs to be implemented in the callback; non-zero indicates that the current operation failed, and the callback will not be triggered. Refer to the error codes for detailed errors. |
Code Example
IRCIMIWClearMessagesUnreadStatusByTagCallback? callback = IRCIMIWClearMessagesUnreadStatusByTagCallback(onSuccess: (bool? t) {
}, onError: (int? code) {
});
int? ret = await engine?.clearMessagesUnreadStatusByTag(tagId, callback:callback);
Deleting Conversations Corresponding to a Tag
Delete all conversations under a specified tag, while also unbinding 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.
Method
Future<int> clearConversationsByTag(String tagId, bool deleteMessage, {IRCIMIWClearConversationsByTagCallback? callback});
Parameter Description
| Parameter | Type | Description |
|---|
| tagId | String | The unique identifier of the tag, a string of no more than 10 characters. |
| deleteMessage | bool | Whether to delete messages. |
| callback | IRCIMIWClearConversationsByTagCallback | The event callback. |
Return Value
| Return Value | Description |
|---|
| Future<int> | The status code of the current operation. 0 indicates success, and the specific result needs to be implemented in the callback; non-zero indicates that the current operation failed, and the callback will not be triggered. Refer to the error codes for detailed errors. |
Code Example
IRCIMIWClearConversationsByTagCallback? callback = IRCIMIWClearConversationsByTagCallback(onSuccess: (bool? t) {
}, onError: (int? code) {
});
int? ret = await engine?.clearConversationsByTag(tagId, deleteMessage, callback:callback);
You can configure whether to simultaneously clear the local messages corresponding to these conversations using the deleteMessage 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 message history is still stored on the server. If deletion is required, use the Delete Server-Side Historical Messages API.