Message threading

Message threading is a feature that allows users to ask questions, give feedback or add context to a specific message without disrupting the conversation flow. A message thread refers to a collection of messages grouped together, consisting of a parent message and its replies. It can have the following elements:

• A message can have a thread of replies.
• A message that has a thread of replies is a parent message.
• A parent message and its threaded replies are collectively called a message thread.
• Every message within a thread, whether it's parent or reply, is a threaded message.
• A message that doesn't have any replies is an unthreaded message.

Message threading can be widely used to help conversations flow smoothly while keeping users engaged. Message replies in a thread are common among popular messaging platforms, such as Slack and iMessage.

• Conversation flow: Without message threading, it's hard to specify which message a channel member is responding to. Users would have to explain the context of their response, potentially confusing other channel members and distracting them from reading new messages. Message threads can help everyone stay engaged and carry on their conversation without any interferences.

• In-depth discussions: By allowing users to reply to each other's messages in a thread, they can have more in-depth conversations on one topic. They're able to ask follow-up questions or provide more detailed explanations to a specific message without interrupting others in the channel. Message threads can encourage users to start topic-specific discussions separate from the main channel conversation.

Refer to the following limitations before using the message threading feature:

• Message threading doesn't integrate with SyncManager.
• SDK only supports 1-depth threads, meaning you can only add reply messages to non-reply messages. You can't add a reply to a reply message.
• You can only reply to text and file messages, not admin messages. However, you can add admin type messages as a reply to another message.

You can retrieve messages and their replies in a specific thread.

The loadNext() method of a PreviousMessageListQuery instance returns a list of BaseMessage objects. With this method, you can retrieve previous messages in a specific channel. To include the replies of the target messages in the results, you need to change the value of the includeReplies property in the PreviousMessageListQuery instance.

The following table lists the properties of the PreviousMessageListQuery class.

final listQuery = PreviousMessageListQuery()
    ..channelType = channel.channelType
    ..channelUrl = channel.channelUrl
    ..includeReplies = INCLUDE_REPLIES
    ..includeThreadInfo = INCLUDE_THREAD_INFO
    ..includeParentMessageText = INCLUDE_PARENT_MESSAGE_TEXT;

You can also limit the number of returned messages or the order of the results.

try {
    final listQuery = PreviousMessageListQuery()
        ..channelType = channel.channelType
        ..channelUrl = channel.channelUrl
        ..limit = LIMIT
        ..reverse = REVERSE
        ..includeReplies = INCLUDE_REPLIES
        ..includeThreadInfo = INCLUDE_THREAD_INFO
        ..includeParentMessageText = INCLUDE_PARENT_MESSAGE_TEXT;

    final result = await listQuery.loadNext();
} catch (e) {
    // Handle error.
}

The getMessagesByTimestamp() and getMessagesById() methods of a BaseChannel instance returns a list of BaseMessage objects. By using these methods, you can retrieve messages in a specific channel according to a MessageListParams object.

The following table lists the properties of the MessageListParams.

final params = MessageListParams()
    ..includeReplies = true
    ..includeParentMessageText = true
    ..includeThreadInfo = true
    ..previousResultSize = 10;

By using the getMessagesByTimestamp() method, you can retrieve a set number of previous and next messages on both sides of a specific timestamp in a channel.

try {
    final result = await channel.getMessagesByTimestamp(
        TIMESTAMP,
        params,
    );
    // The result includes replies.
} catch (e) {
    // Handle error.
}

By using the getMessagesById() method, you can retrieve a set number of previous and next messages on both sides of a specific message ID in a channel.

try {
    final result = await channel.getMessagesById(
        MESSAGE_ID,
        params,
    );
    // The result includes replies.
} catch (e) {
    // Handle error.
}

You can retrieve replies of a parent message if you can determine the parent message like the following. First, create a ThreadMessageListParams object and set properties related to the thread where the target replies belong to.

final params = ThreadedMessageListParams()
    ..includeReplies = true
    ..includeParentMessageText = true
    ..includeThreadInfo = true
    ..previousResultSize = 10;

The following table lists the properties of the ThreadMessageListParams.

With the timestamp of the parent message, you can retrieve its replies by passing a TreadMessageListParams object as an argument to the parameter in the getThreadedMessagesByTimestamp method.

try {
    final result = await message.getThreadedMessagesByTimestamp(
        TIMESTAMP,
        params
    );
    // The result includes an object that contains a parent message and replies.
} catch (e) {
    // Handle error.
}

You can retrieve a specific message by creating and passing the MessageRetrievalParams object as a parameter to the getMessage() method.

try {
    final params = MessageRetrievalParams()
        ..messageId = MESSAGE_ID
        ..channelType = CHANNEL_TYPE
        ..channelUrl = CHANNEL_URL;

    final message = await BaseMessage.getMessage(params);
} catch (e) {
    // Handle error.
}

You can reply to a specific message in a channel through the sendUserMessage() or sendFileMessage() method. To do so, you should create a UserMessageParams or a FileMessageParams object and then specify the parentMessageId property of the object. Sending reply messages works the same way as sending regular messages to a channel except replies have an additional parentMessageId property.

When replying to a message through the sendUserMessage() method, specify and pass a UserMessageParams object to the method as a parameter.

try {
    final params = UserMessageParams()
        ..parentMessageId = PARENT_MESSAGE_ID;

    final result = await channel.sendUserMessage(params);
    // A reply to a specific message in the form of a text message is successfully sent.
} catch (e) {
    // Handle error.
}

The following table lists the properties of the UserMessageParams.

When replying with a file message through the sendFileMessage() method, specify and pass a FileMessageParams object as an argument to a parameter in the method.

try {
    final params = FileMessageParams().withFile(file, name: ‘FILE_NAME’)
        ..parentMessageId = PARENT_MESSAGE_ID;

    final result = await channel.sendFileMessage(params);
    // A reply to a specific message in the form of a file message is successfully sent
} catch (e) {
    // Handle error.
}

The following table lists the properties of the FileMessageParams.

You can retrieve message changelogs.

Each message changelog has distinct properties such as a timestamp of when a message was updated and a unique ID of a deleted message. Based on these two properties, you can retrieve message changelogs in two different ways: either by timestamp or by token. The getMessageChangeLogs() method requires a MessageChangeLogParams object to determine what messages to return. The results can also differ depending on a parameter specified in the method: either TIMESTAMP or TOKEN.

final params = MessageChangeLogParams()
    ..includeReplies = true
    ..includeThreadInfo = true
    ..includeParentMessageText = true;

The following table lists the properties of the MessageChangeLogParams.

You can retrieve message changelogs by specifying a timestamp. The results will include changelogs that were created after the specified timestamp.

try {
    final result = await channel.getMessageChangeLogs(
        timestamp: TIMESTAMP,
        params: params
    );
    // The result object may contain updated and deleted messages, the hasNext property, and the token for next results.
} catch (e) {
    // Handle error.
}

You can also retrieve message changelogs by specifying a token. The token is an opaque string that marks the starting point of the next page in the result set and it is included in the callback of the previous call. Based on the token, the next page will start with changelogs that were created after the specified token.

try {
    final result = await channel.getMessageChangeLogs(
        token: TOKEN,
        params: params
    );
    // The result object contains updated and deleted messages, information on the hasNext property, and the next results.
} catch (e) {
    // Handle error.
}

Once a reply is created or deleted from a thread, the onThreadInfoUpdated() method of channel event handlers is invoked. The method returns a threadInfoUpdateEvent object that has the latest information about the thread. This object needs to be applied to the parent message object.

Note: Like other messages, when a reply is created in a channel, the onMessageReceived() method of the channel event handler in client apps will be called.

Class MyClass with ChannelEventHandler {
    // Add this class via sendbird.addChannelEventHandler(UNIQUE_HANDLER_ID, this).
    // Remove with sendbird.removeChannelEventHandler(UNIQUE_HANDLER_ID) when it is no longer needed.

    @override
    void onThreadInfoUpdated(BaseChannel channel, ThreadInfoUpdateEvent event) {
        // Look for a message that has event.targetMessageId and apply it to the message.
        message.applyThreadInfoUpdateEvent(event);
    }
}