Threads & Replies

Threads and replies provide your users with a way to go into more detail about a specific topic.

This can be very helpful to keep the conversation organized and reduce noise. To create a thread you simply send a message with a parent_id. Have a look at the example below:

await messageClient.SendMessageToThreadAsync(
  channel.Type,
  channel.Id,
  new MessageRequest { Text = "Hey, I am replying to a message!" },
  user.Id,
  parentId: message.Id);

If you specify show_in_channel, the message will be visible both in a thread of replies as well as the main channel.

Messages inside a thread can also have reactions, attachments and mention as any other message.

Thread Pagination

When you read a channel you do not receive messages inside threads. The parent message includes the count of replies which it is usually what apps show as the link to the thread screen. Reading a thread and paginating its messages works in a very similar way as paginating a channel.

// retrieve the first 20 messages inside the thread
await messageClient.GetRepliesAsync(message.Id, new MessagePaginationParams
{
  Limit = 20,
});

// retrieve the 20 more messages before the message with id "42"
await messageClient.GetRepliesAsync(message.Id, new MessagePaginationParams
{
  Limit = 20,
  IDLTE = "42",
});

Quote Message

Instead of replying in a thread, it’s also possible to quote a message. Quoting a message doesn’t result in the creation of a thread; the message is quoted inline.

To quote a message, simply provide the quoted_message_id field when sending a message:

await messageClient.SendMessageAsync(channel.Type, channel.Id, new MessageRequest
{
  Text = "This is the first message that quotes another message",
  QuotedMessageId = msg.Id, // Quote the initial message
}, user.Id);

Based on the provided quoted_message_id, the quoted_message field is automatically enriched when querying channels with messages. Example response:

{
  "id": "message_with_quoted_message",
  "text": "This is the first message that quotes another message",
  "quoted_message_id": "first_message_id",
  "quoted_message": {
    "id": "first_message_id",
    "text": "The initial message"
  }
}

Quoted messages are only available one level deep. If you want to access deeply quoted messages you will have to fetch them directly either finding the message in response of channel.query() or querying message by its ID. Example: Message A quotes Message B and Message B quotes Message C. In this case it’s not possible to access Message C through Message A directly. You have to fetch Message B from API in order to access it

Thread List

Query Threads

It is possible to query the list of threads that current user is participant of. This is useful to create thread list similar to what Slack or Discord has. Response will include threads with unread replies first, sorted by the latest reply timestamp in descending order. Threads with no unread replies will follow, also sorted by the latest reply timestamp in descending order.

const threads = await client.queryThreads();

for (const thread of threads) {
  const state = thread.state.getLatestValue();

  console.log(state.participants);
  console.log(state.replies);
  console.log(state.parentMessage.text);
  console.log(state.read); // read states of the participants
}

You can also paginate over the thread list or request specific number of latest replies per thread.

// Example: Get threads created by a specific user, updated after a certain date,
// sorted by creation date (newest first)
const { threads: page1, next: next1 } = await client.queryThreads({
  sort: [{ created_at: -1 }],
  filter: {
    created_by_user_id: { $eq: "user1" },
    updated_at: { $gte: "2024-01-01T00:00:00Z" },
  },
  limit: 10, // Get 10 threads per page
});

// request the next page
const { threads: page2, next: next2 } = await client.queryThreads({
  sort: [{ created_at: -1 }],
  filter: {
    created_by_user_id: { $eq: "user1" },
    updated_at: { $gte: "2024-01-01T00:00:00Z" },
  },
  limit: 10,
  next: next1,
});

Following is the list of supported options for querying threads:

nametypedescriptiondefaultoptional
reply_limitnumberNumber of latest replies to fetch per thread2✓
participant_limitnumberNumber of thread participants to request per thread100✓
limitnumberMaximum number of threads to return in response10✓
watchbooleanIf true, all the channels corresponding to threads returned in response will be watchedtrue✓
member_limitnumberNumber of members to request per thread channel100✓

Filtering and Sorting Threads

You can filter and sort threads using MongoDB-style query operators. This allows you to create more specific queries and organize the results according to your needs.

Supported Sort Fields

You can sort threads by the following fields:

  • active_participant_count: Number of active participants in the thread
  • created_at: Thread creation timestamp
  • last_message_at: Timestamp of the last message in the thread
  • parent_message_id: ID of the parent message
  • participant_count: Total number of participants in the thread
  • reply_count: Number of replies in the thread
  • updated_at: Thread last update timestamp

Use 1 for ascending order and -1 for descending order.

Allowed Sort Combinations

When sorting threads, below are the supported field combinations:

  1. has_unread, last_message_at, parent_message_id
  2. last_message_at, parent_message_id
  3. created_at
  4. updated_at
  5. reply_count
  6. participant_count
  7. active_participant_count
  8. parent_message_id

Default Sort

If no sort parameters are provided, threads are sorted by default using the following combination:

[{ "has_unread": -1 }, { "last_message_at": -1 }, { "parent_message_id": -1 }]

This means threads are sorted by:

  1. Unread status (unread threads first)
  2. Last message timestamp (newest first)
  3. Parent message ID (descending)

Supported Filter Fields

You can filter threads using the following fields and operators:

NameTypeSupported OperatorsDescription
channel_cidstring or list of strings$eq, $inFilter by channel CID
channel.disabledboolean$eqFilter by channel disabled field
parent_message_idstring or list of strings$eq, $inFilter by parent message ID
created_by_user_idstring or list of strings$eq, $inFilter by thread creator’s user ID
created_atstring (RFC3339 timestamp)$eq, $gt, $lt, $gte, $lteFilter by thread creation timestamp
updated_atstring (RFC3339 timestamp)$eq, $gt, $lt, $gte, $lteFilter by thread update timestamp
last_message_atstring (RFC3339 timestamp)$eq, $gt, $lt, $gte, $lteFilter by last message timestamp
// Get threads created by a specific user, updated after a certain date,
// sorted by creation date (newest first)
var filter = new Dictionary<string, object>
{
    { "created_by_user_id", new Dictionary<string, object> { { "$eq", "user1" } } },
    { "updated_at", new Dictionary<string, object> { { "$gte", "2024-01-01T00:00:00Z" } } }
};

var sort = new List<SortParameter>
{
    new SortParameter { Field = "created_at", Direction = SortDirection.Descending }
};

// First page
var opts = QueryThreadsOptions.Default
    .WithFilter(filter)
    .WithSortBy(sort)
    .WithLimit(10)
    .WithUserId(userId);

var response = await threadClient.QueryThreads(opts);

// Get next page using the 'next' token from the response
if (response.Next != null)
{
    var nextPageOpts = opts.WithNext(response.Next);
    var nextPage = await threadClient.QueryThreads(nextPageOpts);
}

Thread List Management

ThreadManager class offers built-in pagination handling for threads with own state store to access loaded threads. To access threads you can either subscribe to the ThreadManager state or access the latest value by calling getLatestValue on state property of the ThreadManager.

const threadManager = new ThreadManager({ client });

const unsubscribe = threadManager.state.subscribe((nextState) => {
  console.log(nextState.threads);
});

threadManager.loadNextPage();

// or
await threadManager.loadNextPage();

const { threads } = threadManager.state.getLatestValue();

Client instance already comes with one ThreadManager instance which can be accessed via threads property of the client ( client.threads ).

Event Handling Of Threads

Each thread instance comes with registerSubscriptions method which registers handlers to appropriate thread-related events. With subscriptions registered, the updates to the state are done automatically and can be accessed by subscribing to the state updates.

const { threads } = await client.queryThreads({ watch: true, limit: 1 });

const [thread] = threads;

thread.registerSubcsriptions();

const unsubscribe = thread.state.subscribe((nextState) => {
  console.log(nextState.replies);
});

Note that watch parameter is required when querying for threads in this case as without it, the channel to which the thread is linked won’t receive updates.

If you’re using ThreadManger to manage your list of threads, you can call registerSubscriptions method on the manager instance and the manager will automatically handle subscriptions (registration and cleanup) of the added and removed threads.

const threadManager = new ThreadManager({ client });

threadManager.registerSubscriptions();

await threadManager.loadNextPage();

// these threads are listening to linked channel events
const { threads } = threadManager.state.getLatestValue();

Get Thread By ID

This endpoint returns a thread by the given threadId.

const threadId = "<parent_message_id>";

const thread = await client.getThread(threadId, {
  watch: true, // optional
  reply_limit: 3, // optional
  member_limit: 0, // optional
  participant_limit: 10, // optional
});

Update Thread Title and Custom Data

You can assign a title and any additional custom data to each thread.

const threadId = "<parent_message_id>";

// optional
const thread = await client.getThread(threadId);
thread.registerSubcsriptions();

const { thread: updatedThread } = await client.partialUpdateThread(threadId, {
  set: {
    title: "New Title",
    extraData: "Hello World",
  },
});

console.log(updatedThread.title);
console.log(updatedThread.extraData);

// or if you're using optional approach (Thread instance)
const { title, custom } = thread.state.getLatestValue();
console.log(title, custom.extraData);

To get full type support for your custom data, you can extend ThreadResponseCustomData interface through module augmentation. Simply create a declaration file within your project and add your custom properties to our interface:

// yourDeclarationFile.d.ts
import "stream-chat";

declare module "stream-chat" {
  interface ThreadResponseCustomData {
    extraData?: string;
  }
}
Previous
Reactions
Next
Unread Reminders
© Getstream.io, Inc. All Rights Reserved.