Thread Subscription - CometChat Docs

AI Integration Quick Reference

Field	Value
Package	`cometchat_chat_uikit`
Import	`import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';`
Purpose	Let users subscribe to or unsubscribe from message threads so notifications only reach the people who care.
Feature gate	`UIKitSettingsBuilder.enableThreadSubscription` — `false` by default
Key widgets	`CometChatMessageList` · `CometChatMessageHeader` · `CometChatThreadedHeader`
Key events	`CometChatMessageEvents.ccThreadSubscriptionChanged`
Prerequisites	Threaded messages working in your app — see Threaded Messages.
Related	Thread Subscription (SDK) · Threaded Messages Header

Available from UI Kit v6.1.1. This feature requires cometchat_chat_uikit v6.1.1 or later, which depends on cometchat_sdk v5.0.7.

Overview

Thread subscription gives users control over thread noise: they can subscribe to a thread to be notified about its replies, or unsubscribe from one to mute it. The server subscribes users automatically when they start a thread, reply in one, or are @-mentioned in one — subscribing explicitly is how they opt in to a thread they have not taken part in yet. The UI Kit ships three surfaces for the same toggle, kept in sync automatically:

A Subscribe to thread / Unsubscribe from thread option in the message action menu.
A notification bell on the thread screen’s CometChatMessageHeader.
A subscribe control in the reply-count row of CometChatThreadedHeader.

Prerequisites

Threaded messages working in your app — see Threaded Messages.
CometChat UI Kit for Flutter v6.1.1 or later, with Chat SDK v5.0.7 or later.

Enable the Feature

Thread subscription is off by default and is enabled per app through UIKitSettings at init time. With the gate off, none of the surfaces render and no subscription request is ever made, whatever the individual visibility flags say.

Dart

UIKitSettings uiKitSettings = (UIKitSettingsBuilder()
  ..subscriptionType = CometChatSubscriptionType.allUsers
  ..autoEstablishSocketConnection = true
  ..region = CometChatConfig.region
  ..appId = CometChatConfig.appId
  ..authKey = CometChatConfig.authKey
  ..enableThreadSubscription = true // opt in — default is false
).build();

CometChatUIKit.init(
  uiKitSettings: uiKitSettings,
  onSuccess: (successMessage) => debugPrint('CometChat Initialized'),
  onError: (error) => debugPrint('CometChat Initialization error'),
);

Anywhere you build your own UI around the feature, check the gate the kit reads:

Dart

final bool enabled =
    CometChatUIKit.authenticationSettings?.enableThreadSubscription == true;

With the gate on, CometChatMessageList adds Subscribe to thread / Unsubscribe from thread to the action menu. The label reflects the current state, and the option appears on every message — whether or not it has replies yet. On a thread reply it targets the thread’s parent message, so subscribing works from anywhere in the thread. A successful change shows a toast — “Subscribed. You’ll be notified about new replies in this thread.” or “Unsubscribed. Notifications are off until you reply or are mentioned.” To hide the option while keeping the rest of the feature:

Dart

CometChatMessageList(
  user: user,
  hideThreadSubscriptionOption: true,
)

Surface 2: The Header Bell

On the thread screen, pass the thread’s root message as parentMessage to CometChatMessageHeader. The header switches to thread mode and renders a bell in its trailing area that reflects the live subscription state; tapping it toggles the subscription.

Dart

CometChatMessageHeader(
  user: user,
  group: group,
  parentMessage: parentMessage, // thread mode + subscription bell
)

Set threadSubscriptionVisibility: false on the header to hide the bell.

Surface 3: The Threaded Header Control

CometChatThreadedHeader renders a subscribe control in its reply-count row. It flips on tap, ignores taps while a request is in flight, and reverts with a “Couldn’t update. Please try again.” toast if the server rejects the change.

Dart

CometChatThreadedHeader(
  parentMessage: parentMessage,
  loggedInUser: loggedInUser,
  // hide it when the header bell above already carries the toggle
  threadSubscriptionVisibility: false,
)

When both the header bell and this control are on screen, hide one of them so the thread screen carries a single toggle.

Behavior

Unknown state renders as unsubscribed — a message whose state has not been fetched yet (for example, one that just arrived in real time) shows the “Subscribe” affordance. Subscribing is idempotent, so the extra request is harmless.
Auto-subscribe is reflected — when the user sends a reply in a thread, is @-mentioned in an incoming message, or receives the first reply to their own message, the kit flips every surface to subscribed without making a request.
Unsubscribing is not sticky — replying again, or being @-mentioned, re-subscribes the user.

Cross-Surface Sync

All three surfaces listen to the UI Kit event bus, so toggling in one place updates the others without a refetch. If you build your own control, or keep your own list of followed threads, listen for ccThreadSubscriptionChanged on CometChatMessageEvents — it carries the parent message ID and the new state:

Dart

class _ThreadInboxState extends State<ThreadInbox>
    with CometChatMessageEventListener {
  @override
  void initState() {
    super.initState();
    CometChatMessageEvents.addMessagesListener("thread_inbox", this);
  }

  @override
  void dispose() {
    CometChatMessageEvents.removeMessagesListener("thread_inbox");
    super.dispose();
  }

  @override
  void ccThreadSubscriptionChanged(int parentMessageId, bool subscribed) {
    // An unsubscribe removes the thread from the user's participated list
    if (!subscribed) _removeThreadRow(parentMessageId);
  }
}

CometChatThreadedHeader.onThreadSubscriptionChange reports only toggles made on that control; the event covers every surface. See Events.

Notifications

Whether a subscribed thread actually produces a push notification is governed by the user’s notification preferences: the replies preference supports notifying only for threads the user is subscribed to (SUBSCRIBE_TO_SUBSCRIBED_THREADS). See Thread Subscription (SDK).

Next Steps & Further Reading

Thread Subscription (SDK) — the underlying APIs, including fetching the threads a user participates in to build a thread inbox.
Threaded Messages Header — the full component reference.
Message List — action-menu options.

​Overview

​Prerequisites

​Enable the Feature

​Surface 1: The Message Action Menu Option

​Surface 2: The Header Bell

​Surface 3: The Threaded Header Control

​Behavior

​Cross-Surface Sync

​Notifications

​Next Steps & Further Reading

Overview

Prerequisites

Enable the Feature

Surface 1: The Message Action Menu Option

Surface 2: The Header Bell

Surface 3: The Threaded Header Control

Behavior

Cross-Surface Sync

Notifications

Next Steps & Further Reading