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.
Load channel messages
The load()
method of a PreviousMessageListQuery
instance returns a list of BaseMessage
objects. 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.
PreviousMessageListQuery
The following table lists the properties of this 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. |
replyType | string | Specifies the type of message to include in the results. |
includeParentMessageInfo | boolean | Determines whether to include the information of the parent messages in the result. (Default: false) |
| boolean | (Deprecated) Determines whether replies are included in the results. |
| 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 |
load()
List of parameters
Parameter name | Type | Description |
---|---|---|
LIMIT | number | 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. |
MESSAGE_TYPE_FILTER | string | Restricts the search scope only to retrieve messages with the specified message type. |
Load messages by timestamp or message ID
The getMessagesByTimestamp()
and getMessagesByMessageId()
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.
MessageListParams
The following table lists the properties of this class.
Property name | 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. |
replyType | string | Specifies the type of message to include in the results. |
includeParentMessageInfo | boolean | Determines whether to include the information of the parent messages in the result. (Default: false) |
| boolean | (Deprecated) Determines whether replies are included in the results. |
| 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 |
By timestamp
You can retrieve a set number of messages of previous and next messages on both sides of a specific timestamp in a channel by using the getMessagesByTimestamp()
method.
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.
List of parameters
Parameter name | 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
Property name | Type | Description |
---|---|---|
previousResultSize | int | Specifies the number of messages to retrieve that were sent before the specified timestamp. |
nextResultSize | int | Specifies the number of messages to retrieve that were sent after the specified timestamp. |
isInclusive | boolean | Determines whether to include the messages with the matching timestamp in the results. |
reverse | boolean | Determines whether to sort the retrieved messages in reverse order. If false, the results are in ascending order. |
includeParentMessageInfo | boolean | Determines whether to include the information of the parent messages in the result. (Default: false) |
| 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 |
With the timestamp of the parent message, you can retrieve its replies by passing a TreadedMessageListParams
object as an argument to the parameter in the getThreadedMessagesByTimestamp()
method.
List of parameters
Parameter name | 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 to the getMessage()
method as a parameter.
MessageRetrievalParams
Property name | Description |
---|---|
messageId | Type: long |
channelType | Type: String |
channelUrl | Type: String |
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
Property name | Type | Description |
---|---|---|
parentMessageId | 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 |
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
Argument | Type | Description |
---|---|---|
| string | Specifies the URL of the file to be attached to the message |
| 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 |
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
The following table lists the properties of this class.
Property | Type | Description |
---|---|---|
includeThreadInfo | boolean | Determines whether to include the thread information of the messages in the results when the results contain parent messages. |
replyType | string | Specifies the type of message to include in the results. |
includeParentMessageInfo | boolean | Determines whether to include the information of the parent messages in the result. (Default: false) |
| boolean | (Deprecated) Determines whether replies are included in the results. |
| 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 |
By timestamp
You can retrieve the message changelogs by specifying a timestamp. The results will include changelogs that were created after the specified timestamp.
List of parameters
Parameter name | 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.
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.
List of parameters
Parameter name | Description |
---|---|
channel | Type: BaseChannel |
threadInfoUpdateEvent | Type: ThreadInfoUpdateEvent |
If a reply message is created, onMessageReceived
will be called with that reply message. A user will have to find the parent message with the parentMessageID
property in that message object.
If the parent message is not in the message view stack and the user wants to get the parent message object, they can do so by calling
BaseMessage.getMessage(params, handler)
to retrieve the parent message object.
Once the reply message has been created, the onThreadInfoUpdated()
event handler will be called since the thread info has been changed. To update thread information, the user should find the matching parent message with targetMessageID
and use the parentMessage.applyThreadInfoUpdateEvent()
method.