Pin A Message

Keep important messages easy to find by pinning them to a conversation. A pinned message is visible to all participants of the conversation, along with who pinned it and when. Users can pin messages, unpin them, and fetch all pinned messages of a conversation. You can also listen to pin events in real-time. Let’s see how to work with pinned messages in CometChat’s Android SDK.

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

To pin a message, use the pinMessage method and pass the ID of the message to be pinned. On success, the callback returns the updated BaseMessage with its pin attributes set.

Java
Kotlin

long messageId = 1;

CometChat.pinMessage(messageId, new CometChat.CallbackListener<BaseMessage>() {
  @Override
  public void onSuccess(BaseMessage message) {
      Log.d(TAG, "Message pinned at: " + message.getPinnedAt());
  }

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

val messageId = 1L

CometChat.pinMessage(messageId, object : CometChat.CallbackListener<BaseMessage>() {
  override fun onSuccess(message: BaseMessage?) {
      Log.d(TAG, "Message pinned at: ${message?.pinnedAt}")
  }

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

In a group conversation, the CometChat UI Kits show the Pin/Unpin option only to participants with the Admin or Moderator scope, or the group owner. This gate is applied client-side — the SDK does not currently enforce roles on the server, so apply your own role check if you build custom pin UI. Every participant can see pinned messages. In a one-on-one conversation, both participants can pin and unpin. Deleted messages cannot be pinned; deleting a pinned message automatically unpins it.

Unpin a Message

To unpin a message, use the unpinMessage method. Any participant with pin permission can unpin a message — not just the user who originally pinned it. On success, the callback returns the updated BaseMessage with its pin attributes cleared.

Java
Kotlin

long messageId = 1;

CometChat.unpinMessage(messageId, new CometChat.CallbackListener<BaseMessage>() {
  @Override
  public void onSuccess(BaseMessage message) {
      Log.d(TAG, "Message unpinned. isPinned: " + message.isPinned());
  }

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

val messageId = 1L

CometChat.unpinMessage(messageId, object : CometChat.CallbackListener<BaseMessage>() {
  override fun onSuccess(message: BaseMessage?) {
      Log.d(TAG, "Message unpinned. isPinned: ${message?.isPinned}")
  }

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

Fetch Pinned Messages

To fetch all pinned messages of a conversation, create a MessagesRequest with the setPinned(true) filter of the MessagesRequestBuilder. Setting a UID (for a one-on-one conversation) or a GUID (for a group) is mandatory — exactly one of the two. The returned list is sorted by the time of pinning, most recently pinned first.

Java (User)
Java (Group)
Kotlin (User)
Kotlin (Group)

String UID = "cometchat-uid-1";

MessagesRequest messagesRequest = new MessagesRequest.MessagesRequestBuilder()
  .setPinned(true)
  .setLimit(50)
  .setUID(UID)
  .build();

messagesRequest.fetchNext(new CometChat.CallbackListener<List<BaseMessage>>() {
  @Override
  public void onSuccess(List<BaseMessage> messages) {
      Log.d(TAG, "Pinned messages: " + messages.size());
  }

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

String GUID = "cometchat-guid-1";

MessagesRequest messagesRequest = new MessagesRequest.MessagesRequestBuilder()
  .setPinned(true)
  .setLimit(50)
  .setGUID(GUID)
  .build();

messagesRequest.fetchNext(new CometChat.CallbackListener<List<BaseMessage>>() {
  @Override
  public void onSuccess(List<BaseMessage> messages) {
      Log.d(TAG, "Pinned messages: " + messages.size());
  }

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

val UID = "cometchat-uid-1"

val messagesRequest = MessagesRequest.MessagesRequestBuilder()
  .setPinned(true)
  .setLimit(50)
  .setUID(UID)
  .build()

messagesRequest.fetchNext(object : CometChat.CallbackListener<List<BaseMessage>>() {
  override fun onSuccess(messages: List<BaseMessage>?) {
      Log.d(TAG, "Pinned messages: ${messages?.size}")
  }

  override fun onError(e: CometChatException?) {
      Log.e(TAG, "Pinned messages fetch failed: ${e?.message}")
  }
})

val GUID = "cometchat-guid-1"

val messagesRequest = MessagesRequest.MessagesRequestBuilder()
  .setPinned(true)
  .setLimit(50)
  .setGUID(GUID)
  .build()

messagesRequest.fetchNext(object : CometChat.CallbackListener<List<BaseMessage>>() {
  override fun onSuccess(messages: List<BaseMessage>?) {
      Log.d(TAG, "Pinned messages: ${messages?.size}")
  }

  override fun onError(e: CometChatException?) {
      Log.e(TAG, "Pinned messages fetch failed: ${e?.message}")
  }
})

Check if a Message is Pinned

Every fetched or received message carries its pin state on the BaseMessage itself.

Method	Description
`isPinned()`	Returns `true` if the message is currently pinned in its conversation.
`getPinnedAt()`	The timestamp at which the message was pinned. `0` when the message is not pinned.
`getPinnedBy()`	The `UID` of the user who most recently pinned the message. The value `app_system` indicates a pin applied by the app itself (a system pin).

Java
Kotlin

if (message.isPinned()) {
    Log.d(TAG, "Pinned by " + message.getPinnedBy() + " at " + message.getPinnedAt());
}

if (message.isPinned) {
    Log.d(TAG, "Pinned by ${message.pinnedBy} at ${message.pinnedAt}")
}

Editing a message preserves its pin. A message stores only its most recent pinner in getPinnedBy().

Real-time Pin Events

Register a MessageListener and override the pin callbacks. Each event delivers the full updated BaseMessage, so you can directly replace the message in your list. Today these callbacks fire on the acting user’s device when a pin or unpin succeeds. Delivery to other participants activates once server-side real-time delivery for pin events is rolled out — until then, other clients pick up pin changes on their next message fetch.

Java
Kotlin

private String listenerID = "UNIQUE_LISTENER_ID";

CometChat.addMessageListener(listenerID, new CometChat.MessageListener() {
  @Override
  public void onMessagePinned(BaseMessage message) {
      Log.d(TAG, "Message pinned: " + message.getId());
  }

  @Override
  public void onMessageUnpinned(BaseMessage message) {
      Log.d(TAG, "Message unpinned: " + message.getId());
  }
});

val listenerID = "UNIQUE_LISTENER_ID"

CometChat.addMessageListener(listenerID, object : CometChat.MessageListener() {
  override fun onMessagePinned(message: BaseMessage) {
      Log.d(TAG, "Message pinned: ${message.id}")
  }

  override fun onMessageUnpinned(message: BaseMessage) {
      Log.d(TAG, "Message unpinned: ${message.id}")
  }
})

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

Pin Limit

A conversation can hold a limited number of pinned messages (100 by default). When the limit is exceeded, the SDK surfaces the server error through onError, and the applicable limit can be read programmatically from the exception — never hard-code it.

Java
Kotlin

@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 + " messages in a conversation.");
    }
}

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

Feature Availability

Check whether the Pin Message 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
Kotlin

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

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

​Pin a Message

​Unpin a Message

​Fetch Pinned Messages

​Check if a Message is Pinned

​Real-time Pin Events

​Pin Limit

​Feature Availability

Pin a Message

Unpin a Message

Fetch Pinned Messages

Check if a Message is Pinned

Real-time Pin Events

Pin Limit

Feature Availability