Creating Channels

LAST EDIT May 12 2021

Both channel channel.query 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. Typically you use channel.watch client side and channel.create for a server side integration. Channels are unique either by the specified channel id or by the list of members.

1. Creating a Channel Using a Channel Id

Copied!

This is typically 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.

Note that for client side integrations you'll typically prefer to use channel.watch() instead of channel.create. Channel.watch both creates the channel and watches it at the same time.

2. Creating a Channel for a List of Members

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.

You can achieve this by leaving the channel ID empty and provide 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/remove 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 datastringExtra 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