Get the conversation list
Overview
Conversation is the logic automatically established by the ZIM SDK for users sending one-to-one or group messages(only text message ore rich media messages, excluding signaling messages).
ZIM supports users to listen for conversation changes and get a conversation list from the local database. It also supports developers to retrieve the complete conversation list of a specific user from the ZIM server.
You can obtain and display the one-on-one and group chat conversation lists in scenarios such as chats, gaming communities, and online consulting.
Listen for conversation changes
Before logging in, users should on listen for the callback conversationChanged, After login, the users will receive notifications of conversation changes when the following events happen:
| Category | Event | Event Value | ZIMConversation Property |
|---|
| Basic Conversation Properties | Change conversation name. | Updated |
| Change conversation avatar URL. | conversationAvatarUrl |
- When a user sets a remark (friendAlias) for a friend, the ZIM SDK synchronously modifies the corresponding alias of the one-on-one conversation.
- When a user sets a remark (groupAlias) for a group, the ZIM SDK will synchronize and modify the corresponding conversation alias for the group chat.
| conversationAlias |
| Change unread message count. | unreadMessageCount |
| Additional Conversation Properties | User sets/cancels a conversation as pinned. | isPinned |
| User sets notification status for a conversation. | notificationStatus |
| User saves a conversation draft. | draft |
| User is mentioned in a conversation. | mentionedInfoList |
| Last Message in Conversation Changes | User receives a new message. | lastMessage |
| User sends a new message. |
| Last message status or content changes. |
| Conversation Status Changes | User has a new conversation. | Added | - |
User voluntarily leaves/is kicked out of a group conversation. This assumes that the group conversation already exists (i.e., there are messages in the conversation). | Disabled | - |
Group conversation is dissolved. This assumes that the group conversation already exists (i.e., there are messages in the conversation). |
| Recipient user does not exist when sending a one-on-one message. |
| User sends a message to a group they have not joined. |
| User deletes a conversation. | Deleted | - |
At this time, you can get the conversation list based on your demands.
Currently, the callback conversationChanged only supports notification of incremental changes of the conversation list in the local database and the conversation list on the ZIM server.
You need to maintain the array of conversation lists retrieved from the queryConversationList method, and based on current conversation updates, perform property changes, inserts, and sorted displays .
// Set up the event handler
zim.setEventHandler(this);
...
public void onConversationChanged(ZIM zim, ArrayList<ZIMConversationChangeInfo> conversationChangeInfoList) {
super.onConversationChanged(zim, conversationChangeInfoList);
}
1
// Set up the event handler
[self.zim setEventHandler:self];
...
- (void)zim:(ZIM *)zim conversationChanged:(NSArray<ZIMConversationChangeInfo *> *)conversationChangeInfoList {
// Get the conversation change list.
for (ZIMConversationChangeInfo *info in conversationChangeInfoList) {
if (info.event == ZIMConversationEventAdded) {
// Add to your self-maintained list and set up a UI fresh here.
} else if (info.event == ZIMConversationEventUpdated) {
// Edit the conversation properties, and set up a UI fresh here.
}
}
}
1
// Set up the event handler
[self.zim setEventHandler:self];
...
- (void)zim:(ZIM *)zim conversationChanged:(NSArray<ZIMConversationChangeInfo *> *)conversationChangeInfoList {
// Get the conversation change list.
for (ZIMConversationChangeInfo *info in conversationChangeInfoList) {
if (info.event == ZIMConversationEventAdded) {
// Add to your self-maintained list and set up a UI fresh here.
} else if (info.event == ZIMConversationEventUpdated) {
// Edit the conversation properties, and set up a UI fresh here.
}
}
}
1
// Set up the event handler and listen for related event callbacks.
zim.setEventHandler(shared_from_this());
...
void onConversationChanged(ZIM * zim, const std::vector<ZIMConversationChangeInfo> & conversationChangeInfoList) {
// Get the conversation change list.
for (auto &info : conversationChangeInfoList) {
if (info.event == ZIMConversationEventAdded) {
// Add to your self-maintained list and set up a UI fresh here.
} else if (info.event == ZIMConversationEventUpdated) {
// UI Edit the conversation properties, and set up a UI fresh here.
}
}
}
1
ZIM.GetInstance().onConversationChanged = (
ZIM zim, List<ZIMConversationChangeInfo> conversationChangeInfoList) =>
{
// Notification of the conversation changes.
};
1
zim.on('conversationChanged', function(zim, { infoList }){
console.log('conversationChanged', infoList)
})
1
ZIMEventHandler.onConversationChanged = (conversationChangeInfoList) {
};
1
Get the conversation list
ZIM supports developers to call SDK interfaces to retrieve the current user's conversation list from the local database. It also supports making requests to the ZIM server to retrieve the complete conversation list of a specific user.
After fetching the conversation list, developers can use it to customize the UI display of the conversation list.
From the local database
- The ZIM SDK currently only supports fetching one-to-one and group conversation lists, and does not support fetching the room conversation list.
- The conversation list is stored in the local database, and when getting the conversation list, relevant data will be retrieved from the local database.
- It is recommended for you to use this feature on the first screen of the conversation page.
After login, if users want to know what conversations they have joined, they can call the queryConversationList method to query the conversation list.
To avoid the problem of pulling too many conversations at the same time, which takes a long time and causes slow loading of the conversation interface, you can customize the number of conversations by setting the ZIMConversationQueryConfig object for paging query when pulling conversations.
ZIMConversationQueryConfig config = new ZIMConversationQueryConfig();
// conversation query anchor. Empty indicates that the query starts from the latest.
config.nextConversation = null;
// The number of queries per page.
config.count = 20;
// Get the conversation list.
zim.queryConversationList(config, new ZIMConversationListQueriedCallback() {
@Override
public void onConversationListQueried(ArrayList<ZIMConversation> conversationList, ZIMError errorInfo) {
// Get the results of query the conversation list.
if(errorInfo.code == ZIMErrorCode.SUCCESS) {
// You will need to save and maintain the conversation objects in the array.
} else {
// ......
}
}
});
1
ZIMConversationQueryConfig *config = [[ZIMConversationQueryConfig alloc] init];
// conversation query anchor. Empty indicates that the query starts from the latest.
config.nextConversation = nil;
// The number of queries per page.
config.count = 20;
// Get the conversation list.
[self.zim queryConversationListWithConfig:config callback:^(NSArray<ZIMConversation *> * _Nonnull conversationList, ZIMError * _Nonnull errorInfo) {
// Get the results of query the conversation list.
if(errorInfo.code == ZIMErrorCodeSuccess) {
// You will need to save and maintain the conversation objects in the array.
} else {
// ......
}
}];
1
ZIMConversationQueryConfig *config = [[ZIMConversationQueryConfig alloc] init];
// conversation query anchor. Empty indicates that the query starts from the latest.
config.nextConversation = nil;
// The number of queries per page.
config.count = 20;
// Get the conversation list.
[self.zim queryConversationListWithConfig:config callback:^(NSArray<ZIMConversation *> * _Nonnull conversationList, ZIMError * _Nonnull errorInfo) {
// Get the results of query the conversation list.
if(errorInfo.code == ZIMErrorCodeSuccess) {
// You will need to save and maintain the conversation objects in the array.
} else {
// ......
}
}];
1
ZIMConversationQueryConfig config;
// conversation anchor point. Empty indicates that the query starts from the latest.
config.nextConversation = nullptr;
// The number of queries per page.
config.count = 20;
// Get the conversation list.
zim.queryConversationList(config, [=](std::vector<std::shared_ptr<ZIMConversation>> conversationList, ZIMError errorInfo) {
// Get the results of query the conversation list.
if(errorInfo.code == ZIMErrorCodeSuccess) {
// You will need to save and maintain the conversation objects in the array.
} else {
// ......
}
});
1
ZIMConversationQueryConfig config = new ZIMConversationQueryConfig();
// Conversation anchor, pass null to start querying from the latest
config.nextConversation = null;
// Number of conversations to query at a time
config.count = 20;
// Retrieve the conversation list
ZIM.GetInstance().QueryConversationList(config, (List<ZIMConversation> conversationList,
ZIMError errorInfo) =>
{
// Callback of the retrieval result
});
1
var config = {
// The conversation flag. If it is set to `null`, the flag is the latest conversation.
nextConversation: null,
// The number of conversations queried per page.
count: 20
};
// Pull the conversation list.
zim.queryConversationList(config)
.then(function({ conversationList }){
// Query succeeded. You need to store and maintain the conversation objects in the array.
})
.catch(function(err){
// Query failed.
})
1
ZIMConversationQueryConfig conversationQueryConfig =
ZIMConversationQueryConfig();
conversationQueryConfig.nextConversation = null;
// The number of queries per page.
conversationQueryConfig.count = 20;
//Get the conversation list.
ZIM
.getInstance()
.queryConversationList(conversationQueryConfig)
.then((value) => {
// You will need to save and maintain the conversation objects in the array.
})
.catchError((onError) {});
1
From the ZIM server
You can get a user's conversation list by calling the server API. For more details, please refer to the server API documentation Query conversation list
