/ SDKs / iOS
SDKs
Chat SDKs iOS v4
Chat SDKs iOS
Chat SDKs
iOS
Version 4

Retrieve a list of messages

Copy link

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

Copy link

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.

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

Copy link

This table only contains properties shown in the code above. See the API reference for a complete list of properties.

Property nameTypeDescription

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.

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

Copy link

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 nameTypeDescription

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

Copy link

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.

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.
    }
}