hritika-cometchat · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026 · Sep 15, 2026 · Sep 16, 2026
diff --git a/docs.json b/docs.json
@@ -1867,13 +1867,13 @@
                             "pages": [
                               "ui-kit/android/guide-overview",
                               "ui-kit/android/guide-threaded-messages",
-                              "ui-kit/android/guide-thread-subscription",
                               "ui-kit/android/guide-pin-and-save-messages",
                               "ui-kit/android/guide-block-unblock-user",
                               "ui-kit/android/guide-new-chat",
                               "ui-kit/android/guide-message-privately",
                               "ui-kit/android/guide-call-log-details",
                               "ui-kit/android/guide-group-chat",
+                              "ui-kit/android/guide-text-color",
                               "ui-kit/android/custom-text-formatter-guide",
                               "ui-kit/android/mentions-formatter-guide",
                               "ui-kit/android/shortcut-formatter-guide",
@@ -6979,6 +6979,10 @@
       "source": "/ui-kit/react/property-changes",
       "destination": "/ui-kit/react/migration-property-changes"
     },
+    {
+      "source": "/ui-kit/android/guide-thread-subscription",
+      "destination": "/ui-kit/android/guide-threaded-messages#thread-subscription"
+    },
     {
       "source": "/ui-kit/android/property-changes",
       "destination": "/ui-kit/android/upgrading-from-v4"

diff --git a/images/pin.png b/images/pin.png
diff --git a/images/save.png b/images/save.png
@@ -1,9 +1,9 @@
 ---
 title: "Conversations"
 description: "Scrollable list of recent one-on-one and group conversations for the logged-in user."
 ---

 `CometChatConversations` renders a scrollable list of recent conversations with real-time updates for new messages, typing indicators, read receipts, and user presence.

 <Frame>
  <img src="/images/f2c77c5b-Conversation-ac41cc6650fbb941c64f389aee910dbc.png" />
@@ -165,6 +165,15 @@
 | With tags | `.setTags(listOf("vip")).withTags(true)` |
 | Filter by user tags | `.withUserAndGroupTags(true).setUserTags(listOf("premium"))` |
 | Filter by group tags | `.withUserAndGroupTags(true).setGroupTags(listOf("support"))` |
+| Pinned conversations only | `.setPinnedBy("system,me")` |
+
+The default list already arrives pin-ordered, so `setPinnedBy` is only for a **dedicated pinned list** — `"me"` for the user's own pins, `"system"` for admin/global pins, `"system,me"` for both. See [Pin A Conversation (SDK)](/sdk/android/v5/pin-conversation).
+
+```kotlin lines
+conversations.setConversationsRequestBuilder(
+    ConversationsRequest.ConversationsRequestBuilder().setPinnedBy("system,me")
+)
+```
 
 <Warning>
 Pass the builder object, not the result of `.build()`. The component calls `.build()` internally. Default page size is 30 with infinite scroll.
@@ -419,6 +428,52 @@
 
 ---
 
+## Pinning Conversations
+
+A pinned conversation sits at the top of the list and holds that position even as new messages arrive in other chats. The pin is **private to the logged-in user** — nobody else sees it — and it syncs to that user's other devices.
+
+When the feature is enabled for your app, the long-press menu includes **Pin conversation** / **Unpin conversation** with no wiring needed: pinning applies immediately with a toast, unpinning asks for confirmation first, and a pinned row shows a pin indicator next to its timestamp.
+
+<Warning>
+**Pin Conversation must be enabled for your app** through the `features.ux.conversations.pinned.enabled` app setting. Until it is, the option never renders, and a direct SDK call rejects with `ERR_FEATURE_NOT_ACCESSIBLE`. The UI Kit reads that setting itself at login and on every reconnect — there is no app code to write. Read it yourself with `CometChatUIKit.isPinConversationEnabled()` when you need to gate your own entry point.
+</Warning>
+
+`setPinConversationOptionVisibility(View.GONE)` (Compose: `hidePinOption = true`) hides the option on one particular list. It is **ANDed** with the Dashboard flag, so the option renders only when both allow it.
+
+<Tabs>
+<Tab title="Kotlin (XML Views)">
+```kotlin lines
+conversations.setPinConversationOptionVisibility(View.GONE)
+```
+</Tab>
+<Tab title="Jetpack Compose">
+```kotlin lines
+CometChatConversations(
+    hidePinOption = true
+)
+```
+</Tab>
+</Tabs>
+
+### Reading pin state
+
+```kotlin lines
+val isPinned = conversation.isPinned              // pinnedAt > 0
+
+// An admin/global pin. A user can neither pin nor unpin one of these
+// (the server rejects it with ERR_SYSTEM_PINNED_CONVERSATION), so hide
+// or disable the pin/unpin control.
+val isSystemPinned = conversation.isSystemPinned  // pinnedBy == "app_system"
+```
+
+<Note>
+The conversation list arrives **already pin-ordered** from the server — admin pins first, then the user's own, then everything else — and each row carries its pin attributes. You do not need a separate fetch to render a pinned section. To render a pinned-**only** list, use the `setPinnedBy` filter shown in [Filtering Conversations](#filtering-conversations).
+</Note>
+
+For pins made elsewhere, the Chat SDK exposes `CometChat.ConversationListener` with `onConversationPinned` / `onConversationUnpinned`. See [Pin A Conversation (SDK)](/sdk/android/v5/pin-conversation) for those callbacks, the pin methods, and the per-user pin limit underneath.
+
+---
+
 ## Functionality
 
 | Method (Kotlin XML) | Compose Parameter | Description |
@@ -431,7 +486,7 @@
 | `setSelectionMode(MULTIPLE)` | `selectionMode = MULTIPLE` | Enable selection mode |
 | `setTitle("Chats")` | `title = "Chats"` | Custom toolbar title |
 | `setSearchPlaceholderText("Search...")` | `searchPlaceholderText = "Search..."` | Search placeholder |
-| `setPinConversationOptionVisibility(View.GONE)` | — | Hide the built-in Pin/Unpin conversation option |
+| `setPinConversationOptionVisibility(View.GONE)` | `hidePinOption = true` | Hide the built-in Pin/Unpin conversation option |
 
 ---
 
@@ -709,18 +764,6 @@
 </Tab>
 </Tabs>
 
-### Built-in Pin Conversation Option
-
-When the Pin Conversation feature is enabled for your app (`CometChatUIKit.isPinConversationEnabled()`), the long-press menu automatically includes **Pin conversation** / **Unpin conversation** — no wiring needed. Pinning applies immediately with a toast; unpinning asks for confirmation first. Pinned conversations display a pin indicator next to the timestamp and stay at the **top of the list**, holding their position even as new messages arrive in other chats. Hide the option with `setPinConversationOptionVisibility(View.GONE)`.
-
-To render a pinned-only list, pass a request builder with the pinned filter — see [Pin A Conversation (SDK)](/sdk/android/v5/pin-conversation):
-
-```kotlin lines
-conversations.setConversationsRequestBuilder(
-    ConversationsRequest.ConversationsRequestBuilder().setPinnedBy("system,me")
-)
-```
-
 ---
 
 ## Common Patterns

@@ -7,7 +7,7 @@

 | Field | Value |
 | --- | --- |
 | Packages | `com.cometchat:chatuikit-kotlin-android` (Kotlin XML Views), `com.cometchat:chatuikit-compose-android` (Jetpack Compose) |
 | Required setup | `CometChatUIKit.init()` then `CometChatUIKit.login()` — must complete before rendering any component |
 | Core features | Instant Messaging, Media Sharing, Read Receipts, Mark as Unread, Typing Indicator, User Presence, Reactions, Mentions, Rich Text Formatting, Quoted Reply, Search, Threaded Conversations, Moderation, Report Message, Group Chat |
 | Key components | `CometChatConversations`, `CometChatMessageList`, `CometChatMessageComposer`, `CometChatMessageHeader`, `CometChatUsers`, `CometChatGroups`, `CometChatGroupMembers`, `CometChatMessageInformation`, `CometChatThreadHeader` |
@@ -147,15 +147,33 @@
 | [CometChatSavedMessages](/ui-kit/android/saved-messages) | Full-screen, private list of the user's saved messages. |
 | [CometChatMessageHeader](/ui-kit/android/message-header) | Built-in "Pinned messages" menu entry point. |
 
-See the [Pin & Save Messages guide](/ui-kit/android/guide-pin-and-save-messages) for end-to-end wiring.
+Each feature is switched on per app, and each carries its own cap:
+
+| App setting | Controls |
+| --- | --- |
+| `features.ux.messages.pinned.enabled` | Whether the pin options and screen render at all |
+| `features.ux.messages.pinned.limit` | Pinned messages per conversation |
+| `features.ux.messages.saved.enabled` | Whether the save options and screen render at all |
+| `features.ux.messages.saved.limit` | Saved messages per user |
+
+The UI Kit reads the feature flags at login, so no wiring is needed to show or hide the options. When a user reaches a cap, the kit shows a toast naming the limit — no extra handling required. For a full walkthrough, see the [Pin & Save Messages guide](/ui-kit/android/guide-pin-and-save-messages).
 
 ## Pin Conversations
 
 Keep the chats that matter at the top. Users pin a conversation from the long-press menu; pinned conversations show a pin indicator and stay above the rest of the list.
 
 | Component | Role |
 | --- | --- |
-| [CometChatConversations](/ui-kit/android/conversations) | Provides the Pin/Unpin conversation option, the row indicator, and pinned-first ordering. |
+| [CometChatConversations](/ui-kit/android/conversations#pinning-conversations) | Provides the Pin/Unpin conversation option, the row indicator, and pinned-first ordering. |
+
+Conversation pinning is switched on per app, and carries its own cap:
+
+| App setting | Controls |
+| --- | --- |
+| `features.ux.conversations.pinned.enabled` | Whether the pin/unpin conversation option renders |
+| `features.ux.conversations.pinned.limit` | Pinned conversations per user |
+
+A conversation can also be **system-pinned** app-wide by your app. System pins always sort above user pins, and a user can neither pin nor unpin them. See [Conversations → Pinning Conversations](/ui-kit/android/conversations#pinning-conversations).
 
 ## Rich Text Formatting
 
@@ -169,6 +187,7 @@
 | --- | --- |
 | [CometChatMessageComposer](/ui-kit/android/message-composer) | Provides a built-in rich text editor with formatting toolbar and text selection menu items for bold, italic, strikethrough, code, links, lists, blockquotes, and code blocks. |
 | [CometChatMessageList](/ui-kit/android/message-list) | Renders formatted messages with the appropriate styling automatically applied, ensuring that rich text formatting is displayed exactly as intended by the sender. |
+
 ## Threaded Conversations
 
 Respond directly to a specific message, keeping conversations organized.
@@ -183,16 +202,16 @@
 | [CometChatMessageComposer](/ui-kit/android/message-composer) | Allows composing messages within a thread. |
 | [CometChatMessageList](/ui-kit/android/message-list) | Displays threaded messages in context. |
 
-## Thread Subscription
+### Thread Subscription
 
-Let users subscribe to or unsubscribe from a thread to control whether its replies notify them. Opt-in feature — enable it with `UIKitSettings.setEnableThreadSubscription(true)`.
+Let users subscribe to or unsubscribe from a thread to control whether its replies notify them. Enabled by default from **v6.1.0** — remove a surface with `setThreadSubscriptionOptionVisibility(View.GONE)` or `setThreadSubscriptionVisibility(View.GONE)`. On **v6.0.x** the feature is opt-in via `UIKitSettings.setEnableThreadSubscription(true)`.
 
 | Component | Role |
 | --- | --- |
 | [CometChatMessageList](/ui-kit/android/message-list) | Provides the Subscribe to thread / Unsubscribe from thread option in the message action sheet. |
 | [CometChatThreadHeader](/ui-kit/android/threaded-messages-header) | Shows the subscription bell on the thread view. |
 
-See the [Thread Subscription guide](/ui-kit/android/guide-thread-subscription) for setup and behavior.
+Subscriptions are also created automatically by the **server**, so they apply to any app on the SDK, not just the UI Kit: sending a message subscribes you to that message's own thread, posting a reply subscribes you to that thread, and being @mentioned in a reply subscribes you. The kit reflects these the moment they happen. See [Threaded Messages → Thread Subscription](/ui-kit/android/guide-threaded-messages#thread-subscription) for setup and behavior.
 
 ## Quoted Replies
 

@@ -1,6 +1,6 @@
 ---
 title: "Custom Text Formatter"
-sidebarTitle: "Custom Text Formatter"
+sidebarTitle: "Text Formatter Base Class"
 description: "Extend CometChatTextFormatter to build custom inline text patterns with tracking characters and suggestion lists."
 ---
 
@@ -9,7 +9,7 @@
 | Field | Value |
 | --- | --- |
 | Packages | `com.cometchat:chatuikit-kotlin-android` · `com.cometchat:chatuikit-compose-android` |
 | Key class | `CometChatTextFormatter` (abstract base class for custom formatters) |
 | Required setup | `CometChatUIKit.init()` then `CometChatUIKit.login("UID")` |
 | Purpose | Extend to create custom inline text patterns with tracking characters, suggestion lists, and span formatting |
 | Features | Tracking character activation, suggestion list, span formatting per context (composer, bubbles, conversations), pre-send hooks |
@@ -18,7 +18,7 @@

 </Accordion>

 `CometChatTextFormatter` is an abstract class for formatting text in the message composer and message bubbles. Extend it to build custom formatters — hashtags, shortcuts, or any pattern triggered by a tracking character.

 | Capability | Description |
 | --- | --- |
@@ -46,7 +46,7 @@
 </Tab>
 <Tab title="Jetpack Compose">
 ```kotlin lines
 // Same class — formatters are shared between both modules
 class HashTagFormatter : CometChatTextFormatter('#') {
    private val suggestions: MutableList<SuggestionItem> = ArrayList()
 }

@@ -8,7 +8,7 @@
 | Field | Value |
 | --- | --- |
 | Kotlin (XML Views) | `com.cometchat:chatuikit-kotlin-android` |
 | Jetpack Compose | `com.cometchat:chatuikit-compose-android` |
 | Import | `com.cometchat.uikit.core.events.CometChatEvents` |
 | Event flows | `CometChatEvents.messageEvents`, `CometChatEvents.callEvents`, `CometChatEvents.conversationEvents`, `CometChatEvents.groupEvents`, `CometChatEvents.userEvents`, `CometChatEvents.uiEvents` |
 | Pattern | Kotlin `SharedFlow` with sealed class event types — collect in `viewModelScope` or `lifecycleScope` |
@@ -71,14 +71,14 @@
 | `CometChatMessageEvent.MessagePinned(message)` | Triggered when a message is pinned. |
 | `CometChatMessageEvent.MessageUnpinned(message)` | Triggered when a message is unpinned. |
 | `CometChatMessageEvent.MessageSaved(message)` | Triggered when the logged-in user saves a message. |
 | `CometChatMessageEvent.MessageUnsaved(message)` | Triggered when the logged-in user unsaves a message. |

 **Collecting events:**

 <Tabs>
 <Tab title="Kotlin (XML Views)">
 ```kotlin
 // In an Activity or Fragment — use lifecycleScope
 lifecycleScope.launch {
    CometChatEvents.messageEvents.collect { event ->
        when (event) {
@@ -155,7 +155,7 @@

 ### Thread Events

 `CometChatEvents.threadEvents` emits `CometChatThreadEvent` instances when the logged-in user subscribes to or unsubscribes from a message thread, so every surface showing a subscription control can stay in sync without a refetch.

 Every event on this bus is published by the UI Kit itself — the Chat SDK has no thread listener, and a `subscribeToThread()` / `unsubscribeFromThread()` callback *is* the acknowledgement. Because surfaces do not share message instances, a handler should update its own state **and** stamp the flag onto the message objects it holds with `BaseMessage.setThreadSubscribed()`.

@@ -181,7 +181,7 @@
 }
 ```
 
-See the [Thread Subscription guide](/ui-kit/android/guide-thread-subscription) for the feature end to end.
+See [Threaded Messages → Thread Subscription](/ui-kit/android/guide-threaded-messages#thread-subscription) for the feature end to end.
 
 ### Call Events
 
@@ -543,7 +543,7 @@
 </Tab>
 </Tabs>

 > **About `CardActionClicked`:** The UI Kit renders card bubbles automatically (`CometChatCardBubble`) and emits this event when a user taps an action inside one — so a single subscriber handles every card action across your app. `event.message` is a `CardMessage` for standalone [card messages](/sdk/android/v5/send-message#card-message) and an `AIAssistantMessage` for cards embedded in AI agent replies. `event.actionEvent` is typed `Any`; import and cast it to `com.cometchat.cards.actions.CometChatCardActionEvent` to read its `action`, `elementId`, and `cardJson`.

 ---

@@ -551,8 +551,8 @@

 Since `SharedFlow` collection is coroutine-based, lifecycle management is handled automatically:

 - In XML Views, use `lifecycleScope.launch` — the coroutine is cancelled when the lifecycle owner is destroyed.
 - In Jetpack Compose, use `LaunchedEffect` — the coroutine is cancelled when the composable leaves the composition.

 No manual `removeListener` calls are needed, unlike the old static listener pattern.


@@ -16,7 +16,7 @@

 </Accordion>

 > This page indexes focused, task‑oriented feature guides for the Android UI Kit. Each guide shows how to implement a specific capability end‑to‑end using UIKit components. Guides include both **Kotlin (XML Views)** and **Jetpack Compose** examples where applicable.

 ## When to Use These Guides

@@ -27,7 +27,7 @@
 | Module | Description |
 |:-------|:------------|
 | `chatuikit-kotlin` | Traditional XML-based Views for use with Activities and Fragments. |
 | `chatuikit-compose` | Jetpack Compose components for declarative UI. |

 ## Guide Directory

@@ -41,7 +41,8 @@
 | [Threaded Messages](/ui-kit/android/guide-threaded-messages) | Threaded replies: open parent message context, list replies, compose with parent linkage. |
 | [Search Messages](/ui-kit/android/guide-search-messages) | Full-text message search across conversations with result routing and navigation. |
 | [AI Agent](/ui-kit/android/guide-ai-agent) | Build an AI-powered agent that responds to user messages using CometChat's AI features. |
-| [Custom Text Formatter](/ui-kit/android/custom-text-formatter-guide) | Extend `CometChatTextFormatter` to build custom inline text patterns with tracking characters and suggestion lists. |
+| [Color Selected Text](/ui-kit/android/guide-text-color) | Add a color button to the composer toolbar that colors selected text, rendered in the sent message. |
+| [Text Formatter Base Class](/ui-kit/android/custom-text-formatter-guide) | Extend `CometChatTextFormatter` to build custom inline text patterns with tracking characters and suggestion lists. |
 | [Mentions Formatter](/ui-kit/android/mentions-formatter-guide) | Format @mentions with styled tokens, suggestion lists, and click handling. |
 | [ShortCut Formatter](/ui-kit/android/shortcut-formatter-guide) | Add shortcut text expansion to the message composer via the message-shortcuts extension. |
 

@@ -14,7 +14,7 @@
 | **Save Message** | All conversations | Only the acting user | Action-sheet option, bubble indicator, [Saved Messages](/ui-kit/android/saved-messages) screen |
 | **Pin Conversation** | Conversation list | Only the acting user | Long-press option + pin indicator in [Conversations](/ui-kit/android/conversations) |

 The options, confirmation dialogs, toasts and indicators are built into the UI Kit components. The only integration work is wiring the two full-screen views into your navigation.

 ## Prerequisites

@@ -29,11 +29,11 @@

 ## Pin & Save in the Message List

 With the features enabled, [CometChatMessageList](/ui-kit/android/message-list) automatically adds **Pin message / Unpin message** and **Save message / Unsave message** to the long-press action sheet for text and media messages. The labels toggle with the message's current state.

 - **Pin** permission is enforced by the **server**, not by the UI Kit: the Pin/Unpin option is shown to every participant, and a user who lacks permission gets a "you don't have permission" toast (`ERR_PERMISSION_DENIED`) when they tap it. Everyone sees pinned indicators. Build custom pin UI the same way — show the action and handle the denial, rather than trying to predict the verdict client-side.
 - **Save** has no role gating — every user can save any message.
 - **Pin** and **Save** apply immediately and show a toast (*Message pinned*, *Message saved*, …); **Unpin** and **Unsave** ask for confirmation first. If a pin or save limit is exceeded, the limit toast is generated from the server's response automatically.
 - Pinned and saved messages show **indicators in the bubble footer** (a filled pin / bookmark before the timestamp), updating live for all bubble types.

 ## Step 1: Open Pinned Messages from the Chat Header
@@ -144,15 +144,46 @@
 </Tab>
 </Tabs>
 
+## App Settings and Limits
+
+Each feature is switched on per app, and each carries a cap on how many items a user may pin or save. Both are configured as app settings in the dashboard:
+
+| Setting | Controls |
+| --- | --- |
+| `features.ux.messages.pinned.enabled` | Whether the pin options and screen render at all |
+| `features.ux.messages.pinned.limit` | Pins per conversation |
+| `features.ux.messages.saved.enabled` | Whether the save options and screen render at all |
+| `features.ux.messages.saved.limit` | Saves per user |
+| `features.ux.conversations.pinned.enabled` | Whether the pin/unpin conversation option renders |
+| `features.ux.conversations.pinned.limit` | Pinned conversations per user (see [Conversations](/ui-kit/android/conversations#pinning-conversations)) |
+
+When a user hits a cap, the UI Kit shows a toast explaining the limit — you don't need to handle the error yourself.
+
+### Error Codes
+
+The built-in options turn these rejections into toasts. If you build custom pin or save UI on the SDK, handle them yourself:
+
+| Code | Meaning |
+| --- | --- |
+| `ERR_PERMISSION_DENIED` | The acting user's role may not pin or unpin here. Pin and unpin are gated independently. |
+| `ERR_PINNED_MESSAGES_LIMIT_EXCEEDED` | The conversation's pin cap was reached. |
+| `ERR_SAVED_MESSAGES_LIMIT_EXCEEDED` | The user's save cap was reached. |
+| `ERR_PINNED_CONVERSATIONS_LIMIT_EXCEEDED` | The user's conversation pin cap was reached. |
+| `ERR_SYSTEM_PINNED_CONVERSATION` | The conversation is **system-pinned** for all users by the app, so a user can neither pin nor unpin it. |
+| `ERR_MESSAGE_NO_ACCESS` | The user has no access to that message — for example they are not a participant in its conversation. |
+| `ERR_FEATURE_NOT_ACCESSIBLE` | The feature is not enabled for the app. |
+
+The limit and system-pin codes are also listed in the [Error Guide](/articles/error-guide).
+
 ## Live Updates
 
-On the acting user's device, all surfaces stay in sync through the UI Kit event bus — pinning from the action sheet updates the bubble indicator and the Pinned Messages screen without a refetch. Delivery of pin/save events to other participants and to the user's other devices activates once server-side real-time delivery for these features is rolled out; until then, other clients pick the change up on their next fetch. If you build custom UI, observe the `MessagePinned` / `MessageUnpinned` / `MessageSaved` / `MessageUnsaved` events; see [Events](/ui-kit/android/events).
+On the acting user's device, all surfaces stay in sync through the UI Kit event bus — pinning from the action sheet updates the bubble indicator and the Pinned Messages screen without a refetch. Delivery of message pin/save events to other participants and to the user's other devices activates once server-side real-time delivery for these features is rolled out; until then, other clients pick the change up on their next fetch. If you build custom UI, observe the `MessagePinned` / `MessageUnpinned` / `MessageSaved` / `MessageUnsaved` events; see [Events](/ui-kit/android/events).
 
 ## Summary / Feature Matrix
 
 | Capability | Built-in | Your wiring |
 | --- | --- | --- |
 | Action-sheet options, confirm dialogs, toasts | ✅ | — |
 | Bubble footer indicators | ✅ | — |
 | Pinned/Saved screens (list, unpin/unsave, empty states, live upkeep) | ✅ | Host + navigate |
 | Chat-header "Pinned messages" entry | ✅ (opt-in) | `setShowPinnedMessagesOption(true)` + click listener |