tencent cloud

Feedback

Android&iOS&Windows&Mac

Last updated: 2024-07-05 18:00:24

    Overview

    Pinning a conversation to the top is to fix a one-to-one or group conversation at the top of the conversation list to facilitate search. A conversation pinned to the top will not be displayed under another conversation with an update. The status of a conversation being pinned to the top will be stored on the server and synced to new devices.
    Note
    This feature is supported only by the SDK of the Enhanced edition on v5.3.425 or later.
    The maximum number of conversations that can be pinned to the top is 50, and this limit cannot be increased.

    Effect

    You can use this feature to achieve the pinning effect as shown in the figure below, where the two group chats with a gray background are pinned conversations:
    
    
    

    Interface Description

    Pinning a Conversation to the Top

    Call pinConversation (Android / iOS and Mac / Windows) to set whether to pin a conversation to the top.
    When getConversationList is called to get the conversation list, it will first return the conversation that is pinned to the top and then other conversations. You can check whether a conversation is pinned to the top through the isPinned field of the V2TIMConversation object.
    The conversations are sorted based on the orderKey field of the V2TIMConversation object. This field is an integer that increases as the conversation is activated when a message is sent/received, a draft is set, or the conversation is pinned to the top.
    A conversation pinned to the top will always be displayed above others. If multiple conversations are pinned to the top, they will be sorted in the original order. For example, if there are five conversations (1, 2, 3, 4, and 5 in order) and conversations 2 and 3 are pinned to the top, the new order will be 2, 3, 1, 4, and 5. Obviously, conversations 2 and 3 are displayed above others, and conversation 2 is displayed above conversation 3.
    Sample code:
    Android
    iOS and macOS
    Windows
    // If `isPinned` is `true`, the conversation is pinned to the top; otherwise, it is not.
    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);
    }
    });
    // If `isPinned` is `YES`, the conversation is pinned to the top; otherwise, it is not.
    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(
    [=]() {
    // The conversation is pinned to top successfully.
    delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
    // Failed to pin the conversation to the top.
    delete callback;
    });
    
    V2TIMManager::GetInstance()->GetConversationManager()->PinConversation(conversationID, isPinned, callback);

    Conversation Pinned Status Changed Notification

    If you have called addConversationListener (Android / iOS and macOS / Windows) to add a conversation listener, you can get the isPinned value of the V2TIMConversation object in onConversationChanged and determine whether the pinned status of a conversation has changed.
    Sample code:
    Android
    iOS and macOS
    public void onConversationChanged(List<V2TIMConversation> conversationList) {
    // Received the notification of a change in the conversation information
    Log.i("imsdk", "onConversationChanged");
    }
    - (void)onConversationChanged:(NSArray<V2TIMConversation*> *) conversationList {
    for (V2TIMConversation *conv in conversationList) {
    if ([conv.conversationID isEqualToString:self.conversationData.conversationID]) {
    // `conv.isPinned` is the pinned status.
    }
    }
    }
    
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support