Threaded Messages

Implement threaded replies so users can respond to specific messages in a focused sub-conversation.

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)

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
        }
    }
}

Jetpack Compose

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)

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)
}

Jetpack Compose

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

Implementation Flow

1. User taps thread icon on a message.
2. Intent launches ThreadMessageActivity with raw message JSON (or Compose navigation).
3. ViewModel stores parent message and exposes via StateFlow.
4. Header & MessageList render parent + replies.
5. Composer sends new replies under the parent message.
6. 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)

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

Jetpack Compose

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:

1. A Subscribe to thread / Unsubscribe from thread option in the message action sheet.
2. 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)

// 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.

Jetpack Compose

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

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

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

Kotlin (XML Views)

// 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