After logging in to the app, you can display a list of recent conversations. The entire display process includes the following steps: pulling the conversation list, processing the change notifications, and updating the UI content (including the unread count). This document describes these steps in detail.
After logging in to the app, you can call getConversationList() to pull the local conversation list and display the list on the UI. The conversation list is a list of V2TIMConversation objects, and every object represents a conversation.
The number of local conversations may be large, for example, greater than 500, and it may take a long time to load all the conversations at a time, which results in slow display of the conversation list on the UI. To improve user experience, the getConversationList()
API is provided to support the feature of pulling by page.
getConversationList()
API is called for the first time, you can set the nextSeq
parameter to 0
, indicating that the conversation list is pulled from the beginning, and set count
to 50
, indicating that 50 conversation objects are pulled at a time.getConversationList()
, will contain the nextSeq
field for the next pulling by page and the isFinished
field that indicates whether the conversation pulling is completed.isFinished
is true
, all conversations have been pulled.isFinished
is false
, more conversations can be pulled. This does not mean that the next page of the conversation list will be pulled immediately. In common communications software, pulling by page is often triggered by your swipe operations. Your each swipe on the conversation list triggers pulling by page once.nextSeq
and count
parameters again. The values of the two parameters come from the V2TIMConversationResult object returned in the previous pulling.isFinished
is true
.After obtaining the V2TIMConversation object, the IM SDK can display the conversation information on the UI. V2TIMConversation
contains the following key fields, which are often used to construct the conversation list.
Field | Description |
---|---|
showName | The conversation name:
|
faceUrl | The profile photo for the conversation:
|
unreadCount | The unread count, which indicates the number of unread messages. |
recvOpt | The message receiving option, which is generally used for a group conversation. It indicates whether the Mute Notifications mode is enabled for the group. |
lastMessage | The last message, which displays the message digest of the conversation. |
groupAtInfolist | The @ information of the conversation, which shows "someone @ me", "@ all members", and more. |
isPinned | Whether the conversation is pinned to the top. This is available only in the Lite edition. |
After the IM SDK is successfully logged in, or the user goes online, or the connection is re-established after being interrupted, the IM SDK will automatically update the conversation list. The update process is shown as follows:
V2TIMConversationListener
.V2TIMConversationListener
.Note:To ensure that the order of the conversation list complies with the sorting rule specified in the last message, the data source must be re-sorted based on timestamp in lastMessage.
The sample code shows how to pull, display, and update the conversation list.
// 1. Set the conversation listener.
[[V2TIMManager sharedInstance] setConversationListener:self];
// 2. Log in to the IM SDK.
[[V2TIMManager sharedInstance] login:@"yahaha" userSig:@"Pass in the actual UserSig" succ:^{
// 3. Pull 50 local conversations to display them on the UI. Set the value of `nextSeq` to `0` for the first pulling.
__weak __typeof(self) weakSelf = self;
[[V2TIMManager sharedInstance] getConversationList:0 count:50
succ:^(NSArray<V2TIMConversation *> *list, uint64_t nextSeq, BOOL isFinished) {
__strong __typeof(weakSelf) strongSelf = weakSelf;
// Pulling is successful, and the UI conversation list is updated.
[strongSelf updateConversation:list];
// 4. If more conversations need to be pulled, the value of `nextSeq` returned in the previous pulling will be passed in.
if(!isFinished) {
[[V2TIMManager sharedInstance] getConversationList:nextSeq count:50
succ:^(NSArray<V2TIMConversation *> *list, uint64_t nextSeq, BOOL isFinished) {
// Pulling is successful, and the UI conversation list is updated.
[strongSelf updateConversation:list];
} fail:^(int code, NSString *msg) {
// The attempt to pull the conversation list fails.
}];
}
} fail:^(int code, NSString *msg) {
// The attempt to pull the conversation list fails.
}];
} fail:^(int code, NSString *msg) {
// Login fails.
}];
// Receive the callback for adding a conversation.
- (void)onNewConversation:(NSArray<V2TIMConversation*> *) conversationList {
[self updateConversation:conversationList];
}
// Receive the callback for updating the conversation.
- (void)onConversationChanged:(NSArray<V2TIMConversation*> *) conversationList {
[self updateConversation:conversationList];
}
// Update the UI conversation list.
- (void)updateConversation:(NSArray *)convList
{
// If the updated conversation exists in the UI conversation list, replace this conversation. Otherwise, add this conversation.
for (int i = 0 ; i < convList.count ; ++ i) {
V2TIMConversation *conv = convList[i];
BOOL isExit = NO;
for (int j = 0; j < self.uiConvList.count; ++ j) {
V2TIMConversation *uiConv = self.localConvList[j];
// If the updated conversation exists in the UI conversation list, replace this conversation.
if ([uiConv.conversationID isEqualToString:conv.conversationID]) {
[self.uiConvList replaceObjectAtIndex:j withObject:conv];
isExit = YES;
break;
}
}
// If the updated conversation does not exist in the UI conversation list, add this conversation.
if (!isExit) {
[self.uiConvList addObject:conv];
}
}
// Sort the UI conversation list based on `timestamp` in `lastMessage` of the conversation.
[self.uiConvList sortUsingComparator:^NSComparisonResult(V2TIMConversation *obj1, V2TIMConversation *obj2) {
return [obj2.lastMessage.timestamp compare:obj1.lastMessage.timestamp];
}];
}
You can call the getTotalUnreadMessageCount API to get the total unread count of all conversations. You don't need to go through the conversation list and add up the unread count of each conversation to get the total unread count. When the total unread count changes, the SDK will proactively call back onTotalUnreadMessageCountChanged to your app to notify you of the latest total unread count.
Note:This feature is available only in Enhanced Edition v5.3.425 or later.
You can pin a one-to-one or group conversation to the top of the conversation list so you can quickly find it. The new SDK version has added the pinConversation API for pinning/unpinning conversations to/from the top. The pinning/unpinning settings also support roaming and multi-device synchronization.
The V2TIMConversation conversation object has added the isPinned API, which is used to determine whether a conversation is pinned to the top. When the pinned-to-top status of a conversation changes, the SDK will call back onConversationChanged to your app.
Note:This feature is available only in Enhanced Edition v5.3.425 or later.
You can call the deleteConversation API to delete a conversation. By default, conversation deletion is not synchronized across multiple devices. You can enable the synchronization feature in the console. When a conversation is deleted, the message history of this conversation will be deleted from the local storage and the server and cannot be recovered.
When sending a message, you may need to switch to another chat window before message editing is completed. In this case, you can call the setConversationDraft API to save the unfinished message as a draft. Later, you can return to the original chat window and call draftText to continue editing the message.
Note:
- Only text content can be stored as drafts.
- Drafts are stored only locally, instead of on the server. Therefore, drafts cannot be synchronized across multiple devices. If the app is uninstalled, drafts cannot be reloaded.
A locally stored conversation list can contain unlimited conversations. A conversation list stored in the cloud can have up to 100 conversations (which can be extended to 500 conversations by a Flagship edition user in the console).
If the information of a conversation has not been updated for a long time, this conversation can be stored in the cloud for up to seven days. To extend the conversation storage period, contact us.
Locally stored conversations may not always be consistent with those stored in the cloud. If you do not call the deleteConversation API to delete a local conversation, the conversation will always exist. However, only up to 100 conversations can be stored in the cloud. In addition, if the information of a conversation has not been updated for a long time, the conversation can be stored in the cloud for only up to seven days. Therefore, the conversation lists displayed on different mobile phones may be inconsistent.
Conversations that are pulled by the getConversationList
API may have already been added to the data source of the UI conversation list through the onNewConversation
callback API. Therefore, to avoid adding the same conversation repeatedly, you need to find and replace duplicate conversations in the data source by using getConversationID.
IM SDK v5.3.425 or later version supports pinning a conversation to the top, and the setting can be synchronized to the cloud.
Was this page helpful?