Thread Subscription - CometChat Docs

AI Integration Quick Reference

// Subscribe / unsubscribe — a thread is identified by its PARENT message id
CometChat.subscribeToThread(parentMessageId, callbackListener)
CometChat.unsubscribeFromThread(parentMessageId, callbackListener)

// Read state off a fetched parent message — there is no state store to query
val following: Boolean = parentMessage.isThreadSubscribed

// Align local copies after the server accepts (LOCAL ONLY — sends nothing)
parentMessage.setThreadSubscribed(true)

// Thread inbox
val request = ThreadsRequest.ThreadsRequestBuilder()
    .setParticipatedByMe(true)
    .setLimit(30)
    .build()
request.fetchNext(callbackListener)          // List<MessageThread>

Give users Slack-style control over thread noise. A user can subscribe to a message thread to be notified of future replies, or unsubscribe from it to mute it. The server subscribes a user to a thread automatically when they start it, reply in it, or are @-mentioned in it — and they can explicitly subscribe to any parent message, even one that has no replies yet. The SDK also exposes the list of threads a user participates in, so you can build a thread inbox.

Thread subscription builds on Threaded Messages. A thread is identified by the ID of its parent message — there is no separate thread ID.

How State Works

The SDK keeps no subscription state of its own. There is no cache and no thread listener to reconcile:

Every message fetch asks the server for the flag, and it arrives on the message — read it with BaseMessage.isThreadSubscribed().
subscribeToThread() and unsubscribeFromThread() call back when the server has accepted the change. The callback is the acknowledgement — there is no follow-up event.

Your app owns the resulting UI state. That means you decide when to flip a toggle optimistically, and you decide what a thread’s state is before you have fetched it. To subscribe to a thread, use the subscribeToThread method with the ID of the thread’s parent message. The call is idempotent — subscribing to a thread the user is already subscribed to succeeds silently. Subscribing to a message with zero replies is allowed; the user will be notified when the first reply arrives.

Java
Kotlin

long parentMessageId = 1;

CometChat.subscribeToThread(parentMessageId, new CometChat.CallbackListener<String>() {
  @Override
  public void onSuccess(String response) {
      // The server has accepted it — flip your toggle here.
      Log.d(TAG, "Subscribed to thread: " + response);
  }

  @Override
  public void onError(CometChatException e) {
      Log.e(TAG, "Failed to subscribe: " + e.getMessage());
  }
});

val parentMessageId = 1L

CometChat.subscribeToThread(parentMessageId, object : CometChat.CallbackListener<String>() {
  override fun onSuccess(response: String?) {
      // The server has accepted it — flip your toggle here.
      Log.d(TAG, "Subscribed to thread: $response")
  }

  override fun onError(e: CometChatException?) {
      Log.e(TAG, "Failed to subscribe: ${e?.message}")
  }
})

Unsubscribe from a Thread

To unsubscribe from a thread, use the unsubscribeFromThread method. This too is idempotent — unsubscribing from a thread the user is not subscribed to succeeds silently.

Java
Kotlin

long parentMessageId = 1;

CometChat.unsubscribeFromThread(parentMessageId, new CometChat.CallbackListener<String>() {
  @Override
  public void onSuccess(String response) {
      Log.d(TAG, "Unsubscribed from thread: " + response);
  }

  @Override
  public void onError(CometChatException e) {
      Log.e(TAG, "Failed to unsubscribe: " + e.getMessage());
  }
});

val parentMessageId = 1L

CometChat.unsubscribeFromThread(parentMessageId, object : CometChat.CallbackListener<String>() {
  override fun onSuccess(response: String?) {
      Log.d(TAG, "Unsubscribed from thread: $response")
  }

  override fun onError(e: CometChatException?) {
      Log.e(TAG, "Failed to unsubscribe: ${e?.message}")
  }
})

Unsubscribing hard-deletes the server row, so a thread inbox built with ThreadsRequest must drop that row rather than mark it unfollowed. It is also not sticky: if the user replies in the thread again, or is @-mentioned in it, they are automatically re-subscribed. Do not promise users “you won’t be notified about this thread again”.

Read the Subscription State

The subscription state rides on the message. Read it with isThreadSubscribed() on the thread’s parent message.

Java
Kotlin

if (parentMessage.isThreadSubscribed()) {
    // render "Unsubscribe from thread"
} else {
    // render "Subscribe to thread"
}

if (parentMessage.isThreadSubscribed) {
    // render "Unsubscribe from thread"
} else {
    // render "Subscribe to thread"
}

The flag is populated only on responses to requests that asked for it. On MessagesRequestBuilder that opt-in is withThreadSubscribed(boolean), and it defaults to true — leave it there. Passing false trades the signal away for a marginally smaller response, and isThreadSubscribed() then reads false for every message, indistinguishable from a genuine unsubscribe.

val messagesRequest = MessagesRequest.MessagesRequestBuilder()
  .setUID(UID)
  .setLimit(50)
  .withThreadSubscribed(true)   // the default — shown here for clarity
  .build()

A message delivered over the websocket carries no flag and therefore reads false. That is not a claim that the user is unsubscribed — it means nobody asked. When you need certainty for a thread you have not fetched (a deep link, for instance), fetch the parent message with CometChat.getMessageDetails() and read the flag off the result.

You are subscribed to your own messages

Sending a message subscribes you to the thread it may later grow — there is nothing to call. The message comes back with the flag set, both in the send response and on later fetches, and only for you: the flag is per-viewer, so the same message reads false for everybody else until they subscribe themselves. 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

The same thread can be represented by several message objects at once — a row in the message list, the parent of an open thread view, an entry in a thread inbox. Because the SDK caches nothing, use setThreadSubscribed() to align the copies you hold once you know the answer:

Java
Kotlin

CometChat.subscribeToThread(parentMessageId, new CometChat.CallbackListener<String>() {
  @Override
  public void onSuccess(String response) {
      // The server accepted it — bring the objects you are rendering into line.
      parentMessage.setThreadSubscribed(true);
  }

  @Override
  public void onError(CometChatException e) { }
});

CometChat.subscribeToThread(parentMessageId, object : CometChat.CallbackListener<String>() {
  override fun onSuccess(response: String?) {
      // The server accepted it — bring the objects you are rendering into line.
      parentMessage.isThreadSubscribed = true
  }

  override fun onError(e: CometChatException?) { }
})

setThreadSubscribed() is local only — it changes the object in memory and sends nothing to the server. Use subscribeToThread() / unsubscribeFromThread() to change the actual subscription.

Reacting to Replies

A thread reply is an ordinary message with a parent message ID set, delivered through the standard MessageListener like any other message. There is no separate thread listener.

Java
Kotlin

private String listenerID = "UNIQUE_LISTENER_ID";

CometChat.addMessageListener(listenerID, new CometChat.MessageListener() {
  @Override
  public void onTextMessageReceived(TextMessage message) {
      long parentMessageId = message.getParentMessageId();
      if (parentMessageId > 0) {
          // A reply landed in a thread — bump your thread row here.
      }
  }
});

val listenerID = "UNIQUE_LISTENER_ID"

CometChat.addMessageListener(listenerID, object : CometChat.MessageListener() {
  override fun onTextMessageReceived(message: TextMessage) {
      if (message.parentMessageId > 0) {
          // A reply landed in a thread — bump your thread row here.
      }
  }
})

To stop listening, remove the listener with CometChat.removeMessageListener(listenerID). Using MessageListener also gets you onMessageEdited and onMessageDeleted for replies, which a thread-only channel would not. Your own replies do not arrive on a listener — bump your thread row from the sendMessage() callback instead.

Fetch the Threads a User Participates In

To build a thread inbox — one row per thread the user is part of — create a ThreadsRequest using the ThreadsRequestBuilder. The list is the union of threads the user started, replied in, was mentioned in, or explicitly subscribed to. Every returned row is, by definition, a thread the user is subscribed to: participation is subscription, and unsubscribing removes the row.

Setting	Description
`setLimit(int value)`	Page size, validated between 1 and 1000 at fetch time. Defaults to 30 — thread rows are heavy (each carries a root message and a last reply).
`setUid(String value)`	Scope the list to threads in the one-on-one conversation with this user. Mutually exclusive with `setGuid()`.
`setGuid(String value)`	Scope the list to threads in this group. Mutually exclusive with `setUid()`.
`setParticipatedByMe(boolean)`	Defaults to `true`. Only the threads the logged-in user participates in are returned.

Java
Kotlin

ThreadsRequest threadsRequest = new ThreadsRequest.ThreadsRequestBuilder()
  .setParticipatedByMe(true)
  .setLimit(30)
  .build();

threadsRequest.fetchNext(new CometChat.CallbackListener<List<MessageThread>>() {
  @Override
  public void onSuccess(List<MessageThread> threads) {
      for (MessageThread thread : threads) {
          Log.d(TAG, "Thread " + thread.getParentMessageId()
                  + " has " + thread.getReplyCount() + " replies");
      }
  }

  @Override
  public void onError(CometChatException e) {
      Log.e(TAG, "Threads fetch failed: " + e.getMessage());
  }
});

val threadsRequest = ThreadsRequest.ThreadsRequestBuilder()
  .setParticipatedByMe(true)
  .setLimit(30)
  .build()

threadsRequest.fetchNext(object : CometChat.CallbackListener<List<MessageThread>>() {
  override fun onSuccess(threads: List<MessageThread>?) {
      threads?.forEach { thread ->
          Log.d(TAG, "Thread ${thread.parentMessageId} has ${thread.replyCount} replies")
      }
  }

  override fun onError(e: CometChatException?) {
      Log.e(TAG, "Threads fetch failed: ${e?.message}")
  }
})

Call fetchNext() repeatedly to page forward; hasMore() tells you whether more pages exist. A ThreadsRequest is forward-only — there is no fetchPrevious(). To refresh the list from the top, build a new request from the builder and replace your list with its results. Calling fetchNext() while a fetch is already in flight fails with a request-in-progress error, and a setLimit() outside 1…1000 fails at fetch time rather than at build().

ThreadsRequestBuilder spells these setUid() / setGuid() — not the setUID() / setGUID() used by MessagesRequestBuilder. The two are mutually exclusive; setting both throws an IllegalArgumentException from build().

The MessageThread Model

Each row is a MessageThread — enough to render an inbox without fetching the parent message separately.

Method	Description
`getParentMessageId()`	The thread’s identity — the ID of its root message. Pass it to `subscribeToThread()`.
`getParentMessage()`	The root message as a full `BaseMessage`.
`getReplyCount()`	Number of replies in the thread.
`getLastReply()`	The most recent reply as a `BaseMessage`. `null` for a thread with no replies yet — expected, not an error.
`getConversationId()`	The ID of the conversation the thread belongs to.
`getReceiverType()`	`user` or `group`.
`getReceiverUid()`	The raw `UID`/`GUID` of the conversation — no name or avatar. Resolve those yourself via `CometChat.getUser()` / `CometChat.getGroup()`.
`isSubscribed()`	Always `true` for rows from a `setParticipatedByMe(true)` fetch — presence in the list is the subscription.
`getUnreadReplyCount()`	The unread reply count, or `null` when unknown. `null` is not `0`.
`getUpdatedAt()`	An opaque pagination cursor (unix seconds, no tiebreak). Do not sort your UI on it.
`getRawData()`	The untouched raw thread object — the escape hatch for any field not yet modelled.

To order rows in your UI, sort on getLastReply().getSentAt(), falling back to getParentMessage().getSentAt() for zero-reply threads — not on getUpdatedAt().

getUnreadReplyCount() returns null, not 0, when the count is unknown. Treat null as “no badge” rather than as zero unread.

The list starts empty for every user when the feature launches — it fills up as users reply, get mentioned, and subscribe to threads. There is no historical backfill.

Notification Preferences

The notification preference for replies gains a new value so users can be notified only for threads they are subscribed to: 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.

See Notification Preferences for how to read and update a user’s preferences.

Error Handling

Error	Meaning
`ERROR_INVALID_MESSAGEID`	The parent message ID was `0` or negative. The SDK rejects this locally, before any network call.
`ERR_MESSAGE_NO_ACCESS`	The user no longer has access to the message’s conversation (for example, they left or were banned from the group). Treat the thread as inaccessible and remove its row.
`ERR_MESSAGE_ID_NOT_FOUND`	The parent message does not exist (for example, it was deleted).

Next Steps

Threaded Messages

Send and fetch replies inside a thread

Mentions

@-mentions, which auto-subscribe a user to a thread

All Real Time Listeners

Every listener the SDK exposes, in one place

Save A Message

Bookmark a message privately, across conversations

​How State Works

​Subscribe to a Thread

​Unsubscribe from a Thread

​Read the Subscription State

​You are subscribed to your own messages

​Keeping your own copies in sync

​Reacting to Replies

​Fetch the Threads a User Participates In

​The MessageThread Model

​Notification Preferences

​Error Handling

​Next Steps

Threaded Messages

Mentions

All Real Time Listeners

Save A Message

How State Works

Subscribe to a Thread

Unsubscribe from a Thread

Read the Subscription State

You are subscribed to your own messages

Keeping your own copies in sync

Reacting to Replies

Fetch the Threads a User Participates In

The MessageThread Model

Notification Preferences

Error Handling

Next Steps