一、功能描述
注意：说明：
注意：1. 置顶会话功能仅增强版 5.3.425 及以上版本支持。
注意：2. 置顶会话数上限50，不支持增加。
二、效果展示
你可以使用本功能，实现如下所示的会话置顶效果，其中灰色背景的两个群聊是被置顶的群聊会话：
三、置顶会话
你可以调用 pinConversation(Java / Swift / Objective-C / C++) 接口，设置是否置顶会话。
调用 getConversationList 获取会话列表时，该接口返回的会话列表中，置顶的会话在前，未置顶的会话在后。你可以通过 V2TIMConversation 对象的 isPinned 字段，检查会话有没有置顶。
会话的顺序，按V2TIMConversation 对象的 orderKey 字段排序。orderKey 字段是整型数，当发送新消息、接收新消息、设置草稿或置顶会话时，会话被激活，orderKey 字段会增大。
会话被置顶后，置顶会话始终排在未置顶会话的前面。如果同时置顶多个会话，这几个会话之间的相对顺序仍然会保持。
例如，有 5 个依次排序的会话 1、2、3、4、5，同时置顶会话 2 和 3，置顶后的顺序是 2、3、1、4、5，显然，会话 2 和 3 排在最前面，并且会话 2 仍然排在 3 的前面。
示例代码如下：
JavaSwiftObjective-CC++// isPinned 参数为 true，表示置顶会话，否则，表示取消置顶。String conversationID = "conversationID";V2TIMManager.getConversationManager().pinConversation(conversationID, true, new V2TIMCallback() { @Override public void onSuccess() { Log.i("imsdk", "success"); } @Override public void onError(int code, String desc) { Log.i("imsdk", "failure, code:" + code + ", desc:" + desc); }});// isPinned 参数为 true，表示置顶会话，否则，表示取消置顶。var isPinned = trueV2TIMManager.shared.pinConversation(conversationID: "conversationID", isPinned: isPinned) { print("pinConversation succ \\(isPinned)") isPinned = !isPinned} fail: { code, desc in print("pinConversation fail \\(isPinned), \\(code), \\(desc)")}// isPinned 参数为 YES，表示置顶会话，否则，表示取消置顶。NSString *conversationID = @"conversationID";[[V2TIMManager sharedInstance] pinConversation:conversationID isPinned:YES succ:^{ NSLog(@"success");} fail:^(int code, NSString *desc) { NSLog(@"failure, code:%d, desc:%@", code, desc);}];class Callback final : public V2TIMCallback {public: using SuccessCallback = std::function<void()>; using ErrorCallback = std::function<void(int, const V2TIMString&)>; Callback() = default; ~Callback() override = default; void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) { success_callback_ = std::move(success_callback); error_callback_ = std::move(error_callback); } void OnSuccess() override { if (success_callback_) { success_callback_(); } } void OnError(int error_code, const V2TIMString& error_message) override { if (error_callback_) { error_callback_(error_code, error_message); } }private: SuccessCallback success_callback_; ErrorCallback error_callback_;};V2TIMString conversationID = u8"conversationID";bool isPinned = true;auto callback = new Callback;callback->SetCallback( [=]() { // 置顶会话成功 delete callback; }, [=](int error_code, const V2TIMString& error_message) { // 置顶会话失败 delete callback; });V2TIMManager::GetInstance()->GetConversationManager()->PinConversation(conversationID, isPinned, callback);
四、会话置顶变更通知
如果你事先调用了 addConversationListener(Java / Swift / Objective-C / C++) 添加会话监听器，就可以在 onConversationChanged 中获取到 V2TIMConversation 对象的 isPinned 字段值。根据这个字段可以判断会话的置顶状态是否变化。
示例代码如下：
JavaSwiftObjective-CC++public void onConversationChanged(List<V2TIMConversation> conversationList) { // 收到会话信息变更通知 Log.i("imsdk", "onConversationChanged");}func onConversationChanged(conversationList: Array<V2TIMConversation>) { for conv in conversationList { if conv.conversationID == self.conversationData.conversationID { // conv.isPinned 为会话置顶状态 let isPinned = conv.isPinned // 在这里可以根据需要处理 isPinned 状态 } }}- (void)onConversationChanged:(NSArray<V2TIMConversation*> *) conversationList { for (V2TIMConversation *conv in conversationList) { if ([conv.conversationID isEqualToString:self.conversationData.conversationID]) { // conv.isPinned 为会话置顶状态 } }}class ConversationListener final : public V2TIMConversationListener {public: void OnConversationChanged(const V2TIMConversationVector& conversationList) override { // 收到会话信息变更通知 } // 其他成员 …};// 添加会话事件监听器，注意在移除监听器之前需要保持 conversationListener 的生命期，以免接收不到事件回调ConversationListener conversationListener;V2TIMManager::GetInstance()->GetConversationManager()->AddConversationListener(&conversationListener);
五、操作置顶/取消置顶后，为什么会话没有按照 lastMessage 的顺序排序？
会话列表始终按照 V2TIMConversation.orderKey 从大到小的顺序排列，orderKey 会随着会话的更新依次递增。常见引起 orderKey 递增的操作有：收发消息（也即 lastMessage 发生变化）、置顶/取消置顶。当会话的 lastMessage 的时间顺序与 orderKey 不一致时，以 orderKey 顺序为准。