Channel Pagination
The channel query endpoint allows you to paginate messages, watchers, and members for a channel. Messages use ID-based pagination for consistency, while members and watchers use offset-based pagination.
Message Pagination
Message pagination uses ID-based parameters rather than simple offset/limit. This approach improves performance and prevents issues when the message list changes while paginating.
For example, if you fetched the first 100 messages and want to load the next 100, pass the ID of the oldest message (when paginating in descending order) or the newest message (when paginating in ascending order).
Pagination Parameters
| Parameter | Description |
|---|---|
id_lt |
Retrieve messages older than (less than) the ID |
id_gt |
Retrieve messages newer than (greater than) the ID |
id_lte |
Retrieve messages older than or equal to the ID |
id_gte |
Retrieve messages newer than or equal to the ID |
id_around |
Retrieve messages around a specific message ID |
let messageId: MessageId = "123"
let channelId = ChannelId(type: .messaging, id: "general")
let controller = chatClient.channelController(for: channelId)
// Load messages around a specific message (id_around)
controller.loadPageAroundMessageId(messageId) { error in
if let error = error {
print(error)
} else {
print(controller.messages)
// Load newer messages (id_gt)
controller.loadNextMessages(limit: 10) { error in
print(error ?? controller.messages)
// Load older messages (id_lt)
controller.loadPreviousMessages(limit: 10) { error in
print(error ?? controller.messages)
}
}
}
}
// Alternative: Use Chat for more granular control
let chat = chatClient.makeChat(for: channelId)
// Each call updates chat.state.messages
// Messages newer than ID (id_gt)
try await chat.loadMessages(after: messageId, limit: 10)
print(chat.state.messages)
// Messages older than ID (id_lt)
try await chat.loadMessages(before: messageId, limit: 10)
print(chat.state.messages)
// Messages around ID (id_around)
try await chat.loadMessages(around: messageId, limit: 10)
print(chat.state.messages)Member and Watcher Pagination
Members and watchers use limit and offset parameters for pagination.
| Parameter | Description | Maximum |
|---|---|---|
limit |
Number of records to return | 300 |
offset |
Number of records to skip | 10000 |
let channelId = ChannelId(type: .messaging, id: "general")
// Members: the controller sets the offset from the members it has already loaded
let memberListController = chatClient.memberListController(
query: .init(cid: channelId, pageSize: 20)
)
memberListController.synchronize { error in
guard error == nil else { return }
// Load the next page of members
memberListController.loadNextMembers(limit: 20) { error in
print(memberListController.members)
}
}
// Watchers: the controller sets the offset from the watchers it has already loaded
let watcherListController = chatClient.watcherListController(
query: .init(cid: channelId, pagination: Pagination(pageSize: 20))
)
watcherListController.synchronize { error in
guard error == nil else { return }
// Load the next page of watchers
watcherListController.loadNextWatchers(limit: 20) { error in
print(watcherListController.watchers)
}
}To retrieve filtered and sorted members in a channel use the Query Members API