GetStream · laevandus · Apr 13, 2026 · Apr 14, 2026 · Apr 15, 2026 · Apr 17, 2026
@@ -3,6 +3,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 # Upcoming
 
+## StreamChat
+### ✅ Added
+- Add `ChatClient.queryGroupedChannels(groups:limit:presence:watch:)` to fetch grouped channels with per-group unread counts [#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 `unreadChannelCountsByGroup` to `CurrentChatUser`, observable for changes via `ConnectedUser` [#4076](https://github.com/GetStream/stream-chat-swift/pull/4076)
 ### 🔄 Changed
 
 # [5.3.0](https://github.com/GetStream/stream-chat-swift/releases/tag/5.3.0)

@@ -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
+    }
+}
+
+final class GroupedQueryChannelsRequestGroup: Encodable, Sendable {
+    let limit: Int?
+    let next: String?
+
+    init(limit: Int?, next: String?) {
+        self.limit = limit
+        self.next = next
+    }
+}
+
+final class GroupedQueryChannelsPayload: Decodable, Sendable {
+    let groups: [String: GroupedQueryChannelsGroupPayload]
+
+    init(groups: [String: GroupedQueryChannelsGroupPayload]) {
+        self.groups = groups
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case groups
+    }
+
+    required init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        groups = try container.decode([String: GroupedQueryChannelsGroupPayload].self, forKey: .groups)
+    }
+}
+
+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,39 @@ public class ChatClient: @unchecked Sendable {
         }
     }
 
+    // MARK: - Grouped Channels
+
+    /// Fetches the first page of channels for the requested groups in a single request.
+    ///
+    /// To observe and paginate a group's channels, create a ``ChannelList`` for its
+    /// ``ChannelGroup/groupKey`` via ``ChatClient/makeChannelList(with:)-(String)`` and read
+    /// ``ChannelListState/channels``.
+    ///
+    /// - Parameters:
+    ///   - groups: The group keys to fetch.
+    ///   - limit: The number of channels to return per group. `nil` uses the backend default.
+    ///   - presence: When `true`, includes presence info and streams presence updates over the WebSocket.
+    ///   - watch: When `true`, subscribes to WebSocket events for the returned channels.
+    ///
+    /// - Returns: The fetched ``ChannelGroup`` values.
+    /// - Throws: An error while communicating with the Stream API.
+    @discardableResult public func queryGroupedChannels(
+        groups: [String],
+        limit: Int? = nil,
+        presence: Bool = false,
+        watch: Bool = true
+    ) async throws -> [ChannelGroup] {
+        let groupRequests: [String: GroupedQueryChannelsRequestGroup]? = groups.isEmpty ? nil : groups.reduce(into: [:]) { result, key in
+            result[key] = GroupedQueryChannelsRequestGroup(limit: limit, next: nil)
+        }
+        return try await channelListUpdater.queryGroupedChannels(
+            groups: groupRequests,
+            limit: groupRequests == nil ? limit : nil,
+            watch: watch,
+            presence: presence
+        )
+    }
+
     // MARK: - Upload attachments
 
     /// Uploads an attachment to the specified CDN.

@@ -281,7 +281,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 {
@@ -356,7 +358,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(
@@ -444,7 +446,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)
     }
@@ -477,7 +479,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] = [
@@ -497,8 +499,13 @@ extension ChannelDTO {
         }
 
         request.predicate = NSCompoundPredicate(type: .and, subpredicates: subpredicates)
-        request.fetchLimit = query.pagination.pageSize
-        request.fetchBatchSize = query.pagination.pageSize
+        request.fetchLimit = query.pagination.pageSize == .unsetPageSize ? 0 : query.pagination.pageSize
+        // For grouped queries `pageSize` is `.unsetPageSize`, which would disable batching.
+        // Fall back to the standard channels page size to keep memory bounded as the linked set
+        // grows across pagination.
+        request.fetchBatchSize = query.pagination.pageSize == .unsetPageSize
+            ? .channelsPageSize
+            : query.pagination.pageSize
         return request
     }
 

@@ -12,6 +12,38 @@ class ChannelListQueryDTO: NSManagedObject {
     /// Serialized `Filter` JSON which can be used in cases the query needs to be repeated, i.e. for newly created channels.
     @NSManaged var filterJSONData: Data
 
+    /// Next-page cursor returned by the grouped channels endpoint for this group.
+    /// `nil` means there is no next page (either never paginated or the backend
+    /// signaled exhaustion). Only meaningful for queries that carry a `groupKey`.
+    @NSManaged var next: String?
+
+    /// The `watch` flag that the original grouped-channels request was issued with.
+    ///
+    /// Persisted so that subsequent paginated fetches (via `ChannelList`) and the
+    /// `SyncRepository` refetch after reconnect can reuse the same value the caller
+    /// passed to `ChatClient.queryGroupedChannels(groups:limit:presence:watch:)` instead of
+    /// silently downgrading to `false`.
+    ///
+    /// When `watch` is `false`, ordinary channel and member WebSocket events
+    /// (`message.new`, `channel.updated`, etc.) still arrive for channels the current
+    /// user is a member of. What `watch == true` additionally enables is the
+    /// watcher-scoped event stream — most notably typing indicators
+    /// (`typing.start` / `typing.stop`) — so any UI that needs typing indicators
+    /// on a grouped channel must pass `watch: true` on the initial query.
+    ///
+    /// Only meaningful for queries that carry a `groupKey`; filter-based queries
+    /// derive watching from `ChannelListQuery.options`.
+    @NSManaged var watch: Bool
+
+    /// The `presence` flag that the original grouped-channels request was issued with.
+    ///
+    /// Persisted so that subsequent paginated fetches and sync refetches reuse the
+    /// same value, keeping presence info in responses and presence updates on the
+    /// WebSocket consistent across the lifetime of the group subscription.
+    ///
+    /// Only meaningful for queries that carry a `groupKey`.
+    @NSManaged var presence: Bool
+
     // MARK: - Relationships
 
     @NSManaged var channels: Set<ChannelDTO>
@@ -35,21 +67,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 {

@@ -7,6 +7,8 @@ import Foundation
 
 @objc(CurrentUserDTO)
 class CurrentUserDTO: NSManagedObject {
+    /// JSON-encoded `[groupKey: unreadCount]`.
+    @NSManaged var unreadGroupedChannelsCounts: Data?
     @NSManaged var unreadChannelsCount: Int64
     @NSManaged var unreadMessagesCount: Int64
     @NSManaged var unreadThreadsCount: Int64
@@ -144,6 +146,30 @@ extension NSManagedObjectContext: CurrentUserDatabaseSession {
         }
     }
 
+    /// Merges per-group unread channel counts into `CurrentUserDTO.unreadChannelCountsByGroup`.
+    /// Called from `queryGroupedChannels` responses and from WS events carrying
+    /// `grouped_unread_channels`; both paths use merge semantics, so keys absent from the input
+    /// are left untouched and a group that disappears from a server snapshot will keep its
+    /// locally-cached count until something explicitly clears it.
+    func mergeCurrentUserUnreadChannelCountsByGroup(_ unreadChannelCountsByGroup: [String: Int]) throws {
+        invalidateCurrentUserCache()
+
+        guard let dto = currentUser else {
+            throw ClientError.CurrentUserDoesNotExist()
+        }
+
+        dto.unreadChannelCountsByGroup = (dto.unreadChannelCountsByGroup ?? [:]).merging(unreadChannelCountsByGroup) { _, new in new }
+    }
+
+    func adjustUnreadChannelCount(forGroup groupKey: String, by delta: Int) {
+        invalidateCurrentUserCache()
+        guard let dto = currentUser, var counts = dto.unreadChannelCountsByGroup, let existing = counts[groupKey] else {
+            return
+        }
+        counts[groupKey] = max(0, existing + delta)
+        dto.unreadChannelCountsByGroup = counts
+    }
+
     func saveCurrentUserDevices(_ devices: [DevicePayload], clearExisting: Bool) throws -> [DeviceDTO] {
         invalidateCurrentUserCache()
 
@@ -212,6 +238,18 @@ extension NSManagedObjectContext: CurrentUserDatabaseSession {
     }
 }
 
+extension CurrentUserDTO {
+    var unreadChannelCountsByGroup: [String: Int]? {
+        get {
+            guard let unreadGroupedChannelsCounts else { return nil }
+            return try? JSONDecoder.default.decode([String: Int].self, from: unreadGroupedChannelsCounts)
+        }
+        set {
+            unreadGroupedChannelsCounts = newValue.flatMap { try? JSONEncoder.default.encode($0) }
+        }
+    }
+}
+
 extension CurrentUserDTO {
     override class func prefetchedRelationshipKeyPaths() -> [String] {
         [
@@ -282,6 +320,7 @@ extension CurrentChatUser {
                 messages: Int(dto.unreadMessagesCount),
                 threads: Int(dto.unreadThreadsCount)
             ),
+            unreadChannelCountsByGroup: dto.unreadChannelCountsByGroup,
             mutedChannels: mutedChannels,
             privacySettings: .init(
                 typingIndicators: .init(enabled: dto.isTypingIndicatorsEnabled),