Creating Channels

LAST EDIT Oct 07 2024

Both channel channel.create and channel.watch methods ensure that a channel exists and create one otherwise. If all you need is to ensure that a channel exists, you can use channel.create. This is allowed server-side and client-side, however, is more commonly used server-side. Client-side integrations favor channel.watch as it both creates and watches the channel in one call. See: Watching A Channel

Channels are unique either by specifying a channel ID or list of members in the create request.

1. Creating a Channel Using a Channel Id

Copied!

This is the best approach if you already have some sort of object in your database that the channel is associated with. As an example, if you're building a live-streaming service like Twitch you have a channel for every streamer in your database.

2. Creating a Channel for a List of Members - distinct channels

Copied!

Channels can be used to create conversations between users. In most cases, you want conversations to be unique and make sure that a group of users have only one channel. These are also referred to as 'distinct channels'.

You can achieve this by leaving the channel ID empty and providing channel type and members. When you do so, the API will ensure that only one channel for the members you specified exists (the order of the members does not matter).

You cannot add members for channels created this way.

Channel Data

Copied!

When you create a channel using one of the above approaches you'll specify the following fields:

nametypedescriptiondefaultoptional
typestringThe channel type. Default types are livestream, messaging, team, gaming and commerce. You can also create your own types.-
idstringThe channel id (optional). If you don't specify an ID the ID will be generated based on the list of members. (max length 64 characters)-
channel dataobjectExtra data for the channel. Must not exceed 5KB in size.default

The channel data can contain as many custom fields as you'd like as long as the total size is below 5KB. Note that you typically upload images to a CDN. So the 5KB limit only applies to the text data specified on the channel. Members is a reserved field, and our UI libraries use name and image to display the channels.

Name

Type

Description

name

string

The channel name. No special meaning, but by default the UI component will try to render this if the property is present.

image

string

The Channel image. Again there is no special meaning but by default, the UI component will try to render this if the property is present.

members

array

The members participating in this Channel. Note that you don't need to specify members for a live stream or other public chat. You only need to specify the members if you want to limit access of this chat to these members and subscribe them to future updates