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(_:params:completionHandler:) method or the getMessagesByMessageId(_:params:completionHandler:) 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.

Swift

let params = MessageListParams()
params.previousResultSize = 5
params.nextResultSize = 5
params.replyType = .all
params.includeThreadInfo = true
    
openChannel.getMessagesByTimestamp(Int64.max, params: params) { messages, error in
    guard error == nil else {
        // Handle error.
        return
    }
    
    // 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.
}
    
openChannel.getMessagesByMessageId(123456, params: params) { messages, error in
    guard error == nil else {
        // Handle error.
        return
    }
    
    // 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. See the API reference for a complete list of properties.

Property name	Type	Description
isInclusive	Bool	Determines whether to include messages sent exactly on the specified timestamp or have the matching message ID. (Default: `false`)
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. (Default: `20`)
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. (Default: `0`)
reverse	Bool	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	MessageTypeFilter	Specifies the message type to filter the messages with the corresponding type. Acceptable values are `.all`, `.user`, `.file`, and `.admin`. (Default: `.all`)
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 loadNextPage(completionHandler:) 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.

Swift

class CustomViewController: ViewController {
    var channel: OpenChannel?
    var query: PreviousMessageListQuery?
    
    func createQuery() {
        // There should be one single instance per channel.
        self.query = channel?.createPreviousMessageListQuery { params in
            // The params is the PreviousMessageListQueryParams object.
            params.customTypeFilter = "greeting"
            params.limit = 20
            params.reverse = false
        }
    }
    
    func loadNextPage() {
        // Retrieve previous messages.
        self.query?.loadNextPage(completionHandler: { messages, error in
            guard error == nil else {
                // Handle error.
                return
            }
        })
    }
}

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
limit	UInt	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	Bool	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`)
customTypeFilter	String	Specifies the custom type of messages to include in the result.

Messages in group channels

A chat view of 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.

Swift

if collection.hasNext {
    collection.loadNext { messages, error in
        guard error == nil else {
            // Handle error.
            return
        }
        // Add messages to your data source.
    }
}
    
if collection.hasPrevious {
    collection.loadPrevious { messages, error in
        guard error == nil else {
            // Handle error.
            return
        }
        // Add messages to your data source.
    }
}

On this page

Messages in open channels Messages in group channels

Sample app