logo
In-app Chat
SDK Error Codes
Powered Byspreading
On this page

Mark conversations


Introduction

When users need to focus on a conversation or can not deal with a conversation at the moment, you can mark the conversation for later processing, such as "starring a conversation," "collapsing a conversation," "hiding a conversation," "marking a conversation as unread," etc. You can achieve this by calling the setConversationMark interface.

Note

When a user marks a conversation, the SDK simply records the mark value of the conversation without changing the underlying logic of the conversation.

Set conversation marks

ZIM supports you in implementing conversation marking operations using either client API or server API.

Client API

1 Listen for conversationChanged

After a user logs into the ZIM SDK, they can register to listen for the onConversationChanged callback interface , to receive notifications of changes in conversation markings.

When the conversation marks are changed, all of the user's online devices will receive a onConversationChanged event notification. From this, the current marks of the conversation can be obtained from the conversation.marks field.

Untitled
// Register the SDK event notification callback
ZIMEventHandler.onConversationChanged = (ZIM zim, List<ZIMConversationChangeInfo> conversationChangeInfoList){
    for (ZIMConversationChangeInfo conversationChangeInfo in conversationChangeInfoList) {
        // Get all the marks of this conversation from conversationChangeInfo.conversation.marks
    }
};
1
Copied!

2 Set or cancel marks

You simply need to call the setConversationMark interface to set or cancel marks for up to 100 conversations (only supports one-on-one chats or group chats). Each conversation can have up to 20 marks.

Untitled
// For example, setting a mark with type 1 for a group chat conversation
int markType = 1;
bool enable = true;
List<ZIMConversationBaseInfo> convList = [];
ZIMConversationBaseInfo conversationBaseInfo = ZIMConversationBaseInfo();
conversationBaseInfo.conversationID = "GroupConv";
conversationBaseInfo.conversationType = ZIMConversationType.group;
convList.add(conversationBaseInfo);
ZIM.getInstance()?.setConversationMark(markType, enable, convList).then((value) {
        // Operation successful
        // Note: Even some of the operations succeeded, some of them failed, errorCode still will be success, and the SDK will return the failed conversations in failedConversationInfos     }).catchError((onError){
        if(onError is PlatformException){
            // Codes for all operation failures 
        }
});
1
Copied!

Server API

Developers can set or cancel conversation marks for multiple users in batches by calling the server-side API. For details, please refer to the server API documentation Mark Conversations.

Query conversation list by marks

When calling the queryConversationList interface, pass in a mark list by ZIMConversationFilterOption.marks, and you can use the marks as filters to get a conversation list.

Note
  • The conversation mark list ZIMConversationFilterOption.marks only supports integers in the range [1, 20]:
    • If the list contains -1, the query result will be all marked conversations;
    • If the list contains 0, the query result will be all conversations without any marks;
    • If multiple marks are passed, the query result will be the union of all the passed marks;
    • If the list is empty, the query result will be all conversations.
  • Only one-on-one conversations and group conversations are queried.

Additionally, if you need to consider whether there are unread messages in the conversation during the query, simply pass isOnlyUnreadConversation as YES when calling the queryConversationList interface.

Untitled
// For example, querying the list of group chat conversations that have a mark of 1 and contain unread messages
ZIMConversationQueryConfig config = ZIMConversationQueryConfig();
config.count = 100;
config.nextConversation = null; // Set to null for the first query, and for subsequent paginated queries, pass in the last conversation in the returned list
ZIMConversationFilterOption option = ZIMConversationFilterOption();
option.marks.add(1); // Fill in the marks to be queried
option.conversationTypes.add(ZIMConversationType.group); // Fill the conversation type. If the list is empty, get both one-to-one and group conversations
option.isOnlyUnreadConversation = true; // Here, specify whether to only query conversations with unread messages. The default is false, and the query does not consider whether there are unread messages in the conversation

ZIM.getInstance()?.queryConversationList(config,option).then((value) {
    // Operation successful
}).catchError((onError){
if(onError is PlatformException){
    // Operation failed
    onError.code;
    onError.message;
}
});
1
Copied!

Query total unread Message count by marks

Call the queryConversationTotalUnreadMessageCount interface and pass in the conversation mark list through ZIMConversationTotalUnreadMessageCountQueryConfig.marks to query the total number of unread messages for conversations marked accordingly.

Note
  • The rule for calculating the total number of unread messages here is consistent with the onConversationTotalUnreadMessageCountUpdated event, which means that if there is a conversation which meets the requirements and has been muted, the unread count of this conversation will not be included in the total unread count queried here.
  • The conversation mark list (ZIMConversationTotalUnreadMessageCountQueryConfig.marks) only supports integers in the range [1, 20]:
    • If the list contains -1, the query result will be for all marked conversations;
    • If the list contains 0, the query result will be for all conversations without any marks;
    • If multiple marks are passed, the query result will be the union of all the passed marks;
    • If the list is empty, the query result will be for all conversations.
  • Only one-on-one conversations and group conversations are queried.
Untitled
// For example, querying the total number of unread messages for group conversations marked with 1
ZIMConversationTotalUnreadMessageCountQueryConfig config =  ZIMConversationTotalUnreadMessageCountQueryConfig();
config.marks.add(1); // Fill in the marks you want to query here
config.conversationTypes.add(ZIMConversationType.group); // Fill in the conversation types you want to query here. If the list is empty, both one-on-one and group conversations will be queried.
ZIM.getInstance()?.queryConversationTotalUnreadMessageCount(config).then((value) {
    // Query Successful
}).catchError((onError){
    if(onError is PlatformException){
        // Query failed

    }
});
1
Copied!

Previous

Set conversation draft

Next

Cache management