docs(react,sdk/javascript): align thread subscription and pin/save with other platforms

sdk/javascript/pin-conversation.mdx

@@ -84,7 +84,7 @@
   </Tab>
 </Tabs>
 
-A user cannot unpin an admin-global pin — that call is rejected with `ERR_ACTION_NOT_ALLOWED`. Hide or disable the unpin control for conversations you know are system-pinned.
+A user cannot unpin an admin-global pin — that call is rejected with `ERR_SYSTEM_PINNED_CONVERSATION`. Hide or disable the unpin control for conversations you know are system-pinned.
 
 ## Fetch Pinned Conversations
 
@@ -95,7 +95,7 @@
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
     let conversationsRequest: CometChat.ConversationsRequest =
       new CometChat.ConversationsRequestBuilder()
         .setPinnedBy([CometChat.PINNED_BY.SYSTEM, CometChat.PINNED_BY.ME])
         .setLimit(30)
@@ -113,7 +113,7 @@
   </Tab>
   <Tab title="JavaScript">
     ```javascript
     let conversationsRequest = new CometChat.ConversationsRequestBuilder()
       .setPinnedBy([CometChat.PINNED_BY.ME])
       .setLimit(30)
       .build();
@@ -218,7 +218,7 @@
   <Tab title="TypeScript">
     ```typescript
     let limit: number | null = await CometChat.getPinnedConversationsLimit();
     let systemLimit: number | null =
       await CometChat.getSystemPinnedConversationsLimit();
     ```
   </Tab>
@@ -233,6 +233,53 @@
 
 Both resolve to `null` when the app settings carry no value. `getSystemPinnedConversationsLimit()` is the separate admin/global cap, enforced independently.
 
+## Error Handling
+
+`pinConversation()` and `unpinConversation()` reject with a `CometChatException`. Branch on the code rather than the message text:
+
+| Code | Meaning |
+| --- | --- |
+| `ERR_PINNED_CONVERSATIONS_LIMIT_EXCEEDED` | The user's conversation pin cap was reached (HTTP 400). |
+| `ERR_UID_NOT_FOUND` / `ERR_GUID_NOT_FOUND` | The peer named by `conversationWith` does not exist (HTTP 404). |
+| `ERR_SYSTEM_PINNED_CONVERSATION` | The conversation is **system-pinned** (admin-global), which a user may never unpin. |
+
+Pins are per-user, so pinning a conversation never affects anyone else's list. Check `conversation.isSystemPinned()` and hide the unpin control rather than letting the call fail.
+
+Both calls are idempotent: unpinning a conversation that was never pinned succeeds rather than erroring.
+
+<Tabs>
+  <Tab title="TypeScript">
+    ```typescript
+    CometChat.pinConversation("uid", "user").then(
+      (response: CometChat.BaseMessage) => {
+        console.log("Done:", response);
+      },
+      (error: CometChat.CometChatException) => {
+        // e.g. code: "ERR_PINNED_CONVERSATIONS_LIMIT_EXCEEDED"
+        console.log(error.code, error.message);
+      }
+    );
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```javascript
+    CometChat.pinConversation("uid", "user").then(
+      (response) => {
+        console.log("Done:", response);
+      },
+      (error) => {
+        // e.g. code: "ERR_PINNED_CONVERSATIONS_LIMIT_EXCEEDED"
+        console.log(error.code, error.message);
+      }
+    );
+    ```
+  </Tab>
+</Tabs>
+
+<Note>
+Read the cap from `CometChat.getPinnedConversationsLimit()`, which resolves to the configured cap, or `null` when unset — so you can name the exact number in your own copy without parsing it out of the error text.
+</Note>
+
 ## Feature Availability
 
 <Tabs>

sdk/javascript/pin-message.mdx

@@ -8,7 +8,7 @@
 <Note>
   Pinning is a moderation action. Only an Admin or Moderator — a group owner
   included — may pin or unpin. The server is the authority: a member's call is
-  rejected with `ERR_ACTION_NOT_ALLOWED`.
+  rejected with `ERR_PERMISSION_DENIED`.
 </Note>
 
 ## Pin a Message
@@ -18,7 +18,7 @@
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
     let messageId: number = 100;
 
     CometChat.pinMessage(messageId).then(
       (message: CometChat.BaseMessage) => {
@@ -32,7 +32,7 @@
   </Tab>
   <Tab title="JavaScript">
     ```javascript
     let messageId = 100;
 
     CometChat.pinMessage(messageId).then(
       (message) => {
@@ -46,7 +46,7 @@
   </Tab>
 </Tabs>
 
 Pinning is **idempotent**, and a message has a single pinner: re-pinning an already pinned message updates `pinnedBy` and `pinnedAt` to the most recent pinner rather than failing.
 
 ## Unpin a Message
 
@@ -86,7 +86,7 @@
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
     let messagesRequest: CometChat.MessagesRequest =
       new CometChat.MessagesRequestBuilder()
         .setUID("cometchat-uid-1")
         .setPinned(true)
@@ -105,7 +105,7 @@
   </Tab>
   <Tab title="JavaScript">
     ```javascript
     let messagesRequest = new CometChat.MessagesRequestBuilder()
       .setGUID("cometchat-guid-1")
       .setPinned(true)
       .setLimit(50)
@@ -168,7 +168,7 @@
 | ------------------- | -------------------------------------------------------------------------- |
 | `isPinned()`        | `true` when the message is pinned.                                          |
 | `getPinnedAt()`     | The pin timestamp, or `undefined`.                                          |
 | `getPinnedBy()`     | The UID of the most recent pinner, or `undefined`.                          |
 | `isSystemPinned()`  | `true` for an admin/global pin. Render it as a system pin, not as a user.   |
 
 ## Real-time Pin Events
@@ -218,7 +218,7 @@
   <Tab title="TypeScript">
     ```typescript
     let limit: number | null = await CometChat.getPinnedMessagesLimit();
     let systemLimit: number | null =
       await CometChat.getSystemPinnedMessagesLimit();
 
     if (limit !== null && pinnedCount >= limit) {
@@ -239,6 +239,50 @@
 
 Both resolve to `null` when the app settings carry no value — show generic copy in that case rather than guessing a number. `getSystemPinnedMessagesLimit()` is the separate cap for admin/global pins, enforced independently of the per-user one.
 
+## Error Handling
+
+`pinMessage()` and `unpinMessage()` reject with a `CometChatException`. Branch on the code rather than the message text:
+
+| Code | Meaning |
+| --- | --- |
+| `ERR_PERMISSION_DENIED` | The acting user's role may not pin or unpin here (HTTP 403). Pin and unpin are gated independently. |
+| `ERR_PINNED_MESSAGES_LIMIT_EXCEEDED` | The conversation's pin cap was reached (HTTP 400). |
+| `ERR_MESSAGE_ID_NOT_FOUND` | No message with that id — it never existed, or it was deleted (HTTP 404). |
+| `ERR_MESSAGE_NO_ACCESS` | The user has no access to that message — for example they are not a participant in its conversation (HTTP 403). |
+
+<Tabs>
+  <Tab title="TypeScript">
+    ```typescript
+    CometChat.pinMessage("1").then(
+      (response: CometChat.BaseMessage) => {
+        console.log("Done:", response);
+      },
+      (error: CometChat.CometChatException) => {
+        // e.g. code: "ERR_PINNED_MESSAGES_LIMIT_EXCEEDED"
+        console.log(error.code, error.message);
+      }
+    );
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```javascript
+    CometChat.pinMessage("1").then(
+      (response) => {
+        console.log("Done:", response);
+      },
+      (error) => {
+        // e.g. code: "ERR_PINNED_MESSAGES_LIMIT_EXCEEDED"
+        console.log(error.code, error.message);
+      }
+    );
+    ```
+  </Tab>
+</Tabs>
+
+<Note>
+Read the cap from `CometChat.getPinnedMessagesLimit()`, which resolves to the configured cap, or `null` when unset — so you can name the exact number in your own copy without parsing it out of the error text.
+</Note>
+
 ## Feature Availability
 
 Check whether Pin Message is enabled for your app before showing pin actions.

sdk/javascript/save-message.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Save A Message"
 description: "Save and unsave messages privately, fetch the saved list across conversations, and listen for save events with the CometChat JavaScript SDK."
 ---
 
 Saving bookmarks a message for the logged-in user. Unlike a pin, a save is **private and cross-conversation**: nobody else can see it, no role is required, and the saved list spans every conversation the user is part of.
@@ -17,7 +17,7 @@
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
     let messageId: number = 100;
 
     CometChat.saveMessage(messageId).then(
       (message: CometChat.BaseMessage) => {
@@ -31,7 +31,7 @@
   </Tab>
   <Tab title="JavaScript">
     ```javascript
     let messageId = 100;
 
     CometChat.saveMessage(messageId).then(
       (message) => {
@@ -47,7 +47,7 @@
 
 Saving is idempotent — saving an already saved message succeeds rather than failing.
 
 ## Unsave a Message
 
 <Tabs>
   <Tab title="TypeScript">
@@ -85,7 +85,7 @@
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
     let messagesRequest: CometChat.MessagesRequest =
       new CometChat.MessagesRequestBuilder()
         .setSaved(true)
         .setLimit(50)
@@ -103,7 +103,7 @@
   </Tab>
   <Tab title="JavaScript">
     ```javascript
     let messagesRequest = new CometChat.MessagesRequestBuilder()
       .setSaved(true)
       .setLimit(50)
       .build();
@@ -177,7 +177,7 @@
 
 ## Real-time Save Events
 
 Save and unsave are **private multi-device** events: they are delivered to the user's other logged-in sessions so a save on the phone shows up on the desktop. Add the callbacks to your existing `MessageListener`.
 
 <Tabs>
   <Tab title="TypeScript">
@@ -246,6 +246,51 @@
 
 It resolves to `null` when the app settings carry no value — show generic copy in that case rather than guessing a number.
 
+## Error Handling
+
+`saveMessage()` and `unsaveMessage()` reject with a `CometChatException`. Branch on the code rather than the message text:
+
+| Code | Meaning |
+| --- | --- |
+| `ERR_SAVED_MESSAGES_LIMIT_EXCEEDED` | The user's save cap was reached (HTTP 400). |
+| `ERR_MESSAGE_ID_NOT_FOUND` | No message with that id — it never existed, or it was deleted (HTTP 404). |
+| `ERR_MESSAGE_NO_ACCESS` | The user has no access to that message — for example they are not a participant in its conversation (HTTP 403). |
+
+Saving is per-user, so there is no role gate: any participant can save a message they have access to, up to the cap.
+
+<Tabs>
+  <Tab title="TypeScript">
+    ```typescript
+    CometChat.saveMessage("1").then(
+      (response: CometChat.BaseMessage) => {
+        console.log("Done:", response);
+      },
+      (error: CometChat.CometChatException) => {
+        // e.g. code: "ERR_SAVED_MESSAGES_LIMIT_EXCEEDED"
+        console.log(error.code, error.message);
+      }
+    );
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```javascript
+    CometChat.saveMessage("1").then(
+      (response) => {
+        console.log("Done:", response);
+      },
+      (error) => {
+        // e.g. code: "ERR_SAVED_MESSAGES_LIMIT_EXCEEDED"
+        console.log(error.code, error.message);
+      }
+    );
+    ```
+  </Tab>
+</Tabs>
+
+<Note>
+Read the cap from `CometChat.getSavedMessagesLimit()`, which resolves to the configured cap, or `null` when unset — so you can name the exact number in your own copy without parsing it out of the error text.
+</Note>
+
 ## Feature Availability
 
 <Tabs>

sdk/javascript/thread-subscription.mdx

@@ -139,7 +139,7 @@
 
 That default is what makes the flag meaningful on your own messages. Since it starts out `true`, a `false` on a message **you sent** — read from a fetch, not the socket — is not silence. It means you unsubscribed, and nothing should quietly put you back.
 
 This only holds for a message you sent and obtained from a fetch. On anyone else's message, or on anything socket-delivered, `false` still just means the server was not asked.
 
 ### Keeping your own copies in sync
 
@@ -218,7 +218,7 @@
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
     let threadsRequest: CometChat.ThreadsRequest =
       new CometChat.ThreadsRequestBuilder()
         .setParticipatedByMe(true)
         .setLimit(30)
@@ -236,7 +236,7 @@
   </Tab>
   <Tab title="JavaScript">
     ```javascript
     let threadsRequest = new CometChat.ThreadsRequestBuilder()
       .setParticipatedByMe(true)
       .setLimit(30)
       .build();
@@ -307,6 +307,74 @@
   message's `sentAt` — a thread with no replies has no last reply.
 </Note>
 
+## Notification Preferences
+
+The notification preference for replies carries a value that pairs with this feature, so a user can be notified only about the threads they follow: `SUBSCRIBE_TO_SUBSCRIBED_THREADS` in the `RepliesOptions` enum.
+
+| Value | Behavior |
+| --- | --- |
+| `DONT_SUBSCRIBE` | No notifications for thread replies. |
+| `SUBSCRIBE_TO_ALL` | Notifications for all thread replies. |
+| `SUBSCRIBE_TO_MENTIONS` | Notifications only for replies that mention the user. |
+| `SUBSCRIBE_TO_SUBSCRIBED_THREADS` | Notifications for replies in threads the user is subscribed to. |
+
+Threads exist in one-on-one conversations as well as groups, so set it on whichever preferences you are updating:
+
+<Tabs>
+  <Tab title="TypeScript">
+    ```typescript
+    const updatedPreferences = new CometChatNotifications.NotificationPreferences();
+
+    const groupPreferences = new CometChatNotifications.GroupPreferences();
+    groupPreferences.setRepliesPreference(
+      CometChatNotifications.RepliesOptions.SUBSCRIBE_TO_SUBSCRIBED_THREADS
+    );
+    updatedPreferences.setGroupPreferences(groupPreferences);
+
+    const oneOnOnePreferences = new CometChatNotifications.OneOnOnePreferences();
+    oneOnOnePreferences.setRepliesPreference(
+      CometChatNotifications.RepliesOptions.SUBSCRIBE_TO_SUBSCRIBED_THREADS
+    );
+    updatedPreferences.setOneOnOnePreferences(oneOnOnePreferences);
+
+    const preferences = await CometChatNotifications.updatePreferences(
+      updatedPreferences
+    );
+    ```
+  </Tab>
+  <Tab title="JavaScript">
+    ```javascript
+    const updatedPreferences = new CometChatNotifications.NotificationPreferences();
+
+    const groupPreferences = new CometChatNotifications.GroupPreferences();
+    groupPreferences.setRepliesPreference(
+      CometChatNotifications.RepliesOptions.SUBSCRIBE_TO_SUBSCRIBED_THREADS
+    );
+    updatedPreferences.setGroupPreferences(groupPreferences);
+
+    const oneOnOnePreferences = new CometChatNotifications.OneOnOnePreferences();
+    oneOnOnePreferences.setRepliesPreference(
+      CometChatNotifications.RepliesOptions.SUBSCRIBE_TO_SUBSCRIBED_THREADS
+    );
+    updatedPreferences.setOneOnOnePreferences(oneOnOnePreferences);
+
+    const preferences = await CometChatNotifications.updatePreferences(
+      updatedPreferences
+    );
+    ```
+  </Tab>
+</Tabs>
+
+<Note>
+`updatePreferences()` merges what you set, so sending only the fields you changed is enough.
+</Note>
+
+<Warning>
+A **threaded reply** (a message posted into a thread) and a **quoted reply** (a reply to one specific message) are configured through two different enums — `RepliesOptions` and `QuotedRepliesOptions` — and their fourth values differ, so the raw number `4` means something different on each. Pass a `QuotedRepliesOptions` value to `setQuotedRepliesPreference()`, never a `RepliesOptions` one.
+</Warning>
+
+See [Notification Preferences](/notifications/preferences) for reading and updating a user's preferences, and for the full `QuotedRepliesOptions` list.
+
 ## Error Handling
 
 Both `subscribeToThread()` and `unsubscribeFromThread()` reject with a `CometChatException`. The most common client-side failure is an invalid parent message ID.

ui-kit/react/components/conversations.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Conversations"
 description: "Scrollable list of recent one-on-one and group conversations for the logged-in user with real-time updates."
 ---
 
 <Accordion title="AI Integration Quick Reference">
@@ -47,7 +47,7 @@
       "onSearchBarClicked": "() => void"
     },
     "visibility": {
       "hideReceipts": { "type": "boolean", "default": false },
       "hideUserStatus": { "type": "boolean", "default": false },
       "hideGroupType": { "type": "boolean", "default": false },
       "hideUnreadCount": { "type": "boolean", "default": false },
@@ -61,7 +61,7 @@
       "customSoundForMessages": { "type": "string", "default": "built-in" }
     },
     "selection": {
       "selectionMode": {
         "type": "CometChatConversationsSelectionMode",
         "values": ["'none'", "'single'", "'multiple'"],
         "default": "'none'"
@@ -222,7 +222,7 @@
 function ChatApp() {
   const [user, setUser] = useState<CometChat.User | undefined>();
   const [group, setGroup] = useState<CometChat.Group | undefined>();
   const [activeConversation, setActiveConversation] = useState<CometChat.Conversation | undefined>();
 
   const handleConversationClick = (conversation: CometChat.Conversation) => {
     setActiveConversation(conversation); // highlights the open row in the list
@@ -310,9 +310,9 @@
 | Prop | Signature | Fires when |
 | --- | --- | --- |
 | `onItemClick` | `(conversation: CometChat.Conversation) => void` | User clicks a conversation item |
 | `onSelect` | `(conversation: CometChat.Conversation, selected: boolean) => void` | Conversation selected/deselected (selection mode) |
 | `onError` | `((error: CometChat.CometChatException) => void) \| null` | SDK error occurs |
 | `onEmpty` | `() => void` | List is empty after initial fetch |
 | `onSearchBarClicked` | `() => void` | Search bar is clicked (makes input read-only) |
 
 ### Events Emitted
@@ -364,7 +364,7 @@
 
 When pinning is enabled for your app (the `features.ux.conversations.pinned.enabled` app setting), each row's context menu carries a **Pin / Unpin** action, and pinned chats sort to the top of the list with a pin indicator on the row. This is wired out of the box — no props required.
 
-Pins are personal to each user, and your app can cap how many a user may pin through the `features.ux.conversations.pinned.limit` app setting; when a user reaches the cap, the kit shows a toast naming the limit. To remove the menu action entirely, set [`hidePinConversation`](#hidepinconversation). See [Core Features → Pin & Save](/ui-kit/react/core-features#pin-and-save-messages).
+Pins are personal to each user, and your app can cap how many a user may pin through the `features.ux.conversations.pinned.limit` app setting; when a user reaches the cap, the kit shows a toast naming the limit. To remove the menu action entirely, set [`hidePinConversation`](#hidepinconversation). See [Core Features → Pin Conversations](/ui-kit/react/core-features#pin-conversations).
 
 A conversation can also be **system-pinned** app-wide (even when empty). System pins always sort above user pins and cannot be unpinned from the UI.
 
@@ -374,8 +374,8 @@
 
 ```tsx
 <CometChatConversations
   headerView={<MyCustomHeader />}
   itemView={(conversation) => <MyCustomItem conversation={conversation} />}
   emptyView={<EmptyState />}
   loadingView={<Skeleton />}
   errorView={<ErrorBanner />}
@@ -385,10 +385,10 @@
 | Slot | Signature | Replaces |
 | --- | --- | --- |
 | `itemView` | `(conversation) => ReactNode` | Entire conversation row |
 | `leadingView` | `(conversation) => ReactNode` | Avatar section |
 | `titleView` | `(conversation) => ReactNode` | Conversation name |
 | `subtitleView` | `(conversation) => ReactNode` | Last message preview |
 | `trailingView` | `(conversation) => ReactNode` | Timestamp + unread badge |
 | `headerView` | `ReactNode` | Header area |
 | `searchView` | `ReactNode` | Search bar |
 | `loadingView` | `ReactNode` | Loading shimmer |
@@ -705,7 +705,7 @@
 
     let className = "conversations__trailing-view-min";
     let topLabel = `${diffInMinutes}`;
     let bottomLabel = diffInMinutes === 1 ? "Min ago" : "Mins ago";
 
     if (diffInHours >= 1 && diffInHours <= 10) {
       className = "conversations__trailing-view-hour";
@@ -924,7 +924,7 @@
 | Sub-component | Description | Props | Flat API equivalent |
 | --- | --- | --- | --- |
 | `Root` | Context provider and container | All Root props + `children` | — |
 | `List` | Scrollable conversation list | `itemView`, `className` | `itemView` |
 | `Item` | Individual conversation row | `leadingView`, `titleView`, `subtitleView`, `trailingView`, `className` | Per-item view props |
 | `Header` | Header area | `title`, `children` | `headerView` |
 | `SearchBar` | Search input | `placeholder`, `onClick` | `searchView` |
@@ -981,7 +981,7 @@
 
 ---
 
 ### searchKeyword
 
 Initial search keyword to pre-filter conversations on mount.
 
@@ -1095,9 +1095,9 @@
 
 ---
 
 ### showScrollbar
 
 Show the native scrollbar on the conversation list.
 
 | | |
 | --- | --- |

ui-kit/react/components/pinned-messages.mdx

@@ -123,7 +123,7 @@
 </Note>
 
 <Note>
-**Permissions & limits** — the unpin action is shown to every member; permission is enforced by the **server**, and a rejected unpin surfaces a permission toast (localizable via `action_permission_denied`). If your app caps pins per conversation, hitting the cap shows a toast naming the limit — you don't handle the error yourself. See the [Pin & Save Messages guide](/ui-kit/react/guide-pin-and-save-messages#step-5-limits).
+**Permissions & limits** — the unpin action is shown to every member; permission is enforced by the **server**, and a rejected unpin surfaces a permission toast (localizable via `action_permission_denied`). If your app caps pins per conversation, hitting the cap shows a toast naming the limit — you don't handle the error yourself. See the [Pin & Save Messages guide](/ui-kit/react/guide-pin-and-save-messages#step-5-app-settings-and-limits).
 </Note>
 
 ---
@@ -140,7 +140,7 @@
 
 function PinnedPanel({
   group,
   onClose,
 }: {
   group: CometChat.Group;
   onClose: () => void;
@@ -366,9 +366,9 @@
 
 ---
 
 ### textFormatters
 
 Text formatters applied when rendering the pinned message previews. See [Text Formatters](/ui-kit/react/plugins/text-formatters).
 
 | | |
 | --- | --- |
@@ -401,7 +401,7 @@
 
 ### hideSaveMessageOption / hideUnsaveMessageOption
 
 Remove the save / unsave actions from the per-message options.
 
 | | |
 | --- | --- |
@@ -487,7 +487,7 @@
 
 ---
 
 ### className
 
 Additional CSS class for the root element.
 

ui-kit/react/components/saved-messages.mdx

@@ -100,7 +100,7 @@
 </Note>
 
 <Note>
-**Limit** — if your app caps how many messages a user can save, hitting the cap shows a toast naming the limit; you don't handle the error yourself. See the [Pin & Save Messages guide](/ui-kit/react/guide-pin-and-save-messages#step-5-limits).
+**Limit** — if your app caps how many messages a user can save, hitting the cap shows a toast naming the limit; you don't handle the error yourself. See the [Pin & Save Messages guide](/ui-kit/react/guide-pin-and-save-messages#step-5-app-settings-and-limits).
 </Note>
 
 ---
@@ -112,7 +112,7 @@
 ```tsx
 import { CometChatSavedMessages } from "@cometchat/chat-uikit-react";
 
 function SavedScreen({ onClose }: { onClose: () => void }) {
   return <CometChatSavedMessages onClose={onClose} />;
 }
 ```
@@ -189,13 +189,13 @@
 
 ### Events
 
 The component itself publishes nothing, but the unsave action it renders (through the shared message options) publishes `ui:message/save-changed`, which keeps other surfaces in sync.
 
 It subscribes to the kit event bus and updates its list automatically — an optimistic `ui:` flip the moment a save/unsave succeeds locally, then the network-confirmed SDK event:
 
 | Event | Payload | Behavior |
 | --- | --- | --- |
 | `ui:message/save-changed` | `{ message, saved }` | Optimistic: adds on save, removes on unsave |
 | `message/saved` / `message/unsaved` | `{ message }` | Network-confirmed add / remove |
 
 See the [Event System](/ui-kit/react/event-system#pin-and-save) for the full list.
@@ -206,14 +206,14 @@
 
 ### Per-message Options
 
 Each saved row exposes an unsave action. Hide it with `hideUnsaveMessageOption`:
 
 ```tsx
 <CometChatSavedMessages hideUnsaveMessageOption />
 ```
 
 <Note>
 Saved rows are list items rather than full message bubbles, so they carry only the unsave action — there is no full per-message options menu here.
 </Note>
 
 ### View Props
@@ -283,9 +283,9 @@
 
 ---
 
 ### textFormatters
 
 Text formatters applied when rendering the saved message previews. See [Text Formatters](/ui-kit/react/plugins/text-formatters).
 
 | | |
 | --- | --- |
@@ -307,7 +307,7 @@
 
 ### hideUnsaveMessageOption
 
 Remove the unsave action from each saved row.
 
 | | |
 | --- | --- |
@@ -338,7 +338,7 @@
 
 ---
 
 ### className
 
 Additional CSS class for the root element.
 
@@ -363,7 +363,7 @@
 | Row preview | `.cometchat-saved-messages__item-preview` |
 | Row subtitle | `.cometchat-saved-messages__item-subtitle` |
 | Row media-type icon | `.cometchat-saved-messages__item-subtitle-icon` (`--image`, `--video`, `--audio`, `--file`) |
 | Row unsave button | `.cometchat-saved-messages__item-unsave` |
 | Empty state | `.cometchat-saved-messages__empty` |
 | Empty title | `.cometchat-saved-messages__empty-title` |
 | Empty subtitle | `.cometchat-saved-messages__empty-subtitle` |

ui-kit/react/core-features.mdx

@@ -160,6 +160,17 @@ Threads require wiring: capture the parent message from the Message List's `onTh
 | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
 | [Threaded Messages guide](/ui-kit/react/guide-threaded-messages) | The [Threaded Messages guide](/ui-kit/react/guide-threaded-messages) shows how to build a thread panel: `onThreadRepliesClick`, `parentMessageId`, and `CometChatThreadHeader` (which displays the parent message with its reply count). |
 
+### Thread Subscription
+
+Users can **subscribe** to a thread to keep getting updates about its replies even when they aren't viewing it, and unsubscribe to stop. Subscription is per-user and per-thread, works in both 1:1 and group conversations, and is wired out of the box — there is no flag to turn on.
+
+| Components | Functionality |
+| --- | --- |
+| [Message List](/ui-kit/react/components/message-list#hidethreadsubscriptionoption) | Adds a Subscribe / Unsubscribe option to the message options menu. On a reply, the action targets the thread's parent message. |
+| [Thread Header](/ui-kit/react/components/thread-header#thread-subscription) | Shows a subscription bell on the thread panel that reflects and toggles the current state. |
+
+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. A deliberate unsubscribe is remembered. See the [Threaded Messages guide](/ui-kit/react/guide-threaded-messages#thread-subscription) for the full behaviour, the `hide*` props, and the `useThreadSubscription` hook.
+
 ## Quoted Replies
 
 Quoted Replies is a robust feature provided by CometChat that enables users to quickly reply to specific messages by selecting the "Reply" option from a message's action menu. This enhances context, keeps conversations organized, and improves overall chat experience in both 1-1 and group chats.
@@ -195,19 +206,38 @@ CometChat lets users **pin** important messages so they're highlighted for every
 | Components | Functionality |
 | --- | --- |
 | [Message List](/ui-kit/react/components/message-list#pin-and-save-options) | Adds Pin, Unpin, Save, and Unsave to the message options menu when the features are enabled. |
+| [Message Bubble](/ui-kit/react/components/message-bubble#pinned-and-saved-indicators) | Marks pinned and saved messages with an indicator on the bubble. |
+| [Message Header](/ui-kit/react/components/message-header) | Provides the "Pinned messages" entry point in its overflow menu. |
 | [Pinned Messages](/ui-kit/react/components/pinned-messages) | A panel of the messages pinned in a conversation, opened from the [Message Header](/ui-kit/react/components/message-header). |
 | [Saved Messages](/ui-kit/react/components/saved-messages) | A personal screen of the current user's saved messages across all conversations. |
-| [Conversations](/ui-kit/react/components/conversations#hidepinconversation) | Lets users pin a whole conversation to the top of their list. |
 
-Your app can also cap how many items a user may pin or save through three app settings:
+Each feature is switched on per app, and each carries its own cap:
 
-| App setting | Caps |
+| App setting | Controls |
 | --- | --- |
+| features.ux.messages.pinned.enabled | Whether the pin options and panel 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 these settings at login, so no wiring is needed to show, hide, or enforce them. When a user reaches a cap, the kit shows a toast that names the exact limit — no extra handling required. For a full walkthrough, see the [Pin & Save Messages guide](/ui-kit/react/guide-pin-and-save-messages).
+
+## Pin Conversations
+
+Keep the chats that matter at the top. Users pin a conversation from the row's context menu; pinned conversations show a pin indicator and sort above the rest of the list. Pins are personal to each user.
+
+| Components | Functionality |
+| --- | --- |
+| [Conversations](/ui-kit/react/components/conversations#pin-conversation) | 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 |
 
-The UI Kit reads these settings at login. When a user reaches a cap, the kit shows a toast that names the exact limit — no extra handling required. For a full walkthrough, see the [Pin & Save Messages guide](/ui-kit/react/guide-pin-and-save-messages).
+A conversation can also be **system-pinned** app-wide by your app. System pins always sort above user pins and cannot be unpinned from the UI. See [Conversations → Pin Conversation](/ui-kit/react/components/conversations#pin-conversation).
 
 ## Group Chat