Thread Subscription - CometChat Docs

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. Users are automatically subscribed to a thread 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. Let’s see how to work with thread subscriptions in CometChat’s iOS SDK.

Available from Chat SDK v4.1.9. These APIs require CometChatSDK v4.1.9 or later.Thread subscription builds on Threaded Messages. A thread is identified by the ID of its parent message — there is no separate thread ID.

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.

Swift

let parentMessageId = 1

CometChat.subscribeToThread(parentMessageId: parentMessageId) { response in
    print("Subscribed to thread: \(response)")
} onError: { error in
    print("Failed to subscribe: \(error.errorDescription)")
}

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.

Swift

let parentMessageId = 1

CometChat.unsubscribeFromThread(parentMessageId: parentMessageId) { response in
    print("Unsubscribed from thread: \(response)")
} onError: { error in
    print("Failed to unsubscribe: \(error.errorDescription)")
}

Unsubscribing is 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

Every fetched message carries the logged-in user’s subscription state for its own thread on BaseMessage.threadSubscribed. It arrives with the message fetch, so rendering a subscribe control needs no extra network call and no separate state cache.

Swift

if message.threadSubscribed {
    // render "Unsubscribe from thread"
} else {
    // render "Subscribe to thread"
}

Because it is a plain Bool, read it only off a message you actually fetched:

Situation	`threadSubscribed`	How to treat it
Message fetched via `MessagesRequest`	Authoritative	Render the state directly.
Message that arrived live over the websocket	`false`	Means “not reported”, not “unsubscribed”.
Message you constructed locally	`false`	Not yet known.

A false on a message that was not fetched with the flag means “the server did not tell me”, not “the user is unsubscribed”. Only a fetched flag is authoritative. Render the unsubscribed state (an enabled “Subscribe” control) in the unknown case — never a spinner or a disabled control.

The property also has a setter, which is local only and performs no network call. It exists so you can align message objects you already hold with a truth you have just established — for example after a successful subscribeToThread:

Swift

CometChat.subscribeToThread(parentMessageId: parentMessageId) { _ in
    message.threadSubscribed = true   // local only; keeps your held objects in step
} onError: { error in
    print("Failed to subscribe: \(error.errorDescription)")
}

To change the actual subscription, always use subscribeToThread / unsubscribeFromThread.

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
`set(limit:)`	Page size. Thread rows are heavy — each carries a root message and a last reply.
`set(uid:)`	Scope the list to threads in the one-on-one conversation with this user. Mutually exclusive with `set(guid:)`.
`set(guid:)`	Scope the list to threads in this group. Mutually exclusive with `set(uid:)`.
`set(participatedByMe:)`	Defaults to `true`. Only the threads the logged-in user participates in are returned.

Swift

let threadsRequest = ThreadsRequest.ThreadsRequestBuilder()
    .set(limit: 30)
    .build()

threadsRequest.fetchNext { threads in
    for thread in threads {
        print("Thread \(thread.parentMessageId) has \(thread.replyCount) replies")
    }
} onError: { error in
    print("Threads fetch failed: \(error.errorDescription)")
}

Call fetchNext repeatedly to page forward; hasMore() tells you whether more pages exist. A ThreadsRequest is single-use and 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. Paging is internally keyed on a compound (updatedAt, id) cursor, matching the JS and Android SDKs. updatedAt alone is second-granular, so threads updated within the same second could not be separated by it and a page boundary could only step past the whole second — skipping every unseen row in it. Carrying the boundary row’s id makes the cursor address one exact row, so a block of same-second threads spills across pages instead of being dropped. You do not set this yourself; it matters only if you were previously working around duplicated or skipped rows.

The MessageThread Model

Each row is a MessageThread:

Property	Description
`parentMessageId`	The thread’s identity — the ID of its root message.
`parentMessage`	The root message as a full `BaseMessage`.
`replyCount`	Number of replies in the thread.
`lastReply`	The most recent reply as a `BaseMessage`. `nil` for a thread with no replies yet — expected, not an error.
`conversationId`	The ID of the conversation the thread belongs to.
`receiverType`	`user` or `group`.
`receiverUid`	The raw `UID`/`GUID` of the conversation. Resolve the display name and avatar yourself via `CometChat.getUser()` / `CometChat.getGroup()`.
`isSubscribed`	Always `true` for rows in this list — presence in the list is the subscription.
`unreadReplyCount`	Reserved for future use — currently `nil` (unknown), which is not the same as `0`.
`updatedAt`	Part of the internal pagination cursor (paired with the row’s id). Second-granular. Do not sort your UI on it.

To order rows in your UI, sort on lastReply?.sentAt, falling back to parentMessage?.sentAt for zero-reply threads — not on updatedAt.

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.

Keeping Your UI in Sync

The SDK does not expose a thread listener or thread-subscription callbacks. It deliberately does not cache subscription state: the state it could not fully observe drifted, so the server’s flag on the message is the single source of truth. Keep your UI in step yourself:

After your own subscribe/unsubscribe — update the message you hold by setting threadSubscribed in the success callback (local only, no network). This is the normal case and needs nothing else.
On the next fetch — threadSubscribed arrives with every fetched message, so a refresh always corrects the state.
For new replies — use the regular message listener (onTextMessageReceived and friends) and check parentMessageId to spot a threaded reply.

A subscribe or unsubscribe performed on the user’s other device produces no real-time event on this one. The state self-corrects on the next message fetch, so refresh when the app returns to the foreground.

Do not build a long-lived local cache of subscription state keyed by parent message id. That is exactly the design the SDK moved away from — it cannot observe every change, so it drifts. Read threadSubscribed off the message each time you render.

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 replies options.

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.

Quoted replies are a separate preference

A quoted reply (a reply to one specific message) and a threaded reply (a message posted into a thread) are configured independently, through two different enums. They are not interchangeable — the raw value 4 means something different on each.

Enum	Set with	Fourth option
`RepliesOptions`	`set(repliesPreference:)`	`SUBSCRIBE_TO_SUBSCRIBED_THREADS`
`QuotedRepliesOptions`	`set(quotedRepliesPreference:)`	`SUBSCRIBE_TO_QUOTES_ON_OWN_MESSAGES`

Swift

let groupPreferences = CometChatNotifications.GroupPreferences()

// Threaded replies: only threads this user follows.
groupPreferences.set(repliesPreference: .SUBSCRIBE_TO_SUBSCRIBED_THREADS)

// Quoted replies: only quotes of this user's own messages.
groupPreferences.set(quotedRepliesPreference: .SUBSCRIBE_TO_QUOTES_ON_OWN_MESSAGES)

Both preferences exist on group and one-on-one preferences alike. See Notification Preferences for how to read and update a user’s preferences.

Error Handling

Error	Meaning
`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).

​Subscribe to a Thread

​Unsubscribe from a Thread

​Read the Subscription State

​Fetch the Threads a User Participates In

​The MessageThread Model

​Keeping Your UI in Sync

​Notification Preferences

​Quoted replies are a separate preference

​Error Handling

Subscribe to a Thread

Unsubscribe from a Thread

Read the Subscription State

Fetch the Threads a User Participates In

The MessageThread Model

Keeping Your UI in Sync

Notification Preferences

Quoted replies are a separate preference

Error Handling