---
source_url: https://www.pubnub.com/docs/sdks/kotlin/api-reference/channel-groups
title: Channel Groups API for Kotlin SDK
updated_at: 2026-06-19T11:37:42.454Z
sdk_name: PubNub Kotlin SDK
sdk_version: 13.4.0
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Channel Groups API for Kotlin SDK

PubNub Kotlin SDK, use the latest version: 13.4.0

Install:

```bash
Add PubNub dependency to your build@13.4.0
```

:::warning Breaking changes in v9.0.0
PubNub Kotlin SDK version 9.0.0 unifies the codebases for Kotlin and [Java](https://www.pubnub.com/docs/sdks/java) SDKs, introduces a new way of instantiating the PubNub client, and changes asynchronous API callbacks and emitted [status events](https://www.pubnub.com/docs/sdks/kotlin/status-events). These changes can impact applications built with previous versions (< `9.0.0` ) of the Kotlin SDK.
For more details about what has changed, refer to [Java/Kotlin SDK migration guide](https://www.pubnub.com/docs/sdks/kotlin/migration-guides/kotlin-v9-migration-guide).
:::

[Channel groups](https://www.pubnub.com/docs/general/channels/subscribe#channel-groups) allow PubNub developers to bundle thousands of [channels](https://www.pubnub.com/docs/general/channels/overview) into a group that can be identified by a name. These channel groups can then be subscribed to, receiving data from the many back-end channels the channel group contains.

:::note Channel group operations
You can't publish to a channel group. You can only subscribe to it. To publish within the channel group, you need to publish to each channel individually.
:::

:::tip Request execution
Most PubNub Kotlin SDK method invocations return an Endpoint object, which allows you to decide whether to perform the operation synchronously or asynchronously.
You must invoke the `.sync()` or `.async()` method on the Endpoint to execute the request, or the operation **will not** be performed.
```kotlin
val channel = pubnub.channel("channelName")
channel.publish("This SDK rules!").async { result ->
    result.onFailure { exception ->
        // Handle error
    }.onSuccess { value ->
        // Handle successful method result
    }
}
```
:::

## Add channels to a channel group

:::note Requires Stream Controller add-on
This method requires that the *Stream Controller* add-on is enabled for your key in the PubNub [Admin Portal](https://admin.pubnub.com/). Read the [support page](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) on enabling add-on features on your keys.
:::

This function adds channels to a channel group.

### Method(s)

Use the following method in the Kotlin SDK:

:::note Maximum number of channels
You can add up to 200 channels to a channel group per API call.
:::

```kotlin
pubnub.addChannelsToChannelGroup(
    channelGroup: String,
    channels: List<String>
).async { result -> }
```

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| channelGroup | String | Yes |  | The channel group to add the channels to. |
| channels | List<String> | Yes |  | The channels to add to the channel group. |

### Sample code

:::tip Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
:::

```kotlin
import com.pubnub.api.PubNub
import com.pubnub.api.UserId

fun main() {
    // Configure PubNub with demo keys
    val config = com.pubnub.api.v2.PNConfiguration.builder(UserId("add-channels-demo"), "demo").apply {
        publishKey = "demo"
    }

    val pubnub = PubNub.create(config.build())

    // Set up channel names and channel group name
    val channelA = "demo-channel-a"
    val channelB = "demo-channel-b"
    val channelC = "demo-channel-c"
    val myChannelGroup = "demo-channel-group"

    // Add channels to a channel group
    println("Adding channels to channel group '$myChannelGroup'...")

    // The addChannelsToChannelGroup method adds channels to an existing or new channel group
    pubnub.addChannelsToChannelGroup(
        // The name of the channel group to add channels to
        channelGroup = myChannelGroup,
        // A list of channel names to add to the channel group
        channels = listOf(channelA, channelB, channelC)
    ).async { result ->
        result.onFailure { exception ->
            println("Failed to add channels to channel group: ${exception.message}")
            exception.printStackTrace()
        }.onSuccess {
            println("Successfully added channels to channel group '$myChannelGroup'")

            // Verify by listing the channels in the group
            pubnub.listChannelsForChannelGroup(channelGroup = myChannelGroup).async { listResult ->
                listResult.onFailure { listException ->
                    println("Failed to list channels: ${listException.message}")
                }.onSuccess { response ->
                    println("Channels in group '$myChannelGroup': ${response.channels.joinToString(", ")}")

                    // Clean up
                    cleanup(pubnub, myChannelGroup)
                }
            }
        }
    }

    // Keep the program running until the operations complete
    Thread.sleep(5000)
}

/**
 * Optional cleanup to remove the channel group after demonstration
 */
fun cleanup(pubnub: PubNub, channelGroup: String) {
    println("Cleaning up - Deleting channel group '$channelGroup'")
    pubnub.deleteChannelGroup(channelGroup = channelGroup).async { result ->
        result.onFailure { exception ->
            println("Failed to delete channel group: ${exception.message}")
        }.onSuccess {
            println("Successfully deleted channel group '$channelGroup'")
            pubnub.destroy()
        }
    }
}
```

### Response

The `addChannelsToChannelGroup()` doesn't return actionable data, be sure to check result object on the outcome of the operation by checking the `result.isFailure` or handling exception `result.onFailure(exception -> { })`.

## List channels in a channel group

:::note Requires Stream Controller add-on
This method requires that the *Stream Controller* add-on is enabled for your key in the [Admin Portal](https://admin.pubnub.com/). Read the [support page](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) on enabling add-on features on your keys.
:::

This function lists all channels in a channel group.

### Method(s)

Use the following method in the Kotlin SDK:

```kotlin
pubnub.listChannelsForChannelGroup(
    channelGroup: String
).async { result -> }
```

| Parameter | Description |
| --- | --- |
| `channelGroup` *Type: `String` | The channel group for which to list channels. |

### Sample code

```kotlin
pubNub.listChannelsForChannelGroup(
    channelGroup = "cg1"
).async { result ->
    result.onFailure { exception ->
        // Handle error
    }.onSuccess { value ->
        // Handle successful method result
    }
}
```

### Returns

The `listChannelsForChannelGroup()` operation returns a `PNChannelGroupsAllChannelsResult` which contains the following operations:

| Method | Description |
| --- | --- |
| `channels`Type: `List<String>` | List of `channels` of a `channel group`. |

## Remove channels from a channel group

:::note Requires Stream Controller add-on
This method requires that the *Stream Controller* add-on is enabled for your key in the [Admin Portal](https://admin.pubnub.com/). Read the [support page](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) on enabling add-on features on your keys.
:::

This function removes channels from a channel group.

### Method(s)

Use the following method in the Kotlin SDK:

```kotlin
pubnub.removeChannelsFromChannelGroup(
    channels: List<String>,
    channelGroup: String
).async { result -> }
```

| Parameter | Description |
| --- | --- |
| `channels` *Type: `List<String>` | The channels to remove from the channel group. |
| `channelGroup` *Type: `String` | The channel group from which to remove channels. |

### Sample code

```kotlin
pubNub.removeChannelsFromChannelGroup(
    channels = listOf("ch1", "ch2"),
    channelGroup = "cg1"
).async { result -> }
```

### Returns

The `removeChannelsFromChannelGroup()` doesn't return actionable data, be sure to check result object on the outcome of the operation by checking the `result.isFailure` or handling exception `result.onFailure(exception -> { })`.

## Delete a channel group

:::note Requires Stream Controller add-on
This method requires that the *Stream Controller* add-on is enabled for your key in the [Admin Portal](https://admin.pubnub.com/). Read the [support page](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) on enabling add-on features on your keys.
:::

This function deletes a channel group.

### Method(s)

Use the following method in the Kotlin SDK:

```kotlin
pubnub.deleteChannelGroup(
    channelGroup: String
).async { result -> }
```

| Parameter | Description |
| --- | --- |
| `channelGroup` *Type: `String` | The channel group to delete. |

### Sample code

```kotlin
pubNub.deleteChannelGroup(
    channelGroup = "cg1"
).async { result -> }
```

### Returns

The `deleteChannelGroup()` doesn't return actionable data, be sure to check result object on the outcome of the operation by checking the `result.isFailure` or handling exception `result.onFailure(exception -> { })`.

## Terms in this document

* **Channel** - A pathway for sending and receiving messages between devices, created automatically when you first use it, that can handle any number of users and messages for different communication needs, like 1-1 text chats, group conversations, and other data streaming.
* **PubNub** - PubNub is a real-time messaging platform that provides APIs and SDKs for building scalable applications. It handles the complex infrastructure of real-time communication, including: Message delivery and persistence, Presence detection, Access control, Push notifications, File sharing, Serverless processing with Functions and Events & Actions, Analytics and monitoring with BizOps Workspace, AI-powered insights with Illuminate.