Channel groups

Channel groups let you subscribe to multiple channels with a single subscription. Add channels to a group and receive messages from all of them at once.

Use channel groups to:

• Subscribe to all user channels with one call
• Monitor presence across multiple channels
• Manage subscriptions dynamically without reconnecting

Publishing to a channel group is not supported. Publish to each channel individually.

Requires Stream Controller

Enable Stream Controller for your key in the Admin Portal. See the support page for details.

Get channel group reference

Get a reference to a channel group with getChannelGroup(). This returns a handle to manage the group without creating it on the server.

If the group exists, the reference points to it. Otherwise, the handle creates the group when you add channels.

Method signature

This method takes the following parameters:

1chat.getChannelGroup(id: String) -> ChannelGroupImpl

Input

* required

Parameter	Description
id * Type: String Default: n/a	Unique identifier for the channel group.

Output

Type	Description
ChannelGroupImpl	A ChannelGroup object you can use to manage the group.

Sample code

Sample code

The code samples in Swift Chat SDK focus on asynchronous code execution.

You can also write synchronous code as the parameters are shared between the async and sync methods but we don't provide usage examples of such.

Get a reference to a channel group named my-channel-group.

1

Remove channel group

Delete a channel group from the server with removeChannelGroup().

Method signature

This method takes the following parameters:

1chat.removeChannelGroup(id: String) async throws

Input

* required

Parameter	Description
id * Type: String Default: n/a	Unique identifier of the channel group to remove.

Output

This method doesn't return any value.

Sample code

Remove a channel group named my-channel-group.

1

List channels

Get a paginated list of all channels in a channel group with listChannels().

Method signature

This method takes the following parameters:

1channelGroup.listChannels(
2    filter: String? = nil,
3    sort: [PubNub.ObjectSortField] = [],
4    limit: Int? = nil,
5    page: PubNubHashedPage? = nil
6) async throws -> (channels: [ChannelImpl], page: PubNubHashedPage?)

Input

* required

Parameter	Description
filter Type: String Default: nil	Expression used to filter the results. Returns only the channels whose properties satisfy the given expression. The filter language is defined here.
sort Type: [PubNub.ObjectSortField] Default: []	An array to specify the sort order. Available options are id, name, and updated. Use ascending or descending to specify the sorting direction.
limit Type: Int Default: nil	Number of objects to return in response. The maximum value is 100.
page Type: PubNubHashedPage Default: nil	Object used for pagination to define which previous or next result page you want to fetch.

Output

Type	Description
(channels: [ChannelImpl], page: PubNubHashedPage?)	A tuple containing a set of channels with pagination information.

Sample code

List all channels in a channel group.

1

Add channels

Add Channel entities to a channel group with add(channels:).

Method signature

This method takes the following parameters:

1channelGroup.add(channels: [ChannelImpl]) async throws

Input

* required

Parameter	Description
channels * Type: [ChannelImpl] Default: n/a	Array of Channel entities to add to the group.

Output

This method doesn't return any value.

Sample code

Add two channels to a channel group.

1

Add channel identifiers

Add channels to a group by ID with addChannelIdentifiers(_:). This avoids fetching full Channel entities.

No validation

This method does not validate that the channel IDs exist.

Method signature

This method takes the following parameters:

1channelGroup.addChannelIdentifiers(_ ids: [String]) async throws

Input

* required

Parameter	Description
ids * Type: [String] Default: n/a	Array of channel IDs to add to the group.

Output

This method doesn't return any value.

Sample code

Add channels by their IDs.

1

Remove channels

Remove Channel entities from a channel group with remove(channels:).

Method signature

This method takes the following parameters:

1channelGroup.remove(channels: [ChannelImpl]) async throws

Input

* required

Parameter	Description
channels * Type: [ChannelImpl] Default: n/a	Array of Channel entities to remove from the group.

Output

This method doesn't return any value.

Sample code

Remove channels from a channel group.

1

Remove channel identifiers

Remove channels from a group by ID with removeChannelIdentifiers(_:).

No validation

This method does not validate that the channel IDs exist in the group.

Method signature

This method takes the following parameters:

1channelGroup.removeChannelIdentifiers(_ ids: [String]) async throws

Input

* required

Parameter	Description
ids * Type: [String] Default: n/a	Array of channel IDs to remove from the group.

Output

This method doesn't return any value.

Sample code

Remove channels by their IDs.

1

Watch channel group

Subscribe to all channels in the group and receive messages with onMessageReceived(). The callback fires whenever a message arrives on any channel in the group.

You can also use channelGroup.stream.messages() for an AsyncStream-based approach.

Deprecation

connect() is deprecated. Use onMessageReceived() (closure-based) or channelGroup.stream.messages() (AsyncStream-based) instead.

Method signature

1channelGroup.onMessageReceived(
2    callback: @escaping (MessageImpl) -> Void
3) -> AutoCloseable

Input

* required

Parameter	Description
callback * Type: (MessageImpl) -> Void Default: n/a	Closure called whenever a new message is published on any channel in the group.

Output

Type	Description
AutoCloseable	An object you must retain. When released or closed, the listener stops.

Sample code

Start receiving messages from all channels in a group.

AsyncStream

1

Closure

1

Get present users

Get a list of users currently present on any channel in the group with whoIsPresent().

Requires Presence

Enable Presence for your keyset in the Admin Portal.

Method signature

This method has the following signature:

1channelGroup.whoIsPresent(
2    limit: Int = 1000,
3    offset: Int? = 0
4) async throws -> [String: [String]]

Input

* required

Parameter	Description
limit Type: Int Default: 1000	Maximum number of occupants to return per channel. Valid range: 0-1000. Use 0 to get occupancy counts without user details.
offset Type: Int? Default: 0	Zero-based starting index for pagination. Returns occupants starting from this position in the list. Must be >= 0.

Output

Type	Description
[String: [String]]	A dictionary where each key is a channel ID and the value is an array of user IDs present on that channel.

Sample code

Get all users present on channels in a group.

1

Stream presence

Receive real-time updates when users join or leave any channel in the group with onPresenceChanged().

You can also use channelGroup.stream.presenceChanges() for an AsyncStream-based approach.

Requires Presence

Enable Presence for your keyset in the Admin Portal.

Deprecation

streamPresence() is deprecated. Use onPresenceChanged() (closure-based) or channelGroup.stream.presenceChanges() (AsyncStream-based) instead.

Method signature

1channelGroup.onPresenceChanged(
2    callback: @escaping ([String: [String]]) -> Void
3) -> AutoCloseable

Input

* required

Parameter	Description
callback * Type: ([String: [String]]) -> Void Default: n/a	Closure called with a dictionary of channel IDs to present user ID arrays whenever presence changes.

Output

Type	Description
AutoCloseable	An object you must retain. When released or closed, the listener stops.

Sample code

Stream presence updates for all channels in a group.

AsyncStream

1

Closure

1