Pin A Conversation

Pin and unpin conversations, fetch the pinned conversation list, and keep it in sync with the CometChat Android SDK.

AI Integration Quick Reference

// Pin / unpin — address the conversation by peer id + type, not by conversation id
CometChat.pinConversation(UID, CometChatConstants.CONVERSATION_TYPE_USER, callbackListener)
CometChat.unpinConversation(GUID, CometChatConstants.CONVERSATION_TYPE_GROUP, callbackListener)

// Fetch pinned conversations only ("me", "system", or "system,me")
val request = ConversationsRequest.ConversationsRequestBuilder()
    .setPinnedBy("system,me")
    .setLimit(30)
    .build()
request.fetchNext(conversationFetchListener)               // onCachedConversations + onServerConversations

// Read pin state off a conversation
val isPinned = conversation.isPinned                       // pinnedAt > 0
val isSystemPinned = conversation.isSystemPinned           // pinnedBy == "app_system"

// Caps and availability
val limit = CometChat.getPinConversationLimit()            // -1 when unspecified
val systemLimit = CometChat.getSystemPinConversationLimit()
val enabled = CometChat.isPinConversationEnabled()         // Boolean

Let users keep their most important chats at the top of the list. Pinning a conversation is per-user — it changes the order of the acting user’s own conversation list and is synced across their devices. A conversation can also be pinned globally for everyone by the app itself (a system pin). Let’s see how to work with pinned conversations in CometChat’s Android SDK.

Pinning a conversation with the SDK requires the Pin Conversation feature to be enabled for your app. You can check its availability at runtime using the feature flag.

​

Pin a Conversation

To pin a conversation, use the pinConversation method. Pass the UID of the other user (for a one-on-one conversation) or the GUID of the group, along with the matching conversation type. On success, the callback returns the updated Conversation with its pin attributes set.

Java (User)

String UID = "cometchat-uid-1";

CometChat.pinConversation(UID, CometChatConstants.CONVERSATION_TYPE_USER,
    new CometChat.CallbackListener<Conversation>() {
      @Override
      public void onSuccess(Conversation conversation) {
          Log.d(TAG, "Conversation pinned at: " + conversation.getPinnedAt());
      }

      @Override
      public void onError(CometChatException e) {
          Log.e(TAG, "Failed to pin conversation: " + e.getMessage());
      }
});

Java (Group)

String GUID = "cometchat-guid-1";

CometChat.pinConversation(GUID, CometChatConstants.CONVERSATION_TYPE_GROUP,
    new CometChat.CallbackListener<Conversation>() {
      @Override
      public void onSuccess(Conversation conversation) {
          Log.d(TAG, "Conversation pinned at: " + conversation.getPinnedAt());
      }

      @Override
      public void onError(CometChatException e) {
          Log.e(TAG, "Failed to pin conversation: " + e.getMessage());
      }
});

Kotlin (User)

val UID = "cometchat-uid-1"

CometChat.pinConversation(UID, CometChatConstants.CONVERSATION_TYPE_USER,
    object : CometChat.CallbackListener<Conversation>() {
      override fun onSuccess(conversation: Conversation?) {
          Log.d(TAG, "Conversation pinned at: ${conversation?.pinnedAt}")
      }

      override fun onError(e: CometChatException) {
          Log.e(TAG, "Failed to pin conversation: ${e?.message}")
      }
})

Kotlin (Group)

val GUID = "cometchat-guid-1"

CometChat.pinConversation(GUID, CometChatConstants.CONVERSATION_TYPE_GROUP,
    object : CometChat.CallbackListener<Conversation>() {
      override fun onSuccess(conversation: Conversation?) {
          Log.d(TAG, "Conversation pinned at: ${conversation?.pinnedAt}")
      }

      override fun onError(e: CometChatException) {
          Log.e(TAG, "Failed to pin conversation: ${e?.message}")
      }
})

​

Unpin a Conversation

To unpin a conversation, use the unpinConversation method with the same parameters. On success, the callback returns the updated Conversation with its pin attributes cleared.

Java

String UID = "cometchat-uid-1";

CometChat.unpinConversation(UID, CometChatConstants.CONVERSATION_TYPE_USER,
    new CometChat.CallbackListener<Conversation>() {
      @Override
      public void onSuccess(Conversation conversation) {
          Log.d(TAG, "Conversation unpinned. isPinned: " + conversation.isPinned());
      }

      @Override
      public void onError(CometChatException e) {
          Log.e(TAG, "Failed to unpin conversation: " + e.getMessage());
      }
});

Kotlin

val UID = "cometchat-uid-1"

CometChat.unpinConversation(UID, CometChatConstants.CONVERSATION_TYPE_USER,
    object : CometChat.CallbackListener<Conversation>() {
      override fun onSuccess(conversation: Conversation?) {
          Log.d(TAG, "Conversation unpinned. isPinned: ${conversation?.isPinned}")
      }

      override fun onError(e: CometChatException) {
          Log.e(TAG, "Failed to unpin conversation: ${e?.message}")
      }
})

A user cannot unpin a system pin (a conversation pinned globally by the app). Use isSystemPinned() to detect this case and hide the unpin action.

​

Fetch Pinned Conversations

The default conversations list already orders pinned conversations at the top. To fetch only pinned conversations, use the setPinnedBy() filter of the ConversationsRequestBuilder.

Value	Description
"me"	Conversations pinned by the logged-in user.
"system"	Conversations pinned globally by the app (system pins).
"system,me"	Both.

Starting with v5.1.0, the CallbackListener overload of `fetchNext()` is deprecated. Use `ConversationFetchListener` instead; it requires SDK 5.1.0 or later, so on 5.0.x keep using CallbackListener. With offline support off, it behaves exactly like the old callback: onError is unchanged, and the server result arrives in the onServer… callback instead of onSuccess. With offline support on, it also delivers the cached result first; the old overload keeps working but receives only the server result. See Show Cached Data.

Java

ConversationsRequest conversationsRequest = new ConversationsRequest.ConversationsRequestBuilder()
  .setPinnedBy("system,me")
  .setLimit(30)
  .build();

conversationsRequest.fetchNext(new CometChat.ConversationFetchListener() {
  @Override
  public void onCachedConversations(List<Conversation> conversations) {
      // Render the cached pinned list immediately.
  }

  @Override
  public void onServerConversations(List<Conversation> conversations) {
      // Reconcile, keyed by conversation id.
  }

  @Override
  public void onError(CometChatException e) {
      Log.e(TAG, "Fetch failed: " + e.getMessage());
  }
});

Kotlin

val conversationsRequest = ConversationsRequest.ConversationsRequestBuilder()
  .setPinnedBy("system,me")
  .setLimit(30)
  .build()

conversationsRequest.fetchNext(object : CometChat.ConversationFetchListener() {
  override fun onCachedConversations(conversations: List<Conversation>) {
      // Render the cached pinned list immediately.
  }

  override fun onServerConversations(conversations: List<Conversation>) {
      // Reconcile, keyed by conversation id.
  }

  override fun onError(e: CometChatException) {
      Log.e(TAG, "Fetch failed: ${e.message}")
  }
})

​

Check if a Conversation is Pinned

Every fetched Conversation carries its pin state.

Method	Description
isPinned()	Returns true if the conversation is pinned for the logged-in user (or globally).
isSystemPinned()	Returns true if the conversation was pinned globally by the app (pinnedBy is app_system).
getPinnedAt()	The timestamp at which the conversation was pinned. 0 when it is not pinned.
getPinnedBy()	The UID of the pinner, or app_system for a system pin.

​

Real-time Conversation Pin Events

Register a ConversationListener to be notified when a conversation is pinned or unpinned, so your list can reorder without a refetch.

Your own pin or unpin fires onConversationPinned / onConversationUnpinned on the device that performed it, just before the pinConversation() / unpinConversation() success callback, so update your UI in one of the two, not both. These callbacks also fire on the user’s other devices when a pin frame arrives there.

Java

private String listenerID = "UNIQUE_LISTENER_ID";

CometChat.addConversationListener(listenerID, new CometChat.ConversationListener() {
  @Override
  public void onConversationPinned(Conversation conversation) {
      Log.d(TAG, "Conversation pinned: " + conversation.getConversationId());
  }

  @Override
  public void onConversationUnpinned(Conversation conversation) {
      Log.d(TAG, "Conversation unpinned: " + conversation.getConversationId());
  }
});

Kotlin

val listenerID = "UNIQUE_LISTENER_ID"

CometChat.addConversationListener(listenerID, object : CometChat.ConversationListener() {
  override fun onConversationPinned(conversation: Conversation) {
      Log.d(TAG, "Conversation pinned: ${conversation.conversationId}")
  }

  override fun onConversationUnpinned(conversation: Conversation) {
      Log.d(TAG, "Conversation unpinned: ${conversation.conversationId}")
  }
})

To stop listening, remove the listener with CometChat.removeConversationListener(listenerID).

​

Pin Limit

A user can pin a capped number of conversations, configurable per app. Read the cap rather than hard-coding it — it is tenant-overridable and will drift.

Java

int limit = CometChat.getPinConversationLimit();
int systemLimit = CometChat.getSystemPinConversationLimit();

if (limit != Settings.LIMIT_UNSPECIFIED && pinnedCount >= limit) {
    // Disable the pin control instead of letting the user hit the error
}

Kotlin

val limit = CometChat.getPinConversationLimit()
val systemLimit = CometChat.getSystemPinConversationLimit()

if (limit != Settings.LIMIT_UNSPECIFIED && pinnedCount >= limit) {
    // Disable the pin control instead of letting the user hit the error
}

Both are synchronous and never throw. They return Settings.LIMIT_UNSPECIFIED (-1) when the app settings carry no value or when they are called before init() completes — show generic copy in that case rather than guessing a number. getSystemPinConversationLimit() is the separate cap for admin/global pins: system pins do not consume a user’s allowance, so the two budgets are enforced independently.

When the limit is breached, the SDK surfaces the server error through onError, and the applicable limit is carried in the exception’s errorParams:

Java

@Override
public void onError(CometChatException e) {
    Object limit = e.getErrorParams() != null ? e.getErrorParams().get("limit") : null;
    if (limit != null) {
        Log.e(TAG, "You can pin up to " + limit + " conversations.");
    }
}

Kotlin

override fun onError(e: CometChatException) {
    val limit = e?.errorParams?.get("limit")
    if (limit != null) {
        Log.e(TAG, "You can pin up to $limit conversations.")
    }
}

​

Error Handling

Error	Meaning
ERROR_INVALID_CONVERSATION_WITH	The conversationWith argument was null or empty. The SDK rejects this locally, before any network call.
ERROR_INVALID_CONVERSATION_TYPE	The conversation type was neither CONVERSATION_TYPE_USER nor CONVERSATION_TYPE_GROUP. Also rejected locally.

​

Feature Availability

Check whether the Pin Conversation feature is enabled for your app before showing pin actions in your UI. The method is synchronous and safe to call from the UI layer.

Java

if (CometChat.isPinConversationEnabled()) {
    // show the Pin conversation option
}

Kotlin

if (CometChat.isPinConversationEnabled()) {
    // show the Pin conversation option
}

---

​

Offline Behaviour

With offline support enabled, fetchNext() on a setPinnedBy() request delivers a cached page first (onCachedConversations, even when empty), then the server list (onServerConversations); offline, it ends with onError with code ERROR_INTERNET_UNAVAILABLE after the cached page. onCachedConversations holds the pinned conversations the cache already knows about, in the same order.

Builder method	Offline
setPinnedBy	Cached

​

Next Steps

Pin A Message

Highlight a message for everyone in the conversation

Save A Message

Bookmark a message privately, across conversations

Retrieve Conversations

Every filter the conversations list supports

All Real Time Listeners

Every listener the SDK exposes, in one place