Pinned Messages - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatPinnedMessages",
  "package": "com.cometchat.uikit.kotlin.presentation.pinnedmessages (XML Views) / com.cometchat.uikit.compose.presentation.pinnedmessages.ui (Compose)",
  "xmlElement": "<com.cometchat.uikit.kotlin.presentation.pinnedmessages.CometChatPinnedMessages />",
  "description": "Full-screen list of all messages pinned in a conversation, rendered as real message bubbles, with jump-to-message and long-press row actions (unpin, copy, info, delete).",
  "primaryOutput": {
    "messageClicked": {
      "method": "setOnMessageClickListener",
      "type": "(BaseMessage) -> Unit"
    }
  },
  "methods": {
    "data": {
      "setUser": { "type": "User", "note": "Scope to a one-on-one conversation. Set exactly one of setUser/setGroup." },
      "setGroup": { "type": "Group", "note": "Scope to a group conversation." }
    },
    "callbacks": {
      "setOnMessageClickListener": "(BaseMessage) -> Unit — row tapped; navigate to the message in its conversation",
      "setOnBackClickListener": "() -> Unit — toolbar back pressed"
    }
  },
  "composeParams": {
    "user": "User? — scope to a one-on-one conversation",
    "group": "Group? — scope to a group conversation",
    "onMessageClick": "(BaseMessage) -> Unit",
    "onBackClick": "() -> Unit"
  },
  "events": ["CometChatMessageEvent.MessagePinned", "CometChatMessageEvent.MessageUnpinned"],
  "featureFlag": "CometChatUIKit.isPinMessageEnabled()"
}

CometChatPinnedMessages lists the messages pinned in one conversation, newest pin first. A pin is conversation-wide and visible to everyone, so this screen shows the same set to every participant.

Pin Messages must be enabled for your app through the features.ux.messages.pinned.enabled app setting in the CometChat Dashboard. Until it is, the pin options never render and this screen has nothing to show. Read the flag with CometChatUIKit.isPinMessageEnabled() to gate your own entry point.

Where It Fits

Open it from your conversation screen, scoped to the conversation the user is in — the Message Header provides a built-in “Pinned messages” menu item for this. It is a full-screen panel with its own back affordance rather than an inline strip. Each row renders the real message bubble, and a long-press menu offers Message info, Copy, Translate (text messages), Unpin and Delete. There is no Subscribe/Unsubscribe to thread option here: a pin that arrives in real time doesn’t carry its thread’s subscription state, so the panel can’t label the toggle correctly. Messages themselves are pinned and unpinned from the Message List action sheet; wire setOnMessageClickListener to jump back to a message in context.

The Pinned Messages screen: a titled screen with a back arrow, listing the pinned messages of one conversation as full bubbles grouped by sender and date. Each bubble carries a pin glyph beside its timestamp, and a media message shows its image with the caption beneath.

Quick Start

Kotlin (XML Views)
Jetpack Compose

Add the component to your layout XML:

activity_pinned_messages.xml

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/main"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.cometchat.uikit.kotlin.presentation.pinnedmessages.CometChatPinnedMessages
        android:id="@+id/pinned_messages"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</FrameLayout>

Scope it to the conversation and wire the callbacks:

PinnedMessagesActivity.kt

class PinnedMessagesActivity : AppCompatActivity() {

    private lateinit var pinnedMessages: CometChatPinnedMessages

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_pinned_messages)

        pinnedMessages = findViewById(R.id.pinned_messages)

        // Scope to the conversation — set exactly one of user / group
        user?.let { pinnedMessages.setUser(it) }
        group?.let { pinnedMessages.setGroup(it) }

        pinnedMessages.setOnMessageClickListener { message ->
            // Navigate to the message in its conversation,
            // e.g. finish with a result and call messageList.gotoMessage(message.id)
        }

        pinnedMessages.setOnBackClickListener { finish() }
    }
}

CometChatPinnedMessages(
    user = user,          // or group = group — set exactly one
    onMessageClick = { message ->
        // Navigate to the message in its conversation
    },
    onBackClick = { navController.popBackStack() }
)

Actions and Events

Callback Methods

Method (Views) / Param (Compose)	Description
`setOnMessageClickListener` / `onMessageClick`	Fired when a row is tapped. Receives the `BaseMessage`; navigate to it in its conversation.
`setOnBackClickListener` / `onBackClick`	Fired when the toolbar back button is pressed.

SDK Events (Real-Time, Automatic)

The list keeps itself up to date — when the logged-in user pins or unpins a message anywhere in the app, the row is added or removed without a refetch, via the MessagePinned / MessageUnpinned events on the UI Kit event bus; see Events. Pins made by other participants appear when the list is next opened or refetched (server-side real-time delivery for pin events is pending rollout).

Functionality

Real bubbles — each row hosts the message’s actual bubble (text, image, video, audio, file), left-aligned with a name • date header and the sender’s avatar. Your own messages render with the outgoing (primary-color) bubble style and the name You.
Long-press menu — long-press a row for message actions: Message info, Copy, Translate (text messages), Unpin, and Delete. Unpinning asks for confirmation before it is performed.
Jump to message — tapping a row emits the message through the click callback so you can open the conversation and scroll to it.
Empty state — a built-in empty state (“No pinned messages yet”) is shown when the conversation has no pinned messages.
Read-only — the screen never marks messages as read and does not affect unread counts or receipts.

ViewModel

The screen is backed by CometChatPinnedMessagesViewModel (in the shared core module), which fetches via MessagesRequestBuilder().setPinned(true) scoped to the set user or group, applies optimistic unpin with revert-on-error, and observes the event bus for live upkeep. In Compose you can inject your own instance through the viewModel parameter.

Next Steps

Message List — where messages are pinned and unpinned, and where the bubble pin indicator appears.
Message Header — the built-in “Pinned messages” menu entry point.
Saved Messages — the private, cross-conversation counterpart.
Pin A Message (SDK) — the underlying SDK APIs.

​Where It Fits

​Quick Start

​Actions and Events

​Callback Methods

​SDK Events (Real-Time, Automatic)

​Functionality

​ViewModel

​Next Steps

Where It Fits

Quick Start

Actions and Events

Callback Methods

SDK Events (Real-Time, Automatic)

Functionality

ViewModel

Next Steps