Retrieve a list of messages

Open channels and group channels use different method to retrieve messages. For open channels, use MessageListParams or PreviousMessageListQuery to retrieve messages from a certain reference point. Meanwhile, loadPrevious() and loadNext() in Message collection retrieve messages sent and received in a group channel.

Messages in open channels

Using the getMessagesByTimestamp() method or the getMessagesByMessageId() method, you can retrieve messages before or after a reference point, which can be a specific timestamp in Unix milliseconds or a message ID in an open channel.

Those methods have two parameters, which are a reference point of message retrieval and a params parameter for MessageListParams. Under the MessageListParams object, you can specify values to properties such as previousResultSize, messageTypeFilter, and customType. The following code shows several types of parameters that you can configure to customize a message query.

KotlinKTX

val params = MessageListParams().apply {
    inclusive = true
    previousResultSize = 5
    nextResultSize = 5
    reverse = false
    messageTypeFilter = ALL
    customType = "promotion"
    // ...
}
// Use the following code to get messages based on timestamp.
// TIMESTAMP should be in Unix milliseconds.
channel.getMessagesByTimestamp(TIMESTAMP, params) { messages, e ->
    if (e != null) {
        // Handle error.
    }
    // A list of previous and next messages of a specified timestamp is successfully retrieved.
    // Through the messages parameter of the callback handler,
    // you can access and display the data of each message from the result list
    // that the Sendbird server has passed to the callback method.
}
// Use the following code to get messages based on message ID.
channel.getMessagesByMessageId(MESSAGE_ID, params) { messages, e ->
    if (e != null) {
        // Handle error.
    }
    // A list of previous and next messages of a specified message ID is successfully retrieved.
    // Through the messages parameter of the callback handler,
    // you can access and display the data of each message from the result list
    // that the Sendbird server has passed to the callback method.
}

MessageListParams

This table only contains properties shown in the code above. To see the comprehensive list of all available methods and properties, see MessageListParams in API reference.

Property name	Type	Description
inclusive	boolean	Determines whether to include messages sent exactly on the specified timestamp or have the matching message ID.
previousResultSize	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.
nextResultSize	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 set to `true`, messages are returned from the most recent to the oldest. (Default: `false`)
messageTypeFilter	enum	Specifies the message type to filter the messages with the corresponding type. Acceptable values are `MessageTypeFilter.ALL`, `MessageTypeFilter.USER`, `MessageTypeFilter.FILE`, and `MessageTypeFilter.ADMIN`.
customType	string	Specifies the custom message type to filter the messages with the corresponding custom type.

If you wish to get previous messages using pagination instead of a time-based or ID-based reference point, use PreviousMessageListQuery and its load() method, which returns pages of BaseMessage objects. With returned messages, you can display the past messages in your UI once they are loaded. The following code is an example of retrieving previous messages in an open channel.

Kotlin

// There should only be a single instance per channel view.
val query = channel.createPreviousMessageListQuery(
    PreviousMessageListQueryParams().apply {
        messagePayloadFilter = MessagePayloadFilter().apply {
            includeMetaArray = true // Retrieve a list of messages along with their meta arrays.
            includeReactions = true // Retrieve a list of messages along with their reactions.
        }
        limit = 20
        reverse = false
    }
)
// Retrieve previous messages.
query.load() { messages, e ->
    if (e != null) {
        // Handle error.
    }
    // ...
}

PreviousMessageListQueryParams

This table only contains properties shown in the code above. To see the comprehensive list of all available methods and properties, see PreviousMessageListQueryParams in API reference.

Property name	Type	Description
messagePayloadFilter	`MessagePayloadFilter`	Determines which information to retrieve along with the messages, such as `includeMetaArray` and `includeReactions`.
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 `20`.
reverse	boolean	Determines whether to sort the retrieved messages in reverse order. If `true`, returns a list of messages which the latest comes at first and the earliest at last. the results are sorted in reverse order. If `false`, returns a list of messages which the earliest comes at first and the latest at last.

Messages in group channels

A chat view of messages in a group channel should be drawn with a MessageCollection instance. To retrieve messages within the collection, check if there are more messages to load through hasPrevious or hasNext first, then call loadPrevious or loadNext, respectively. Then the previous or next page of messages is retrieved. To learn more about message collection, see the Message collection page under Local caching.

KotlinKTX

// Get the next page of messages.
if (collection.hasNext) {
    collection.loadNext { messages, e ->
        if (e != null) {
            // Handle error.
            return@loadNext
        }
        // Add messages to your data source.
    }
}
// Get the previous page of messages.
if (collection.hasPrevious) {
    collection.loadPrevious { messages, e ->
        if (e != null) {
            // Handle error.
            return@loadPrevious
        }
        // Add messages to your data source.
    }
}

On this page

Messages in open channels Messages in group channels

Sample app