---
source_url: https://www.pubnub.com/docs/chat/chat-sdk/build/features/channels/channel-groups
title: Channel groups
updated_at: 2026-06-12T11:22:28.274Z
---

> 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

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.

:::note Requires Stream Controller
Enable *Stream Controller* for your key in the [Admin Portal](https://admin.pubnub.com/). See the [support page](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) 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:

```ts
chat.getChannelGroup(id: string): ChannelGroup
```

#### Input

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| id | string | Yes |  | Unique identifier for the channel group. |

#### Output

| Type | Description |
| --- | --- |
| `ChannelGroup` | A [ChannelGroup](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/channel-group) object you can use to manage the group. |

### Sample code

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

```ts
const 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:

```ts
chat.removeChannelGroup(id: string): Promise<any>
```

#### Input

| Parameter | Description |
| --- | --- |
| `id` *Type: `string`Default: n/a | Unique identifier of the channel group to remove. |

#### Output

| Type | Description |
| --- | --- |
| `Promise<any>` | Returns a response when the channel group is successfully removed. |

### Sample code

Remove a channel group named `my-channel-group`.

```ts
await chat.removeChannelGroup("my-channel-group")
```

## List channels

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

### Method signature

This method takes the following parameters:

```ts
channelGroup.listChannels({
    filter?: string,
    sort?: object,
    limit?: number,
    page?: {
        next?: string,
        prev?: string
    }
}): Promise<{
    channels: Channel[],
    page: {
        next: string,
        prev: string
    },
    total: number
}>
```

#### Input

| 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](https://www.pubnub.com/docs/general/metadata/filtering). |
| `sort`Type: `object`Default: n/a | An object to specify the sort order. Available options are `id`, `name`, and `updated`. Use `asc` or `desc` to specify the sorting direction. For example: `{ name: "asc" }`. |
| `limit`Type: `number`Default: `100` | Number of objects to return in response. The default (and maximum) value is `100`. |
| `page`Type: `object`Default: n/a | Object used for pagination to define which previous or next result page you want to fetch. |

#### Output

| Type | Description |
| --- | --- |
| `Promise<{ channels, page, total }>` | Promise containing a set of channels with pagination information (`next`, `prev`, `total`). |

### Sample code

List all channels in a channel group.

```ts
const channelGroup = chat.getChannelGroup("my-channel-group")

const { channels, page, total } = await channelGroup.listChannels()

channels.forEach(channel => {
    console.log("Channel:", channel.id)
})
```

## Add channels

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

### Method signature

This method takes the following parameters:

```ts
channelGroup.addChannels(channels: Channel[]): Promise<any>
```

#### Input

| Parameter | Description |
| --- | --- |
| `channels` *Type: `Channel[]`Default: n/a | Array of [Channel](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/channel) entities to add to the group. |

#### Output

| Type | Description |
| --- | --- |
| `Promise<any>` | Returns a response when channels are successfully added. |

### Sample code

Add two channels to a channel group.

```ts
const channelGroup = chat.getChannelGroup("my-channel-group")

const supportChannel = await chat.getChannel("support-channel")
const generalChannel = await chat.getChannel("general-channel")

await channelGroup.addChannels([supportChannel, generalChannel])
```

## Add channel identifiers

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

:::note No validation
This method does not validate that the channel IDs exist.
:::

### Method signature

This method takes the following parameters:

```ts
channelGroup.addChannelIdentifiers(ids: string[]): Promise<any>
```

#### Input

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

#### Output

| Type | Description |
| --- | --- |
| `Promise<any>` | Returns a response when channel identifiers are successfully added. |

### Sample code

Add channels by their IDs.

```ts
const channelGroup = chat.getChannelGroup("my-channel-group")

await channelGroup.addChannelIdentifiers(["support-channel", "general-channel"])
```

## Remove channels

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

### Method signature

This method takes the following parameters:

```ts
channelGroup.removeChannels(channels: Channel[]): Promise<any>
```

#### Input

| Parameter | Description |
| --- | --- |
| `channels` *Type: `Channel[]`Default: n/a | Array of [Channel](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/channel) entities to remove from the group. |

#### Output

| Type | Description |
| --- | --- |
| `Promise<any>` | Returns a response when channels are successfully removed. |

### Sample code

Remove channels from a channel group.

```ts
const channelGroup = chat.getChannelGroup("my-channel-group")

// Assuming you have channel references
await channelGroup.removeChannels([supportChannel, generalChannel])
```

## Remove channel identifiers

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

:::note No validation
This method does not validate that the channel IDs exist in the group.
:::

### Method signature

This method takes the following parameters:

```ts
channelGroup.removeChannelIdentifiers(ids: string[]): Promise<any>
```

#### Input

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

#### Output

| Type | Description |
| --- | --- |
| `Promise<any>` | Returns a response when channel identifiers are successfully removed. |

### Sample code

Remove channels by their IDs.

```ts
const channelGroup = chat.getChannelGroup("my-channel-group")

await channelGroup.removeChannelIdentifiers(["support-channel", "general-channel"])
```

## 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.

:::warning Deprecated
`connect()` is deprecated. Use `onMessageReceived()` instead.
:::

### Method signature

This method takes the following parameters:

```ts
channelGroup.onMessageReceived(callback: (message: Message) => void): () => void
```

#### Input

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

#### Output

| Type | Description |
| --- | --- |
| `() => void` | Function you can call to stop listening for new messages. |

### Sample code

Start receiving messages from all channels in a group.

```ts
const channelGroup = chat.getChannelGroup("my-channel-group")

const stopListening = channelGroup.onMessageReceived((message) => {
    console.log(`Received message on channel ${message.channelId}: ${message.content.text}`)
})

// Later, when you want to stop receiving messages
stopListening()
```

## Get present users

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

:::note Requires Presence
Enable [Presence](https://youtu.be/i2yLIqmvFD0) for your keyset in the [Admin Portal](https://admin.pubnub.com/).
:::

### Method signature

This method has the following signature:

```ts
channelGroup.whoIsPresent(
    params?: {
        limit?: number,
        offset?: number
    }
): Promise<{ [channelId: string]: string[] }>
```

#### Input

| Parameter | Description |
| --- | --- |
| `params`Type: `object`Default: n/a | Object containing optional pagination parameters. |
| → `limit`Type: `number`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: `number`Default: n/a | Zero-based starting index for pagination. Returns occupants starting from this position in the list. Must be >= 0. |

#### Output

| Type | Description |
| --- | --- |
| `Promise<{ [channelId: string]: string[] }>` | A map 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.

```ts
const channelGroup = chat.getChannelGroup("my-channel-group")

const presenceByChannel = await channelGroup.whoIsPresent()

Object.entries(presenceByChannel).forEach(([channelId, userIds]) => {
    console.log(`Channel ${channelId} has users:`, userIds)
})
```

## Stream presence

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

:::warning Deprecated
`streamPresence()` is deprecated. Use `onPresenceChanged()` instead.
:::

:::note Requires Presence
Enable [Presence](https://youtu.be/i2yLIqmvFD0) for your keyset in the [Admin Portal](https://admin.pubnub.com/).
:::

### Method signature

This method takes the following parameters:

```ts
channelGroup.onPresenceChanged(
    callback: (presenceByChannels: { [channelId: string]: string[] }) => void
): () => void
```

#### Input

| Parameter | Description |
| --- | --- |
| `callback` *Type: `({ [channelId: string]: string[] }) => void`Default: n/a | Callback function invoked when presence changes. Receives a map where each key is a channel ID and the value is an array of user IDs present on that channel. |

#### Output

| Type | Description |
| --- | --- |
| `() => void` | Function you can call to stop receiving presence updates. |

### Sample code

Stream presence updates for all channels in a group.

```ts
const channelGroup = chat.getChannelGroup("my-channel-group")

const stopPresenceStream = channelGroup.onPresenceChanged((presenceByChannel) => {
    Object.entries(presenceByChannel).forEach(([channelId, userIds]) => {
        console.log(`Channel ${channelId} now has users:`, userIds)
    })
})

// Later, when you want to stop receiving presence updates
stopPresenceStream()
```