GetStream · laevandus · Apr 13, 2026 · Apr 14, 2026 · Apr 15, 2026 · Apr 17, 2026
@@ -26,6 +26,11 @@ _May 13, 2026_
 _May 08, 2026_
 
 ## StreamChat
+### ✅ Added
+- Add `ChatClient.queryGroupedChannels(limit:presence:watch:)` to fetch grouped channels with per-group unread counts [#4076](https://github.com/GetStream/stream-chat-swift/pull/4076)
+- Add `ChatClient.channelListController(groupKey:dynamicFilter:)` for observing a single grouped channels group [#4076](https://github.com/GetStream/stream-chat-swift/pull/4076)
+- Add `ChatClient.makeChannelList(with:)` overload for observing a single grouped channels group in the state layer [#4076](https://github.com/GetStream/stream-chat-swift/pull/4076)
+- Add optional `groupedUnreadChannels` data to relevant web-socket events and `CurrentChatUser` [#4076](https://github.com/GetStream/stream-chat-swift/pull/4076)
 ### 🐞 Fixed
 - Fix image cache misses caused by non-deterministic caching keys in `StreamCDNRequester` [#4075](https://github.com/GetStream/stream-chat-swift/pull/4075)
 - Fix `ChatChannel.latestMessages` being wiped on mid-page pagination [#4077](https://github.com/GetStream/stream-chat-swift/pull/4077)

@@ -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,86 @@ extension ChannelListPayload: Decodable {
     }
 }
 
+final class GroupedQueryChannelsRequestBody: Encodable, Sendable {
+    let limit: Int?
+    let groups: [String: GroupedQueryChannelsRequestGroup]?
+    let watch: Bool
+    let presence: Bool
+
+    init(
+        limit: Int?,
+        groups: [String: GroupedQueryChannelsRequestGroup]?,
+        watch: Bool,
+        presence: Bool
+    ) {
+        self.limit = limit
+        self.groups = groups
+        self.watch = watch
+        self.presence = presence
+    }
+}
+
+struct GroupedQueryChannelsRequestGroup: Encodable, Sendable {
+    let limit: Int?
+    let next: String?
+    let prev: String?
+}
+
+final class GroupedQueryChannelsPayload: Decodable, Sendable {
+    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, Sendable {
+    let channels: [ChannelPayload]
+    let unreadChannels: Int
+    let next: String?
+    let prev: String?
+
+    init(
+        channels: [ChannelPayload],
+        unreadChannels: Int,
+        next: String? = nil,
+        prev: String? = nil
+    ) {
+        self.channels = channels
+        self.unreadChannels = unreadChannels
+        self.next = next
+        self.prev = prev
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case channels
+        case unreadChannels = "unread_channels"
+        case next
+        case prev
+    }
+
+    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
+        next = try container.decodeIfPresent(String.self, forKey: .next)
+        prev = try container.decodeIfPresent(String.self, forKey: .prev)
+    }
+}
+
 struct ChannelPayload {
     let channel: ChannelDetailPayload
 

@@ -619,7 +619,7 @@ public class ChatClient: @unchecked Sendable {
         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.
@@ -649,6 +649,37 @@ public class ChatClient: @unchecked Sendable {
         }
     }
 
+    // MARK: - Grouped Channels
+
+    /// Queries grouped channel groups for the app.
+    public func queryGroupedChannels(
+        limit: Int? = nil,
+        presence: Bool = false,
+        watch: Bool = false,
+        completion: @escaping @Sendable (Result<GroupedChannels, Error>) -> Void
+    ) {
+        channelListUpdater.queryGroupedChannels(
+            groupPagination: nil,
+            limit: limit,
+            watch: watch,
+            presence: presence,
+            completion: completion
+        )
+    }
+
+    /// Queries grouped channel groups for the app.
+    @discardableResult public func queryGroupedChannels(
+        limit: Int? = nil,
+        presence: Bool = false,
+        watch: Bool = false
+    ) async throws -> GroupedChannels {
+        try await withCheckedThrowingContinuation { continuation in
+            queryGroupedChannels(limit: limit, presence: presence, watch: watch) { 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, Sendable {
     /// 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/")!

@@ -28,6 +28,25 @@
     ) -> ChatChannelListController {
         .init(query: query, client: self, filter: filter)
     }
+
+    /// Creates a new `ChannelListController` for a single grouped channels group identified by `groupKey`.
+    ///
+    /// - Parameters:
+    ///   - groupKey: The group key returned by `queryGroupedChannels` (e.g. `"all"`, `"new"`,
+    ///     `"current"`) used to identify the underlying `ChannelListQueryDTO`.
+    ///   - dynamicFilter: A predicate consulted by ``ChannelListLinker`` when channel-related
+    ///     web-socket events arrive (`message.new`, `notification.added_to_channel`,
+    ///     `notification.message_new`, `channel.updated`, `channel.visible`). Returning `true`
+    ///     keeps/links the channel in this list's `ChannelListQueryDTO`; returning `false`
+    ///     unlinks it. Required so events for channels in other groups don't leak into this
+    ///     list when automatic filtering is enabled.
+    /// - Returns: A new instance of `ChatChannelListController`.
+    public func channelListController(
+        groupKey: String,
+        dynamicFilter: @escaping @Sendable (ChatChannel) -> Bool
+    ) -> ChatChannelListController {
+        .init(query: .init(groupKey: groupKey), client: self, filter: dynamicFilter)
+    }
 }
 
 /// `ChatChannelListController` is a controller class which allows observing a list of chat channels based on the provided query.
@@ -81,15 +100,26 @@
         }
     }
 
-    private(set) lazy var channelListObserver: BackgroundListDatabaseObserver<ChatChannel, ChannelDTO> = {
-        let request = ChannelDTO.channelListFetchRequest(query: self.query, chatClientConfig: client.config)
-        let observer = self.environment.createChannelListDatabaseObserver(
+    private(set) lazy var channelListObserver: BackgroundListDatabaseObserver<ChatChannel, ChannelDTO> = makeChannelListObserver(
+        query: query,
+        minimumFetchLimit: 0
+    )
+
+    private func makeChannelListObserver(
+        query: ChannelListQuery,
+        minimumFetchLimit: Int
+    ) -> BackgroundListDatabaseObserver<ChatChannel, ChannelDTO> {
+        let request = ChannelDTO.channelListFetchRequest(query: query, chatClientConfig: client.config)
+        let fetchLimit = max(query.pagination.pageSize, minimumFetchLimit)
+        request.fetchLimit = fetchLimit
+        request.fetchBatchSize = fetchLimit
+
+        let observer = environment.createChannelListDatabaseObserver(
             client.databaseContainer,
             request,
             { try $0.asModel() },
             query.runtimeSortingValues
         )
-
         observer.onDidChange = { [weak self] changes in
             self?.delegateCallback { [weak self] in
                 guard let self = self else {
@@ -101,7 +131,7 @@
             }
         }
         return observer
-    }()
+    }
 
     var _basePublishers: Any?
     /// An internal backing object for all publicly available Combine publishers. We use it to simplify the way we expose
@@ -117,10 +147,13 @@
 
     private let filter: (@Sendable (ChatChannel) -> Bool)?
     private let environment: Environment
-    private lazy var channelListLinker: ChannelListLinker = self.environment
-        .channelListLinkerBuilder(
+    private lazy var channelListLinker: ChannelListLinker = makeChannelListLinker(query: query)
+
+    private func makeChannelListLinker(query: ChannelListQuery) -> ChannelListLinker {
+        environment.channelListLinkerBuilder(
             query, filter, client.config, client.databaseContainer, worker, client.channelWatcherHandler
         )
+    }
 
     /// Creates a new `ChannelListController`.
     ///
@@ -146,12 +179,16 @@
         startChannelListObserverIfNeeded()
         channelListLinker.start(with: client.eventNotificationCenter)
         client.syncRepository.startTrackingChannelListController(self)
-        updateChannelList { [weak self] error in
-            guard let completion else { return }
-            self?.callback {
-                completion(error)
-            }
+
+        if query.groupKey != nil {
+            state = .remoteDataFetched
+            hasLoadedAllPreviousChannels = channels.isEmpty
+            markChannelsAsDeliveredIfNeeded(channels: Array(channels))
+            callback { completion?(nil) }
+            return
         }
+
+        updateChannelList(completion)
     }
 
     // MARK: - Actions
@@ -174,26 +211,60 @@
             return
         }
 
-        let limit = limit ?? query.pagination.pageSize
-        var updatedQuery = query
-        updatedQuery.pagination = Pagination(pageSize: limit, offset: channels.count)
-        worker.update(channelListQuery: updatedQuery) { result in
-            switch result {
-            case let .success(channels):
-                self.markChannelsAsDeliveredIfNeeded(channels: channels)
-                self.hasLoadedAllPreviousChannels = channels.count < limit
-                self.callback { completion?(nil) }
-            case let .failure(error):
-                self.callback { completion?(error) }
+        if let groupKey = query.groupKey {
+            worker.paginationCursor(for: groupKey) { result in
+                switch result {
+                case .failure(let error):
+                    self.callback { completion?(error) }
+                case .success(let cursor):
+                    guard let cursor else {
+                        self.hasLoadedAllPreviousChannels = true
+                        self.callback { completion?(nil) }
+                        return
+                    }
+                    self.worker.queryGroupedChannels(
+                        groupPagination: .init(groupKey: groupKey, next: cursor, prev: nil),
+                        limit: limit,
+                        watch: true,
+                        presence: true
+                    ) { queryResult in
+                        switch queryResult {
+                        case let .success(grouped):
+                            if let group = grouped.groups[groupKey] {
+                                self.hasLoadedAllPreviousChannels = group.next == nil
+                                self.markChannelsAsDeliveredIfNeeded(channels: group.channels)
+                            }
+                            self.callback { completion?(nil) }
+                        case let .failure(error):
+                            self.callback { completion?(error) }
+                        }
+                    }
+                }
+            }
+        } else {
+            let limit = limit ?? query.pagination.pageSize
+            var updatedQuery = query
+            updatedQuery.pagination = Pagination(
+                pageSize: limit,
+                offset: channels.count
+            )
+            worker.update(channelListQuery: updatedQuery) { result in
+                switch result {
+                case let .success(channels):
+                    self.markChannelsAsDeliveredIfNeeded(channels: channels)
+                    self.hasLoadedAllPreviousChannels = channels.count < limit
+                    self.callback { completion?(nil) }
+                case let .failure(error):
+                    self.callback { completion?(error) }
+                }
             }
         }
     }
 
     // MARK: - Internal
 
     func refreshLoadedChannels(completion: @escaping @Sendable (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