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): ChannelGroup

Input

* required

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

Output

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

Sample code

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

1val channelGroup = chat.getChannelGroup("my-channel-group")

Remove channel group

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

Method signature

This method takes the following parameters:

1chat.removeChannelGroup(id: String): PNFuture<Unit>

Input

* required

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

Output

Type	Description
PNFuture<Unit>	Returns an empty response when the channel group is successfully removed.

Sample code

Remove a channel group named my-channel-group.

1chat.removeChannelGroup("my-channel-group").async { result ->
2    result.onSuccess {
3        // Channel group removed successfully
4    }.onFailure {
5        // Handle failure
6    }
7}

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? = null,
3    sort: Collection<PNSortKey<PNKey>> = listOf(),
4    limit: Int? = null,
5    page: PNPage? = null
6): PNFuture<GetChannelsResponse>

Input

* required

Parameter	Description
filter Type: String Default: n/a	Expression used to filter the results. Returns only the channels whose properties satisfy the given expression. The filter language is defined here.
sort Type: Collection<PNSortKey<PNKey>> Default: listOf()	A collection to specify the sort order. Available options are id, name, and updated. Use asc or desc to specify the sorting direction. For example: listOf(PNSortKey.asc(PNKey.NAME)).
limit Type: Int Default: 100	Number of objects to return in response. The default (and maximum) value is 100.
page Type: PNPage Default: n/a	Object used for pagination to define which previous or next result page you want to fetch.

Output

Type	Description
PNFuture<GetChannelsResponse>	PNFuture containing a set of channels with pagination information (next, prev, total).

Sample code

List all channels in a channel group.

1val channelGroup = chat.getChannelGroup("my-channel-group")
2

3channelGroup.listChannels().async { result ->
4    result.onSuccess { response ->
5        response.channels.forEach { channel ->
6            println("Channel: ${channel.id}")
7        }
8    }.onFailure {
9        // Handle failure
10    }
11}

Add channels

Add Channel entities to a channel group with addChannels().

Method signature

This method takes the following parameters:

1channelGroup.addChannels(channels: Collection<Channel>): PNFuture<Unit>

Input

* required

Parameter	Description
channels * Type: Collection<Channel> Default: n/a	Collection of Channel entities to add to the group.

Output

Type	Description
PNFuture<Unit>	Returns an empty response when channels are successfully added.

Sample code

Add two channels to a channel group.

1val channelGroup = chat.getChannelGroup("my-channel-group")
2

3chat.getChannel("support-channel").async { result ->
4    result.onSuccess { supportChannel ->
5        chat.getChannel("general-channel").async { result2 ->
6            result2.onSuccess { generalChannel ->
7                if (supportChannel != null && generalChannel != null) {
8                    channelGroup.addChannels(listOf(supportChannel, generalChannel))
9                        .async { addResult ->
10                            addResult.onSuccess {
11                                // Channels added successfully
12                            }.onFailure {
13                                // Handle failure
14                            }
15                        }
16                }
17            }
18        }
19    }
20}

show all 20 lines

Add channel identifiers

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

No validation

This method doesn't validate whether channels with the given IDs exist. Make sure the channel IDs are valid before adding them.

Method signature

This method takes the following parameters:

1channelGroup.addChannelIdentifiers(ids: Collection<String>): PNFuture<Unit>

Input

* required

Parameter	Description
ids * Type: Collection<String> Default: n/a	Collection of channel IDs to add to the group.

Output

Type	Description
PNFuture<Unit>	Returns an empty response when channel identifiers are successfully added.

Sample code

Add channels by their IDs.

1val channelGroup = chat.getChannelGroup("my-channel-group")
2

3channelGroup.addChannelIdentifiers(listOf("support-channel", "general-channel")).async { result ->
4    result.onSuccess {
5        // Channel identifiers added successfully
6    }.onFailure {
7        // Handle failure
8    }
9}

Remove channels

Remove Channel entities from a channel group with removeChannels().

Method signature

This method takes the following parameters:

1channelGroup.removeChannels(channels: Collection<Channel>): PNFuture<Unit>

Input

* required

Parameter	Description
channels * Type: Collection<Channel> Default: n/a	Collection of Channel entities to remove from the group.

Output

Type	Description
PNFuture<Unit>	Returns an empty response when channels are successfully removed.

Sample code

Remove channels from a channel group.

1val channelGroup = chat.getChannelGroup("my-channel-group")
2

3// Assuming you have Channel references
4channelGroup.removeChannels(listOf(supportChannel, generalChannel)).async { result ->
5    result.onSuccess {
6        // Channels removed successfully
7    }.onFailure {
8        // Handle failure
9    }
10}

Remove channel identifiers

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

No validation

This method doesn't validate whether channels with the given IDs exist in the group. Make sure the channel IDs are valid before removing them.

Method signature

This method takes the following parameters:

1channelGroup.removeChannelIdentifiers(ids: Collection<String>): PNFuture<Unit>

Input

* required

Parameter	Description
ids * Type: Collection<String> Default: n/a	Collection of channel IDs to remove from the group.

Output

Type	Description
PNFuture<Unit>	Returns an empty response when channel identifiers are successfully removed.

Sample code

Remove channels by their IDs.

1val channelGroup = chat.getChannelGroup("my-channel-group")
2

3channelGroup.removeChannelIdentifiers(listOf("support-channel", "general-channel")).async { result ->
4    result.onSuccess {
5        // Channel identifiers removed successfully
6    }.onFailure {
7        // Handle failure
8    }
9}

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.

Deprecated method

connect() is deprecated. Use onMessageReceived() instead. Both methods have the same signature and behavior.

Method signature

This method takes the following parameters:

1channelGroup.onMessageReceived(callback: (Message) -> Unit): AutoCloseable

Input

* required

Parameter	Description
callback * Type: (Message) -> Unit Default: n/a	Callback function invoked whenever a message is received on any channel in the group.

Output

Type	Description
AutoCloseable	Interface you can call to stop listening for new messages by invoking the close() method.

Sample code

Start receiving messages from all channels in a group.

1val channelGroup = chat.getChannelGroup("my-channel-group")
2

3val subscription = channelGroup.onMessageReceived { message ->
4    println("Received message on channel ${message.channelId}: ${message.text}")
5}
6

7// Later, when you want to stop receiving messages
8subscription.close()

Get present users

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

Requires Presence

This method requires that Presence is enabled for your app's keyset in the Admin Portal.

Method signature

This method has the following signature:

1channelGroup.whoIsPresent(
2    limit: Int = 1000,
3    offset: Int? = null
4): PNFuture<Map<String, Collection<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: null	Zero-based starting index for pagination. Returns occupants starting from this position in the list. Must be >= 0.

Output

Type	Description
PNFuture<Map<String, Collection<String>>>	A map where each key is a channel ID and the value is a collection of user IDs present on that channel.

Sample code

Get all users present on channels in a group.

1val channelGroup = chat.getChannelGroup("my-channel-group")
2

3channelGroup.whoIsPresent().async { result ->
4    result.onSuccess { presenceByChannel ->
5        presenceByChannel.forEach { (channelId, userIds) ->
6            println("Channel $channelId has users: $userIds")
7        }
8    }.onFailure {
9        // Handle failure
10    }
11}

Stream presence

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

Deprecated method

streamPresence() is deprecated. Use onPresenceChanged() instead. Both methods have the same signature and behavior.

Requires Presence

This method requires that Presence is enabled for your app's keyset in the Admin Portal.

Method signature

This method takes the following parameters:

1channelGroup.onPresenceChanged(
2    callback: (presenceByChannels: Map<String, Collection<String>>) -> Unit
3): AutoCloseable

Input

* required

Parameter	Description
callback * Type: (Map<String, Collection<String>>) -> Unit Default: n/a	Callback function invoked when presence changes. Receives a map where each key is a channel ID and the value is a collection of user IDs present on that channel.

Output

Type	Description
AutoCloseable	Interface you can call to stop receiving presence updates by invoking the close() method.

Sample code

Stream presence updates for all channels in a group.

1val channelGroup = chat.getChannelGroup("my-channel-group")
2

3val subscription = channelGroup.onPresenceChanged { presenceByChannel ->
4    presenceByChannel.forEach { (channelId, userIds) ->
5        println("Channel $channelId now has users: $userIds")
6    }
7}
8

9// Later, when you want to stop receiving presence updates
10subscription.close()