Threaded Messages - CometChat Docs

AI Integration Quick Reference

Field	Value
Packages	`com.cometchat:chatuikit-kotlin` · `com.cometchat:chatuikit-jetpack`
Key components	`CometChatThreadHeader`, `CometChatMessageList`, `CometChatMessageComposer`
Purpose	Implement threaded replies so users can respond to specific messages in a focused sub-conversation.
Related	Threaded Messages Header, Message List, Message Composer, All Guides

Implement threaded replies in your Android chat app using CometChat’s UI Kit, enabling users to reply to specific messages in a focused sub-conversation.

Overview

Threaded replies allow users to respond directly to a specific message in one-on-one or group chats, improving context and readability:

Organizes related replies into a dedicated thread view.
Mirrors functionality in Slack, Discord, and WhatsApp.
Maintains clarity in active conversations.

Users tap a message → open thread screen → view parent message + replies → compose within thread.

Prerequisites

Android project in Android Studio.
CometChat Android UI Kit v6 (com.cometchat:chatuikit-kotlin or com.cometchat:chatuikit-jetpack) added to your build.gradle.
Valid CometChat App ID, Auth Key, and Region initialized.
<uses-permission android:name="android.permission.INTERNET"/> in AndroidManifest.xml.
Logged-in user via CometChatUIKit.login().
Existing MessagesActivity using CometChatMessageList.

Components

Component	Role
`activity_thread_message.xml`	Defines thread UI: header, message list, composer, unblock.
`ThreadMessageActivity`	Hosts thread screen; initializes UI & ViewModel.
`ThreadMessageViewModel`	Fetches parent message & thread replies; manages state.
`CometChatMessageList`	Displays threaded replies when given parent message ID.
`CometChatMessageComposer`	Composes and sends replies with `parentMessageId`.
`CometChatThreadHeader`	Displays the parent message context at the top of the thread.

Integration Steps

Step 1: Add Thread Layout

Create res/layout/activity_thread_message.xml:

activity_thread_message.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical">

    <com.cometchat.uikit.kotlin.presentation.threadheader.ui.CometChatThreadHeader
        android:id="@+id/threadHeader"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    <com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList
        android:id="@+id/threadMessageList"
        android:layout_width="match_parent"
        android:layout_height="0dp"
        android:layout_weight="1" />

    <LinearLayout
        android:id="@+id/unblockLayout"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:gravity="center"
        android:padding="12dp"
        android:visibility="gone">

        <Button
            android:id="@+id/unblockBtn"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:text="Unblock" />
    </LinearLayout>

    <com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer
        android:id="@+id/threadComposer"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

</LinearLayout>

Step 2: Set up ThreadMessageActivity

Initialize UI & handle blocked-user flows:

Kotlin (XML Views)
Jetpack Compose

import com.cometchat.uikit.kotlin.presentation.threadheader.ui.CometChatThreadHeader
import com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList
import com.cometchat.uikit.kotlin.presentation.messagecomposer.ui.CometChatMessageComposer

class ThreadMessageActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_thread_message)
        val header = findViewById<CometChatThreadHeader>(R.id.threadHeader)
        val messageList = findViewById<CometChatMessageList>(R.id.threadMessageList)
        val composer = findViewById<CometChatMessageComposer>(R.id.threadComposer)
        val unblock = findViewById<View>(R.id.unblockLayout)

        val rawMessage = intent.getStringExtra("raw_json")
        val viewModel = ViewModelProvider(this)[ThreadMessageViewModel::class.java]
        if (rawMessage != null) {
            val parentMessage = BaseMessage.processMessage(JSONObject(rawMessage))
            viewModel.setParentMessage(parentMessage)
        }

        lifecycleScope.launch {
            viewModel.parentMessage.collect { msg ->
                msg?.let {
                    header.setParentMessage(it)
                    messageList.setParentMessage(it.id)
                    composer.setParentMessageId(it.id)
                }
            }
        }

        // Handle blocked user
        if (isBlockedByMe) {
            composer.visibility = View.GONE
            unblock.visibility = View.VISIBLE
        }
    }
}

import com.cometchat.uikit.compose.presentation.threadheader.ui.CometChatThreadHeader
import com.cometchat.uikit.compose.presentation.messagelist.ui.CometChatMessageList
import com.cometchat.uikit.compose.presentation.messagecomposer.ui.CometChatMessageComposer

@Composable
fun ThreadMessageScreen(rawJson: String, isBlockedByMe: Boolean = false) {
    val parentMessage = remember {
        BaseMessage.processMessage(JSONObject(rawJson))
    }

    Column(modifier = Modifier.fillMaxSize()) {
        CometChatThreadHeader(parentMessage = parentMessage)

        CometChatMessageList(
            parentMessageId = parentMessage.id,
            modifier = Modifier.weight(1f)
        )

        if (isBlockedByMe) {
            UnblockPrompt(onUnblock = { /* unblock logic */ })
        } else {
            CometChatMessageComposer(parentMessageId = parentMessage.id)
        }
    }
}

Step 3: Create ThreadMessageViewModel

Store parent message and expose via StateFlow:

class ThreadMessageViewModel : ViewModel() {
    private val _parentMessage = MutableStateFlow<BaseMessage?>(null)
    val parentMessage: StateFlow<BaseMessage?> = _parentMessage.asStateFlow()
    var id: Long = 0
        private set

    fun setParentMessage(message: BaseMessage?) {
        if (message != null) {
            id = message.id
            _parentMessage.value = message
        }
    }
}

Step 4: Hook Thread Entry from Message List

In your MessagesActivity, capture thread icon taps:

Kotlin (XML Views)
Jetpack Compose

messageList.setOnThreadRepliesClick { context, baseMessage, template ->
    val intent = Intent(context, ThreadMessageActivity::class.java)
    intent.putExtra("raw_json", baseMessage.rawMessage.toString())
    intent.putExtra("reply_count", baseMessage.replyCount)
    context.startActivity(intent)
}

CometChatMessageList(
    user = user,
    onThreadRepliesClick = { baseMessage, template ->
        navController.navigate("thread/${baseMessage.rawMessage}")
    },
    modifier = Modifier.weight(1f)
)

Implementation Flow

User taps thread icon on a message.
Intent launches ThreadMessageActivity with raw message JSON (or Compose navigation).
ViewModel stores parent message and exposes via StateFlow.
Header & MessageList render parent + replies.
Composer sends new replies under the parent message.
Live updates flow automatically via UI Kit.

Customization Options

Styling: Override theme attributes or call setter methods on views.
Header Height: threadHeader.setMaxHeight(...).
Hide Reactions: threadHeader.setReactionVisibility(View.GONE).

Filtering & Edge Cases

Group Membership: Verify membership before enabling composer.
Empty Thread: Show placeholder if no replies.
Blocked Users: Composer hidden; use unblock layout.

Blocked-User Handling

Kotlin (XML Views)
Jetpack Compose

if (user.isBlockedByMe) {
    composer.visibility = View.GONE
    unblockLayout.visibility = View.VISIBLE
}

if (user.isBlockedByMe) {
    UnblockPrompt(onUnblock = { /* unblock logic */ })
} else {
    CometChatMessageComposer(parentMessageId = parentMessage.id)
}

Group vs. User-Level Differences

Scenario	Behavior
`ReceiverType.USER`	Direct replies allowed if not blocked.
`ReceiverType.GROUP`	Checks membership before thread access.
Blocked User	Composer hidden; unblock layout shown.
Not in Group	Show option to join group first.

Thread Subscription

Thread subscription gives users Slack-style control over thread noise: they can subscribe to a thread to be notified about its replies, or unsubscribe from one to mute it. Users are automatically subscribed when they start a thread, reply in one, or are @-mentioned in one — subscribing explicitly is how they opt in to a conversation they haven’t participated in yet. The UI Kit ships two surfaces for the same toggle, wired out of the box and kept in sync automatically:

A Subscribe to thread / Unsubscribe from thread option in the message action sheet.
A subscription bell on the thread view.

The Message Action Sheet Option

CometChatMessageList adds a Subscribe to thread / Unsubscribe from thread option to the long-press action sheet. The label reflects the current state, and the option appears on regular messages of every type (agent messages and moderation-blocked messages are excluded) — on a thread reply it targets the thread’s root message, so subscribing from anywhere in the thread works. To hide the option while keeping the rest of the feature:

Kotlin (XML Views)

messageList.setThreadSubscriptionOptionVisibility(View.GONE)

The Thread Header Bell

CometChatThreadHeader renders a subscription bell as a trailing control on the reply-count bar. It flips optimistically on tap and reverts with a toast if the request fails.

Kotlin (XML Views)
Jetpack Compose

// Hide the bell (e.g. because you host your own — see below)
threadHeader.setThreadSubscriptionVisibility(View.GONE)

// Observe state changes (isSubscribed = the new state)
threadHeader.setOnThreadSubscriptionChange { isSubscribed ->
    Log.d(TAG, "Thread subscribed: $isSubscribed")
}

The visibility can also be set in XML with the app:cometchatThreadSubscriptionVisibility attribute.

CometChatThreadHeader(
    parentMessage = parentMessage,
    hideThreadSubscription = false,       // hide the built-in bell when true
    isSubscribed = null,                  // null = seed from parentMessage.isThreadSubscribed()
    onSubscriptionToggle = { isSubscribed ->
        Log.d(TAG, "Thread subscribed: $isSubscribed")
    },
    threadSubscriptionView = null         // or your own composable replacing the bell
)

Hosting the Bell in Your Own Top Bar

Many apps (matching the CometChat sample apps and Figma) place the subscription bell in the thread screen’s top title bar rather than the reply-count row. In Compose, the bell is available as a standalone public composable — hide the header’s built-in one and host ThreadSubscriptionBell wherever you like:

Jetpack Compose
Kotlin (XML Views)

TopAppBar(
    title = { Text(stringResource(R.string.thread)) },
    actions = {
        ThreadSubscriptionBell(parentMessage = parentMessage)
    }
)

CometChatThreadHeader(
    parentMessage = parentMessage,
    hideThreadSubscription = true   // the bell lives in the top bar instead
)

// Hide the kit header's bell and drive your own ImageView in the activity's title bar:
threadHeader.setThreadSubscriptionVisibility(View.GONE)

// On tap: flip your icon optimistically, then call the SDK
CometChat.subscribeToThread(parentMessage.id, object : CometChat.CallbackListener<String>() {
    override fun onSuccess(response: String?) { }
    override fun onError(e: CometChatException?) {
        // revert the icon and show a toast
    }
})

Subscription Behavior

Optimistic with revert — both surfaces flip instantly on tap, keep one request in flight per thread, and revert with a toast if the server rejects the change. An offline tap fails visibly and reverts; nothing is queued.
Auto-subscribe on reply — sending a reply in a thread subscribes the user, and every surface flips to the subscribed state automatically.
Unsubscribing is not sticky — replying again, or being @-mentioned, re-subscribes the user.
Unknown state renders as unsubscribed — a message whose subscription state hasn’t been learned yet (for example, one that just arrived in real time) shows the enabled subscribe control, never a spinner.

Cross-Surface Sync

Both surfaces observe the UI Kit event bus, so toggling in one place updates the other without a refetch. If you build your own subscription control, emit and collect CometChatThreadEvent through CometChatEvents.threadEvents — 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).

Summary / Feature Matrix

Feature	Component / Method
Show thread option	`setOnThreadRepliesClick()`
Display thread messages	`messageList.setParentMessage(parentMessage.getId())`
Show parent message	`header.setParentMessage(parentMessage)`
Compose reply	`composer.setParentMessageId(parentMessage.getId())`
Handle blocked users	`isBlockedByMe()`, hide composer + show unblock UI
Subscribe / unsubscribe	Action-sheet option + `CometChatThreadHeader` bell

Next Steps & Further Reading

Thread Subscription (SDK)

The underlying APIs, including fetching the threads a user participates in to build a thread inbox.

Android Sample App (Kotlin)

Explore this feature in the CometChat SampleApp: GitHub → SampleApp

​Overview

​Prerequisites

​Components

​Integration Steps

​Step 1: Add Thread Layout

​Step 2: Set up ThreadMessageActivity

​Step 3: Create ThreadMessageViewModel

​Step 4: Hook Thread Entry from Message List

​Implementation Flow

​Customization Options

​Filtering & Edge Cases

​Blocked-User Handling

​Group vs. User-Level Differences

​Thread Subscription

​The Message Action Sheet Option

​The Thread Header Bell

​Hosting the Bell in Your Own Top Bar

​Subscription Behavior

​Cross-Surface Sync

​Notifications

​Summary / Feature Matrix

​Next Steps & Further Reading