Chat SDKs Android v3

Chat SDKs Android

Chat SDKs

Android

Version 3

Sendbird Chat SDK v3 for Android is no longer supported as a new version is released. Check out our latest Chat SDK v4

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.

Benefits

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.

Limitations

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.
Message threading is limited to text and file messages. You can't send admin messages as replies or add replies to admin messages.

List messages along with their replies

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

First, messages in a channel must be retrieved. The load() method of a PreviousMessageListQuery instance returns a list of BaseMessage objects. By using this method, you can retrieve previous messages in a specific channel. If you want to include the replies of the target messages in the results, change the value of properties in the PreviousMessageListQuery instance.

List of properties of PreviousMessageListQuery

The following table lists the properties of the PreviousMessageListQuery class.

Property name	Type	Description
limit	int	Specifies the number of results to return per call. Acceptable values are 1 to 100, inclusive. The recommended value for this parameter is 30.
reverse	boolean	Determines whether to sort the retrieved messages in reverse order. If false, the results are in ascending order.
includeThreadInfo	boolean	Determines whether to include the thread information of the messages in the results when the results contain parent messages.
replyTypeFilter	string	Specifies the type of message to include in the results. - NONE (default): All messages that are not replies. These message may or may not have replies in its thread. - ALL: All messages including threaded and non-threaded parent messages as well as its replies. - ONLY_REPLY_TO_CHANNEL: Messages that are not threaded. It only includes the parent messages and replies that were sent to the channel.
includeParentMessageInfo	boolean	Determines whether to include the information of the parent messages in the result. (Default: false)
~~includeReplies~~	boolean	*(Deprecated)* Determines whether to include replies in the results.
~~includeParentMessageText~~	boolean	*(Deprecated)* Determines whether to include the parent message text in the results when the retrieved messages are replies in a thread. If the type of the parent message is `UserMessage`, the value is a message property. If it is `FileMessage`, the value is the name of the uploaded file.

PreviousMessageListQuery listQuery = groupChannel.createPreviousMessageListQuery();
listQuery.setLimit(LIMIT);
listQuery.setReverse(REVERSE);
listQuery.setReplyTypeFilter(ReplyTypeFilter.ALL);
listQuery.setMessagePayloadFilter(
        new MessagePayloadFilter.Builder()
                .setIncludeParentMessageInfo(true)
                .setIncludeThreadInfo(true)
                .build()
);

Based the query instance you set, you can retrieve previous messages in a specific channel using the load() method.

// Retrieving previous messages.
listQuery.load(new PreviousMessageListQuery.MessageListQueryResult() {
    @Override
    public void onResult(List<BaseMessage> list, SendBirdException e) {
        if (e != null) {
            // Handle error.
        }

        ...
    }
});

MessageListParams

You can also retrieve a list of BaseMessage objects through the getMessagesByTimestamp() and getMessagesByMessageId() methods of a BaseChannel instance. When using these methods, you can create and pass a MessageListParams object to the parameter.

The following table lists the properties of the MessageListParams class.

Property	Type	Description
previousResultSize	int	Specifies the number of messages to retrieve that were sent before the specified timestamp or message ID.
nextResultSize	int	Specifies the number of messages to retrieve that were sent after the specified timestamp or message ID.
isInclusive	boolean	Determines whether to include the messages with the matching timestamp or message ID in the results.
reverse	boolean	Determines whether to sort the retrieved messages in reverse order. If false, the results are in ascending order.
includeThreadInfo	boolean	Determines whether to include the thread information of the messages in the results when the results contain parent messages.
replyTypeFilter	string	Specifies the type of message to include in the results. - NONE (default): All messages that are not replies. These message may or may not have replies in its thread. - ALL: All messages including threaded and non-threaded parent messages as well as its replies. - ONLY_REPLY_TO_CHANNEL: Messages that are not threaded. It only includes the parent messages and replies that were sent to the channel.
includeParentMessageInfo	boolean	Determines whether to include the information of the parent messages in the result. (Default: false)
~~includeReplies~~	boolean	*(Deprecated)* Determines whether to include replies in the results.
~~includeParentMessageText~~	boolean	*(Deprecated)* Determines whether to include the parent message text in the results when the messages are replies in a thread. If the type of the parent message is `UserMessage`, the value is a message property. If it is `FileMessage`, the value is the name of the uploaded file.

MessageListParams params = new MessageListParams();
params.setPreviousResultSize(PREV_RESULT_SIZE);
params.setNextResultSize(NEXT_RESULT_SIZE);
params.setInclusive(INCLUSIVE);
params.setReverse(REVERSE);
params.setReplyTypeFilter(ReplyTypeFilter.ALL, ReplyTypeFilter.ONLY_REPLY_TO_CHANNEL, ReplyTypeFilter.NONE);
params.setIncludeThreadInfo(INCLUDE_THREAD_INFO);
params.setMessagePayloadFilter();

By timestamp

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

channel.getMessagesByTimestamp(TIMESTAMP, params, new BaseChannel.GetMessagesHandler() {
    @Override
    public void onResult(List<BaseMessage> messages, SendBirdException e) {
        if (e != null) {
            // Handle error.
        }

        // A list of previous and next messages on both sides of a specified timestamp is successfully retrieved.
        // Through the "messages" parameter of the onResult() callback method,
        // you can access and display the data of each message from the result list that Sendbird server has passed to the callback method.
        List<BaseMessage> messages = messages;
        ...
    }
});

List of arguments

Argument	Type	Description
`TIMESTAMP`	long	Specifies the timestamp to be the reference point for messages to retrieve, in Unix milliseconds format. Messages sent before or after the timestamp can be retrieved.

By message ID

You can retrieve a set number of previous and next messages on both sides of a specific message ID in a channel by using the getMessagesByMessageId() method.

channel.getMessagesByMessageId(MESSAGE_ID, params, new BaseChannel.GetMessagesHandler() {
    @Override
    public void onResult(List<BaseMessage> messages, SendBirdException e) {
        if (e != null) {
            // Handle error.
        }

        // A list of previous and next messages on both sides of a specified message ID is successfully retrieved.
        // Through the "messages" parameter of the onResult() callback method,
        // you can access and display the data of each message from the result list that Sendbird server has passed to the callback method.
        List<BaseMessage> messages = messages;
        ...
    }
});

List of arguments

Argument	Type	Description
`MESSAGE_ID`	long	Specifies the message ID to be the reference point for messages to retrieve. Messages sent before or after the message with the matching message ID can be retrieved.

List replies of a parent message

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.

ThreadMessageListParams params = new ThreadMessageListParams();
params.setPreviousResultSize(PREV_RESULT_SIZE);
params.setNextResultSize(NEXT_RESULT_SIZE);
params.setInclusive(INCLUSIVE);
params.setReverse(REVERSE);
params.setMessagePayloadFilter();

List of arguments

Argument	Type	Description
`PREV_RESULT_SIZE`	int	Specifies the number of messages to retrieve, which are sent previously before a specified timestamp. Note that the actual number of results may be larger than the set value when there are multiple messages with the same timestamp as the earliest message.
`NEXT_RESULT_SIZE`	int	Specifies the number of messages to retrieve, which are sent later after a specified timestamp. Note that the actual number of results may be larger than the set value when there are multiple messages with the same timestamp as the latest message.
`REVERSE`	boolean	Determines whether to sort the retrieved messages in reverse order. If false, the results are in ascending order.
`INCLUDE_PARENT_MESSAGE_INFO`	boolean	Determines whether to include the information of the parent messages in the result. (Default: false)
`INCLUSIVE`	boolean	Determines whether to include the messages with the matching timestamp in the results.
~~`INCLUDE_PARENT_MESSAGE_TEXT`~~	boolean	*(Deprecated)* Determines whether to include the parent message text in the results when the messages are replies in a thread. If the type of the parent message is `UserMessage`, the value is a message property. If it is `FileMessage`, the value is the name of the uploaded file.

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.

parentMessage.getThreadedMessagesByTimestamp(TIMESTAMP, params, new BaseMessage.GetThreadedMessagesHandler() {
    @Override
    public void onResult(BaseMessage parentMessage, List<BaseMessage> messages, SendBirdException e) {
        if (e != null) {
            // Handle error.
        }

        // A list of replies of the specified parent message timestamp is successfully retrieved.
        ...
    }
});

List of arguments

Argument	Type	Description
`TIMESTAMP`	long	Specifies the timestamp to be the reference point of the retrieval, in Unix milliseconds format.

View a single message

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

MessageRetrievalParams params = new MessageRetrievalParams(CHANNEL_URL, CHANNEL_TYPE, MESSAGE_ID);
...

BaseMessage.getMessage(params, new BaseMessage.GetMessageHandler() {
    @Override
    public void onResult(BaseMessage message, SendBirdException e) {
        if (e != null) {
            // Handle error.
        }

        // The specified message is successfully retrieved.
        ...
    }
});

List of arguments

Argument	Type	Description
`CHANNEL_URL`	String	Specifies the URL of the channel to retrieve the message.
`CHANNEL_TYPE`	BaseChannel.ChannelType	Specifies the type of the channel.
`MESSAGE_ID`	long	Specifies the unique ID of the message to retrieve.

Reply to a message

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.

Reply with a text message

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

UserMessageParams params = new UserMessageParams();
params.setParentMessageId(PARENT_MESSAGE_ID);

List of arguments

Argument	Type	Description
`PARENT_MESSAGE_ID`	long	Specifies the unique ID of a parent message. A parent message is a message that has a thread of replies. If the message sent through the `sendUserMessage()` method is a parent message, the value of this property is 0. If the message is a reply to a parent message, the value is the message ID of the parent message.

channel.sendUserMessage(params, new BaseChannel.SendUserMessageHandler() {
    @Override
    public void onSent(UserMessage userMessage, SendBirdException e) {
        if (e != null) {
            // Handle error.
        }

        // A reply to a specific message in the form of a text message is successfully sent.
        ...
    }
});

Reply with a file message

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.

FileMessageParams params = new FileMessageParams();
params.setParentMessageId(PARENT_MESSAGE_ID);

List of argument

Argument	Type	Description
`PARENT_MESSAGE_ID`	long	Specifies the unique ID of a parent message. A parent message is a message that has a thread of replies. If the message sent through the `sendFileMessage()` method is a parent message, the value of this property is 0. If the message is a reply to a parent message, the value is the message ID of the parent message.

channel.sendFileMessage(params, new BaseChannel.SendFileMessageHandler() {
    @Override
    public void onSent(FileMessage userMessage, SendBirdException e) {
        if (e != null) {
            // Handle error.
        }

        // A reply to a specific message in the form of a file message is successfully sent.
        ...
    }
});

List changelogs

You can retrieve message changelogs.

Load 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. Both getMessageChangeLogsSinceToken() and getMessageChangeLogsSinceTimestamp() methods require a parameter MessageChangeLogsParams object to determine what messages to return.

MessageChangeLogsParams params = new MessageChangeLogsParams();
params.setReplyTypeFilter(ReplyTypeFilter.ALL, ReplyTypeFilter.ONLY_REPLY_TO_CHANNEL, ReplyTypeFilter.NONE);
params.setIncludeThreadInfo(INCLUDE_THREAD_INFO);
params.setIncludeParentMessageText(INCLUDE_PARENT_MESSAGE_TEXT);

List of arguments

Argument	Type	Description
`INCLUDE_THREAD_INFO`	boolean	Determines whether to include the thread information of the messages in the results when the results contain parent messages.
`REPLY_TYPE_FILTER`	string	Specifies the type of message to include in the results. - NONE (default): All messages that are not replies. These message may or may not have replies in its thread. - ALL: All messages including threaded and non-threaded parent messages as well as its replies. - ONLY_REPLY_TO_CHANNEL: Messages that are not threaded. It only includes the parent messages and replies that were sent to the channel.
`INCLUDE_PARENT_MESSAGE_INFO`	boolean	Determines whether to include the information of the parent messages in the result. (Default: false)
~~`INCLUDE_REPLIES`~~	boolean	*(Deprecated)* Determines whether replies are included in the results.
~~`INCLUDE_PARENT_MESSAGE_TEXT`~~	boolean	*(Deprecated)* Determines whether to include the parent message text in the results when the messages are replies in a thread. If the type of the parent message is `UserMessage`, the value is a message property. If it is `FileMessage`, the value is the name of the uploaded file.

By timestamp

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

Note: The getMessageChangeLogsByTimestamp method is deprecated. Accordingly, use the getMessageChangeLogsSinceTimestamp() method instead.

channel.getMessageChangeLogsSinceTimestamp(TIMESTAMP, params, new BaseChannel.GetMessageChangeLogsHandler() {
    @Override
    public void onResult(List<BaseMessage> updatedMessages, List<Long> deletedMessageIds, boolean hasMore, String token, SendBirdException e) {
        if (e != null) {
            // Handle error.
        }

        // A list of message changelogs created after the specified timestamp is successfully retrieved.
        ...
    }
});

List of arguments

Argument	Type	Description
`TIMESTAMP`	long	Specifies the timestamp to be the reference point for changelogs to retrieve, in Unix milliseconds format.

By token

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.

Note: The getMessageChangeLogsByToken method is deprecated. Accordingly, use the getMessageChangeLogsSinceToken() method instead.

channel.getMessageChangeLogsSinceToken(TOKEN, params, new BaseChannel.GetMessageChangeLogsHandler() {
    @Override
    public void onResult(List<BaseMessage> updatedMessages, List<Long> deletedMessageIds, boolean hasMore, String token, SendBirdException e) {
        if (e != null) {
            // Handle error.
        }

        // A list of message changelogs created after the specified token is successfully retrieved.
        ...
    }
});

Event handler

Once a reply is created or deleted from a thread, the onThreadInfoUpdated() event handler 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.

@Override
public void onThreadInfoUpdated(BaseChannel channel, ThreadInfoUpdateEvent threadInfoUpdateEvent) {
    // Look for a message that has threadInfoUpdateEvent.targetMessageId
    // Apply the event to the message.
    parentMessage.applyThreadInfoUpdateEvent(threadInfoUpdateEvent);
}

List of parameters

Parameter name	Description
channel	Type: BaseChannel Specifies the channel that has the message thread.
threadInfoUpdateEvent	Type: ThreadInfoUpdateEvent Specifies a `ThreadInfoUpdateEvent` object that has the latest information about the thread.

On this page

Benefits Limitations List messages along with their replies

By timestamp By message ID

List replies of a parent message View a single message Reply to a message

Reply with a text message Reply with a file message

List changelogs

Load message changelogs By timestamp By token

Event handler

Sample app