Overview

Channel refers to a space in Sendbird Chat where users can communicate with one another through messages. With the Chat API, you can create and manage channels and channel information.

Sendbird Chat provides two different types of channels: open channel and group channel. Each type is designed to address a wide variety of business needs.

An open channel is a public chat that can handle millions of online users. No invitation is required to enter an open channel and participate in the conversation.

The following are the different types of open channels.

• Ephemeral: Messages in an ephemeral open channel aren't saved in Sendbird's database. This means that old messages pushed out by new ones can't be retrieved as they are one-time data. On the other hand, messages in a persistent open channel, which is the default open channel type, are permanently stored in the database.

• Dynamic partitioning: Dynamic partitioning open channels are designed to use a set number of subchannels to accommodate an even larger number of users, starting from 2,000 to 20,000 participants for shared regions and up to millions of participants for dedicated regions. This structure of dynamic partitioning enables flexible scaling of open channels by creating or merging subchannels within the open channels and evenly allocating participants among the subchannels to provide a seamless and well-paced chat experience to all users.

• Classic: A single classic open channel can accommodate up to 1,000 simultaneous users in a Twitch-style public chat.

Note: Sendbird applications created before December 15, 2020, are using classic open channels.

To view the image in full screen, click on the

Subchannels are mini channels that are created within an open channel. Dynamic partitioning offers two types of subchannels, which include Single and Multiple. The Single subchannel type is allowed to have only one subchannel while the Multiple subchannel type can create several subchannels depending on the number of participants joining the open channel. Each subchannel can accommodate an equal share of participants and whenever one subchannel reaches the allocation_ratio, another subchannel is created. If your open channel can accommodate 20,000 participants and is able to create 10 subchannels, which is the default value, then each subchannel can host a group of 2,000 participants.

Note: You can select the subchannel type on Sendbird Dashboard.

A dynamic partitioning open channel can scale up and down by automatically creating subchannels based on the number of participants joining the open channel. When an open channel is created, a subchannel is created as well. When a user joins the open channel, the Sendbird server allocates this user to the first subchannel. Subsequent users who join the open channel will continue to be allocated to this subchannel until the number of participants of this subchannel reaches the allocation_ratio, which refers to the rate of participants in a single subchannel that can prompt the creation of a new subchannel. This process is repeated until the total number of participants in the open channel reaches a value of the max_total_participants property.

When all the existing subchannels hit a value of the allocation_ratio property, the Sendbird server allocates incoming users in a round-robin fashion. This means that newcomers who join the open channel after all the subchannels have reached a value of the allocation_ratio property are allocated individually to each subchannel one at a time, rather than to a single subchannel altogether. The round-robin allocation continues until all subchannels reach their full capacity set by the max_participants_per_subchannel property.

If some subchannels fall below a value of the allocation_ratio property, the Sendbird server allocates a newly joined user to the subchannel that has the smallest number of participants at the time this user enters the open channel.

Note: The max_total_participants and max_participants_per_subchannel attributes have fixed values. To confirm their values, visit this page and contact us on Sendbird Dashboard.

Subchannels have a lifetime. The subchannel_min_lifetime indicates how long a subchannel can last when its participant count is below a certain level. This time limit is used for user deallocation. When the ratio of participants in a subchannel to a value of max_participants_per_subchannel falls below a value of deallocation_ratio and remains so for the time set in subchannel_min_lifetime, the corresponding subchannel is merged to another subchannel that has the fewest participants at the time. When a subchannel is merged, a value of max_participants_per_subchannel is ignored.

As for a dynamic partitioning open channel, participants in one subchannel can't interact with those in other subchannels. However, they all share the same channel theme and live streaming content, which makes all subchannels seemingly identical. For example, participants in Subchannel #1 can’t see the conversation taking place in Subchannel #2. However, the participants in both subchannels are still in the same chat environment with the identical channel UI and content broadcasted to all subchannels. Given its features, a dynamic-partitioned open channel works best for occasions that demand a full-scale chat, such as a gaming community and a live streaming event.

A global subchannel is a special subchannel for channel operators that allows them to receive every single message from all subchannels. Whereas participants in a subchannel can read only the messages exchanged within the subchannel, operators can read all the messages created in every subchannel. In addition, operators in a global channel aren't counted towards the max_total_participants and max_participants_per_subchannel properties.

Note: To send an admin message from operators to all subchannels, on Sendbird Dashboard, go to Settings > Channels and set Subchannel type to Multiple.

The following table lists the attributes that can be configured for dynamic partitioning open channels.

Note: To adjust the value of these attributes, visit this page and contact us on the Sendbird Dashboard.

A group channel is a channel that allows close interactions among up to 100 members. To join a group channel, an invitation from a channel member is required by default. Depending on the channel invitation preference, a user who is invited to a group channel can accept or decline the invitation. You can leverage various properties to design different types of group channels that best fit your use cases, such as Twitter-style 1-on-1 direct messaging, WhatsApp-style group chat, and more.

The following are the different types of group channel:

• Public vs. Private: A public group channel can be joined by any user without an invitation. Up to 100 users can join a single public group channel. On the other hand, a private group channel only accepts invited users by default.

• Distinct: The distinct option determines whether to resume the conversation in an existing channel or create a new channel when someone attempts to create a new channel with the same group of members. If such a group channel already exists, the attempt will retrieve the existing channel including the previous chat history. This is similar to Twitter-style 1-on-1 direct messaging. The default value is false.

• Supergroup: A Supergroup channel is an expanded version of a group channel that can accommodate a large number of members in a single channel and serves most of the functions of a group channel. The maximum number of channel members can stretch up to tens of thousands depending on your Sendbird plan. Because a Supergroup channel is built upon the same foundation as a group channel, Platform APIs and SDK functions for both channel types are identical. The super option determines whether a newly created channel is a Supergroup channel or a group channel. When this option is set to true, the distinct option is no longer available.

• Ephemeral: Messages in an ephemeral group channel are not saved on Sendbird's database. This means that old messages pushed out by new ones can't be retrieved as they are one-time data. On the other hand, messages in a persistent group channel are permanently stored in the database, which is the default.

To secure stable operation and optimized user experience in a Supergroup channel, a number of functions are subject to limitations. Some of these limitations include:

• Visual interactions: read and delivery receipts aren’t supported in Supergroup channels to ensure optimal performance in Supergroup channels.

• Unread counts: unread counts are marked up to 100 only. In case they surpass 100, we suggest you display the counts as 99+ to avoid any confusion.

• Push notifications: The way push notifications for Supergroup channels work is determined by two factors: the number of members in a channel and the online status of its members.

  • When there are less than 100 members: A push notification will be sent for every message created in the channel.

  • When there are 100 or more members: A ten-minute time window will be applied to Supergroup channels with 100 or more members. Once the number of members exceeds 100 and a new message is created, a push notification is sent for the new message and then the next push notification arrives ten minutes after that.
    For example, if the number of members in Channel A surpasses 100 at 13:00 and then a new message is sent at 13:01, a push notification will be sent for the message sent at 13:01 and the ten-minute time window begins. During this ten-minute time window, there will be no push notifications for any messages created within the time frame. When time is up and another message is sent at 13:11, the second push notification will be sent for that message.

  • When a user becomes active: If one of the Supergroup channel members enters the channel and reads a message, the user will be recognized as active. Then only for the following one minute, the user will be receiving push notifications for all messages sent within the time frame.

The optimal use cases for each channel type can vary because different channels support different features. The following tables compare open channels, group channels, and Supergroup channels in terms of possible use cases and supported features.

Choose which channel type to use based on key factors such as the duration of the chat and the number of users participating in it. The following table lists possible use cases for each channel type.

The following table lists the differences among the three types of channels. If you wish to adjust the maximum number of a channel depending on use cases, contact our sales team.

With metadata and metacounter which consist of key-value items, you can store additional information about your channels.

The following table compares the different options for storing additional information about a user, channel or message. User, channel, and message objects can contain extra data in the form of data, metadata, and sorted_metaarray. You can also use channel metacounter for storing numeric data about a channel.

The following code shows how the data, metadata, and sorted_metaarray properties can be used for a user, channel, and message objects.

{
    "channels": [
        {
            "is_distinct": true,
            "is_public": false,
            "is_super": false,
            "is_ephemeral": false,
            "name": "On the upcoming AWS event",
            "channel_url": "sendbird_group_channel_25108471_a1bc35f5f0d237207bc1rd343562c878fc2fd426",
            "cover_url": "https://sendbird.com/main/img/cover/cover_43.jpg",
            "data": "{u'background_color': u'yellow', u'description': u'preparing presentation'}", # "data" contains a long string of extra data added to the channel.
            "member_count": 3,
            "members": [
                {
                    "user_id": "Jay",
                    "nickname": "Rooster",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_13_512px.png",
                    "is_active": true,
                    "is_online": false,
                    "last_seen_at": 1542762346134,
                    "state": "joined",
                    "role": "",
                    "metadata": {
                        "font_preference": "times new roman",
                        "font_color": "black"
                    }
                },
                ... # More members
            ],
            ...
        },
        ... # More channels
    ]

}

The following tables show the list of properties in open and group channel resources.

• API endpoints are relative to the base URL allocated to the application. For example, the /open_channels endpoint refers to https://api-{application_id}.sendbird.com/v3/open_channels.

Note: If you want to know the ID and base URL of your application, sign in to your dashboard, go to Settings > Application > General, and then check the Application ID and API request URL.

• It's recommended that the parameter values in API URLs be urlencoded, such as {user_id} and {channel_url}.