please select
  • UIKit
  • SDK
  • Server APIs
Chat/
SDK/
Web/
Conversation/
SDK
  • Install Chat SDK
  • Initialize Chat SDK
  • Login and Logout
  • Client APIs
  • Changelog
  • Message
    • Overview
    • Send a Message
    • Receive a Message
    • Historical Message
    • Forward Messages
    • Modify a Message
    • Delete Messages
    • Clear History Message
    • Recall a Message
    • Send an Online Message
    • Message Read Receipt
    • Query Messages
    • Targeted Group Message
    • Do not Notify
    • Key-Value Extensions
    • Translation
  • Conversation
    • Overview
    • Conversation List
    • Get Conversations
    • Unread Count
    • Pin Conversations
    • Delete Conversations
    • Mark
    • Conversation Group
  • Group
    • Overview
    • Group Management
    • Group Profile
    • Group Member Management
    • Group Member Profile
    • Custom Group Attribute
    • Group Counter
  • Community Topic
    • Community Management
  • User Profile and Relationship Chain
    • User Profile
    • User Status
    • Friend Management
    • Friend Group
    • Block List
  • Guideline for Beginners
  • Console Guide
    • Creating and Upgrading an Application
    • Basic Configuration
    • Feature Configuration
    • Account Management
    • Group Management
    • Webhook Configuration
  • Product Introduction
    • Message Management
      • One-to-One Message
      • Message Storage
      • Offline Push
      • Group Message
      • Message Formats
    • Account System
      • Login Authentication
      • Online Status Management
    • Group Related
      • Group System
      • Group Management
    • User Profile and Relationship Chain
      • Profile Management
      • Relationship Chain Management
  • Purchase Guide
    • Billing Overview
    • Pricing
  • Error Codes
Docs Overview/
Chat/
SDK/
Web/
Conversation/
Pin Conversations/

Pin Conversations

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. The status of a conversation being pinned to the top will be stored on the server and synced to new devices. After this API is called successfully, the conversation list will be sorted again, and the SDK will distribute the TencentCloudChat.EVENT.CONVERSATION_LIST_UPDATED event.
Note
1. The maximum number of conversations that can be pinned to the top is 50, and this limit cannot be increased.

Pinning/Unpinning a Conversation to/from the Top

API
chat.pinConversation(options);
Parameters
The options parameter is of the Object type. It contains the following attribute values:
Name
Type
Description
conversationID
String
Conversation ID, which consists of:
C2C${userID} (for one-to-one chats)
GROUP{groupID} (for group chats)
@TIM#SYSTEM (system notification conversation)
GROUP${topicID} (topic)
isPinned
Boolean
true, the conversation is pinned to the top
false, the conversation is unpinned from the top
Return values
Promise
Sample
// Pin a conversation to top
let promise = chat.pinConversation({ conversationID: 'C2CExample', isPinned: true });
promise.then(function(imResponse) {
  // The conversation is pinned to top successfully.
  const { conversationID } = imResponse.data; // ID of the conversation pinned to top
}).catch(function(imError){
  console.warn('pinConversation error:', imError); // Error information
});
// Unpin a conversation from top
let promise = chat.pinConversation({ conversationID: 'C2CExample', isPinned: false });
promise.then(function(imResponse) {
  // The conversation is unpinned from top successfully.
  const { conversationID } = imResponse.data; // ID of the conversation unpinned from top
}).catch(function(imError){
  console.warn('pinConversation error:', imError); // Error information
});