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 via setEventHandler, 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
zim.setEventHandler(this);

// ...

public void onConversationChanged(ZIM zim, ArrayList<ZIMConversationChangeInfo> conversationChangeInfoList) {
    super.onConversationChanged(zim, conversationChangeInfoList);
    for (ZIMConversationChangeInfo conversationChangeInfo : conversationChangeInfoList) {
        // The full set of markings for the conversation can be obtained from changeInfo.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
Integer markType = 1;
boolean enable  = true;
ArrayList<ZIMConversationBaseInfo> convList = new ArrayList<>();
ZIMConversationBaseInfo conversation = new ZIMConversationBaseInfo();
conversation.conversationID = "GroupConv";
conversation.conversationType = ZIMConversationType.GROUP;
convList.add(conversation);

zim.setConversationMark(markType, enable, convList, new ZIMConversationMarkSetCallback() {
    @Override
    public void onConversationMarkSet(ArrayList<ZIMConversationBaseInfo> failedConversationInfos, ZIMError errorInfo) {
        if(errorInfo.code == ZIMErrorCode.SUCCESS) {
            // Operation succesdful
            // Note: Even if part of the operation is successful and part is failed, the errorCode will still be Success, and failedConversationInfos will return the conversations where the operation failed
        } else {
            // Logic when all operations on all conversations fail
        }
    }
});
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 = new 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 = new 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.queryConversationList(config, option, new ZIMConversationListQueriedCallback() {
    @Override
    public void onConversationListQueried(ArrayList<ZIMConversation> conversationList, ZIMError errorInfo) {
        if(errorInfo.code == ZIMErrorCode.SUCCESS) {
            // Query successful
        } else {
            // Query failed
        }
    }
});
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 = new 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.queryConversationTotalUnreadMessageCount(config, new ZIMConversationTotalUnreadMessageCountQueriedCallback() {
    @Override
    public void onConversationTotalUnreadMessageCountQueried(int unreadMessageCount, ZIMError errorInfo) {
        if(errorInfo.code == ZIMErrorCode.SUCCESS) {
            // Query successful
        } else {
            // Query failed
        }
    }
});
1
Copied!

Previous

Set conversation draft

Next

Cache management