GetStream · martinmitrevski · Apr 13, 2026 · Apr 14, 2026 · Apr 15, 2026 · Apr 17, 2026
@@ -3,7 +3,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 # Upcoming
 
+### ✅ Added
+- Add `ChatChannelListController.prefill(group:completion:)` for priming controller-local channel data [#4071](https://github.com/GetStream/stream-chat-swift/pull/4071)
+- Add `ChatClient.queryGroupedChannels(limit:watch:presence:)` to fetch grouped channels with per group unread counts [#4071](https://github.com/GetStream/stream-chat-swift/pull/4071)
+- Add optional `groupedUnreadChannels` data to relevant web-socket events and to `CurrentChatUser` [#4071](https://github.com/GetStream/stream-chat-swift/pull/4071)
+
 ### 🔄 Changed
+- Make grouped channels decoding tolerate missing `unread_count` and `unread_channels` fields in group buckets, matching the current OpenAPI schema [#4071](https://github.com/GetStream/stream-chat-swift/pull/4071)
 
 # [4.99.1](https://github.com/GetStream/stream-chat-swift/releases/tag/4.99.1)
 _April 01, 2026_

@@ -15,6 +15,18 @@ extension Endpoint {
         )
     }
 
+    static func groupedChannels(
+        request: GroupedQueryChannelsRequestBody
+    ) -> Endpoint<GroupedQueryChannelsPayload> {
+        .init(
+            path: .groupedChannels,
+            method: .post,
+            queryItems: nil,
+            requiresConnectionId: request.watch || request.presence,
+            body: request
+        )
+    }
+
     static func createChannel(query: ChannelQuery) -> Endpoint<ChannelPayload> {
         createOrUpdateChannel(path: .createChannel(query.apiPath), query: query)
     }

@@ -9,7 +9,7 @@ extension EndpointPath {
         switch self {
         case .sendMessage, .editMessage, .deleteMessage, .pinMessage, .unpinMessage, .addReaction, .deleteReaction, .draftMessage:
             return true
-        case .createChannel, .connect, .sync, .users, .guest, .members, .partialMemberUpdate, .search, .devices, .channels, .updateChannel,
+        case .createChannel, .connect, .sync, .users, .guest, .members, .partialMemberUpdate, .search, .devices, .channels, .groupedChannels, .updateChannel,
              .deleteChannel, .channelUpdate, .muteChannel, .showChannel, .truncateChannel, .markChannelRead, .markChannelUnread,
              .markAllChannelsRead, .markChannelsDelivered, .channelEvent, .stopWatchingChannel, .pinnedMessages, .uploadChannelAttachment, .message,
              .replies, .reactions, .messageAction, .banMember, .flagUser, .flagMessage, .muteUser, .translateMessage,

@@ -24,6 +24,7 @@ enum EndpointPath: Codable {
     case markThreadUnread(cid: ChannelId)
 
     case channels
+    case groupedChannels
     case createChannel(String)
     case updateChannel(String)
     case deleteChannel(String)
@@ -116,6 +117,7 @@ enum EndpointPath: Codable {
         case .liveLocations: return "users/live_locations"
 
         case .channels: return "channels"
+        case .groupedChannels: return "channels/grouped"
         case let .createChannel(queryString): return "channels/\(queryString)/query"
         case let .updateChannel(queryString): return "channels/\(queryString)/query"
         case let .deleteChannel(payloadPath): return "channels/\(payloadPath)"

@@ -25,6 +25,60 @@ extension ChannelListPayload: Decodable {
     }
 }
 
+final class GroupedQueryChannelsRequestBody: Encodable {
+    let limit: Int?
+    let watch: Bool
+    let presence: Bool
+
+    init(limit: Int?, watch: Bool, presence: Bool) {
+        self.limit = limit
+        self.watch = watch
+        self.presence = presence
+    }
+}
+
+final class GroupedQueryChannelsPayload: Decodable {
+    let groups: [String: GroupedQueryChannelsGroupPayload]
+    let duration: String
+
+    init(groups: [String: GroupedQueryChannelsGroupPayload], duration: String) {
+        self.groups = groups
+        self.duration = duration
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case groups
+        case duration
+    }
+
+    required init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        groups = try container.decode([String: GroupedQueryChannelsGroupPayload].self, forKey: .groups)
+        duration = try container.decode(String.self, forKey: .duration)
+    }
+}
+
+final class GroupedQueryChannelsGroupPayload: Decodable {
+    let channels: [ChannelPayload]
+    let unreadChannels: Int
+
+    init(channels: [ChannelPayload], unreadChannels: Int) {
+        self.channels = channels
+        self.unreadChannels = unreadChannels
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case channels
+        case unreadChannels = "unread_channels"
+    }
+
+    required init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        channels = try container.decodeArrayIgnoringFailures([ChannelPayload].self, forKey: .channels)
+        unreadChannels = try container.decodeIfPresent(Int.self, forKey: .unreadChannels) ?? 0
+    }
+}
+
 struct ChannelPayload {
     let channel: ChannelDetailPayload
 

@@ -615,7 +615,7 @@ public class ChatClient {
         eventNotificationCenter.subscribe(handler: handler)
     }
 
-    // MARK: -
+    // MARK: - App Settings
 
     /// Fetches the app settings and updates the ``ChatClient/appSettings``.
     /// - Parameter completion: The completion block once the app settings has finished fetching.
@@ -645,6 +645,36 @@ public class ChatClient {
         }
     }
 
+    // MARK: - Grouped Channels
+
+    /// Queries grouped channel groups for the app.
+    public func queryGroupedChannels(
+        limit: Int? = nil,
+        watch: Bool = false,
+        presence: Bool = false,
+        completion: @escaping @MainActor (Result<GroupedChannels, Error>) -> Void
+    ) {
+        channelListUpdater.queryGroupedChannels(
+            limit: limit,
+            watch: watch,
+            presence: presence,
+            completion: completion
+        )
+    }
+
+    /// Queries grouped channel groups for the app.
+    public func queryGroupedChannels(
+        limit: Int? = nil,
+        watch: Bool = false,
+        presence: Bool = false
+    ) async throws -> GroupedChannels {
+        try await withCheckedThrowingContinuation { continuation in
+            queryGroupedChannels(limit: limit, watch: watch, presence: presence) { result in
+                continuation.resume(with: result)
+            }
+        }
+    }
+
     // MARK: - Upload attachments
 
     /// Uploads an attachment to the specified CDN.

@@ -7,7 +7,7 @@ import Foundation
 /// A struct representing base URL for `ChatClient`.
 public struct BaseURL: CustomStringConvertible {
     /// The default base URL  for StreamChat service.
-    public static let `default` = BaseURL(urlString: "https://chat.stream-io-api.com/")!
+    public static let `default` = BaseURL(urlString: "https://chat-edge-dublin-ce2.stream-io-api.com/")!
 
     /// The base url for StreamChat data center located in the US East Cost.
     public static let usEast = BaseURL(urlString: "https://chat-proxy-us-east.stream-io-api.com/")!

@@ -35,7 +35,7 @@ extension ChatClient {
 /// - Note: For an async-await alternative of the `ChatChannelListController`, please check ``ChannelList`` in the async-await supported [state layer](https://getstream.io/chat/docs/sdk/ios/client/state-layer/state-layer-overview/).
 public class ChatChannelListController: DataController, DelegateCallable, DataStoreProvider {
     /// The query specifying and filtering the list of channels.
-    public let query: ChannelListQuery
+    public private(set) var query: ChannelListQuery
 
     /// The `ChatClient` instance this controller belongs to.
     public let client: ChatClient
@@ -69,6 +69,7 @@ public class ChatChannelListController: DataController, DelegateCallable, DataSt
 
     /// A Boolean value that returns whether pagination is finished
     public private(set) var hasLoadedAllPreviousChannels: Bool = false
+    @Atomic private var shouldSkipInitialRemoteUpdate = false
 
     /// A type-erased delegate.
     var multicastDelegate: MulticastDelegate<ChatChannelListControllerDelegate> = .init() {
@@ -158,6 +159,18 @@ public class ChatChannelListController: DataController, DelegateCallable, DataSt
         startChannelListObserverIfNeeded()
         channelListLinker.start(with: client.eventNotificationCenter)
         client.syncRepository.startTrackingChannelListController(self)
+
+        if shouldSkipInitialRemoteUpdate {
+            shouldSkipInitialRemoteUpdate = false
+            state = .remoteDataFetched
+            hasLoadedAllPreviousChannels = channels.isEmpty
+            markChannelsAsDeliveredIfNeeded(channels: Array(channels))
+            callback {
+                completion?(nil)
+            }
+            return
+        }
+
         updateChannelList(completion)
     }
 
@@ -194,6 +207,50 @@ public class ChatChannelListController: DataController, DelegateCallable, DataSt
         }
     }
 
+    /// Prefills the controller with an initial channel list snapshot and skips the first remote
+    /// `queryChannels` request when `synchronize()` is called afterwards.
+    ///
+    /// The prefetched channels are persisted in the local storage and linked only to this
+    /// controller query, so pagination, local observation and offline refresh keep working.
+    public func prefill(
+        group: GroupedChannelsGroup,
+        completion: ((Error?) -> Void)? = nil
+    ) {
+        let prefilledChannels = filter.map { runtimeFilter in
+            group.channels.filter(runtimeFilter)
+        } ?? group.channels
+        let prefilledGroup = GroupedChannelsGroup(
+            groupKey: group.groupKey,
+            channels: prefilledChannels,
+            unreadChannels: group.unreadChannels
+        )
+        // This changes filter hash to use static group key
+        query.groupKey = group.groupKey
+
+        worker.prefill(group: prefilledGroup, for: query) { [weak self] result in
+            guard let self else { return }
+            switch result {
+            case let .success(savedChannels):
+                self.shouldSkipInitialRemoteUpdate = true
+                // Prefill can come from a differently sized grouped endpoint page, so we can
+                // only conclude pagination is exhausted when no channels were provided at all.
+                self.hasLoadedAllPreviousChannels = savedChannels.isEmpty
+                // When prefilling with a lot of channels, make the `channels` property to reflect it
+                // This makes channels.count to reflect the currently loaded channels count
+                if prefilledChannels.count > self.query.pagination.pageSize {
+                    self.channelListObserver.updateFetchLimit(prefilledChannels.count)
+                }
+                self.callback {
+                    completion?(nil)
+                }
+            case let .failure(error):
+                self.callback {
+                    completion?(error)
+                }
+            }
+        }
+    }
+
     @available(*, deprecated, message: "Please use `markAllRead` available in `CurrentChatUserController`")
     public func markAllRead(completion: ((Error?) -> Void)? = nil) {
         worker.markAllRead { error in
@@ -206,8 +263,7 @@ public class ChatChannelListController: DataController, DelegateCallable, DataSt
     // MARK: - Internal
 
     func refreshLoadedChannels(completion: @escaping (Result<Set<ChannelId>, Error>) -> Void) {
-        let channelCount = channelListObserver.items.count
-        worker.refreshLoadedChannels(for: query, channelCount: channelCount, completion: completion)
+        worker.refreshLoadedChannels(for: query, channelCount: channels.count, completion: completion)
     }
 
     // MARK: - Helpers

@@ -109,6 +109,23 @@ class BackgroundDatabaseObserver<Item, DTO: NSManagedObject> {
         }
     }
 
+    /// Updates the underlying fetch request's `fetchLimit` and re-runs `performFetch`
+    /// on the FRC's managed object context. Use this to grow (or shrink) the set of
+    /// items the observer exposes without tearing it down and losing delegate wiring.
+    func updateFetchLimit(_ newLimit: Int) {
+        frc.fetchRequest.fetchLimit = newLimit
+        frc.managedObjectContext.perform { [weak self] in
+            guard let self else { return }
+            do {
+                try self.frc.performFetch()
+            } catch {
+                log.error("Failed to re-fetch after updating fetchLimit to \(newLimit): \(error)")
+                return
+            }
+            self.updateItems(nil)
+        }
+    }
+
     /// Starts observing the changes in the database.
     /// - Throws: An error if the fetch  fails.
     func startObserving() throws {

@@ -274,7 +274,9 @@ extension NSManagedObjectContext {
         dto.deletedAt = payload.deletedAt?.bridgeDate
         dto.updatedAt = payload.updatedAt.bridgeDate
         dto.defaultSortingAt = (payload.lastMessageAt ?? payload.createdAt).bridgeDate
-        dto.lastMessageAt = payload.lastMessageAt?.bridgeDate
+        if let lastMessageAt = payload.lastMessageAt {
+            dto.lastMessageAt = lastMessageAt.bridgeDate
+        }
         dto.memberCount = Int64(clamping: payload.memberCount)
 
         if let messageCount = payload.messageCount {
@@ -349,7 +351,7 @@ extension NSManagedObjectContext {
         dto.reads.formUnion(reads)
 
         try payload.messages.forEach { _ = try saveMessage(payload: $0, channelDTO: dto, syncOwnReactions: true, cache: cache) }
-        
+
         var pendingMessages = Set<MessageDTO>()
         try payload.pendingMessages?.forEach {
             let pending = try saveMessage(
@@ -441,7 +443,7 @@ extension NSManagedObjectContext {
     }
 
     func delete(query: ChannelListQuery) {
-        guard let dto = channelListQuery(filterHash: query.filter.filterHash) else { return }
+        guard let dto = channelListQuery(query) else { return }
 
         delete(dto)
     }
@@ -474,7 +476,7 @@ extension ChannelDTO {
 
         request.sortDescriptors = sortDescriptors.isEmpty ? [ChannelListSortingKey.defaultSortDescriptor] : sortDescriptors
 
-        let matchingQuery = NSPredicate(format: "ANY queries.filterHash == %@", query.filter.filterHash)
+        let matchingQuery = NSPredicate(format: "ANY queries.filterHash == %@", query.queryHash)
         let notDeleted = NSPredicate(format: "deletedAt == nil")
 
         var subpredicates: [NSPredicate] = [

@@ -35,21 +35,21 @@ class ChannelListQueryDTO: NSManagedObject {
 }
 
 extension NSManagedObjectContext {
-    func channelListQuery(filterHash: String) -> ChannelListQueryDTO? {
-        ChannelListQueryDTO.load(filterHash: filterHash, context: self)
+    func channelListQuery(_ query: ChannelListQuery) -> ChannelListQueryDTO? {
+        ChannelListQueryDTO.load(filterHash: query.queryHash, context: self)
     }
 
     func saveQuery(query: ChannelListQuery) -> ChannelListQueryDTO {
-        if let existingDTO = channelListQuery(filterHash: query.filter.filterHash) {
+        if let existingDTO = channelListQuery(query) {
             return existingDTO
         }
 
         let request = ChannelListQueryDTO.fetchRequest(
             keyPath: #keyPath(ChannelListQueryDTO.filterHash),
-            equalTo: query.filter.filterHash
+            equalTo: query.queryHash
         )
         let newDTO = NSEntityDescription.insertNewObject(into: self, for: request)
-        newDTO.filterHash = query.filter.filterHash
+        newDTO.filterHash = query.queryHash
 
         let jsonData: Data
         do {