Creating Channels Backend

LAST EDIT Apr 18 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 livestreaming service like Twitch you have a channel for every streamer in your db.

1
2
3
4
5
await channel = client.channel('messaging', 'travel', { 
    name: 'Awesome channel about traveling', 
    created_by_id: 'myuserid' 
}); 
await channel.create();
1
conversation.create('jlahey')
Note how you specify created_by_id when creating a channel server side. Stream requires that every channel has a user id attached to it who created it. If you don't have this concept in your app it's best to create a user called "system" or similar.

2. Creating a Channel for a List of Members

Copied!

Channels can be used to conversations between users. In most cases, you want conversations to be unique and make sure that a group of users have only a 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.
1
2
3
4
5
const channel = client.channel('messaging', { 
    members: ['thierry', 'tommaso'], 
    created_by_id: 'myuserid' 
}); 
await channel.create();
1
2
$conversation = $client->Channel('messaging', 'thierry-jenny', ['members'=>['thierry', 'jenny']]); 
$state   = $conversation->create('thierry');
1
2
3
4
5
6
7
8
conversation = client.channel( 
    'messaging', 'thierry-tommaso-1',  
    data: { 
      'name'   => 'Founder Chat', 
      'image'  => 'http://bit.ly/2O35mws', 
      'members => ['thierry', 'tommaso'], 
    } 
)

Channel Initialization Parameters

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

created_by_id

string, user id

Required when making server side API calls. You need to specify which user is the owner of this channel.