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.
Channel types
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.
Open channel
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.
Open channel types
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 60,000 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.
How dynamic partitioning works
Subchannel types
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.
User allocation
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
andmax_participants_per_subchannel
attributes have fixed values. To confirm their values, visit this page and contact us on Sendbird Dashboard.
User deallocation
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.
Subchannel view
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.
Operators in a global channel
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.
Channel configuration
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.
List of attributes
Property name | Type | Description |
---|---|---|
allocation_ratio | float | The ratio of the number of participants to |
deallocation_ratio | float | The ratio of the number of participants to a value of |
stickiness_duration_to_subchannel | int | The set time period, in seconds, which allows a participant who has left a subchannel to return to the same subchannel. If a participant returns to the open channel within the |
max_recent_messages_count | int | The number of recent messages to be kept in each subchannel. Subchannel messages are stored only for the set time period of |
subchannel_messages_lifetime | int | The set time period, in days, for messages to be stored. Because all messages in a subchannel can be kept in the channel for the duration set by this property, a participant can retrieve previous messages in the subchannel within this time window. Whenever a new message is sent within the |
subchannel_min_lifetime | int | The set time period that a subchannel exists after it has reached a value of |
Group channel
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.
Group channel types
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 isfalse
. -
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 totrue
, thedistinct
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.
Supergroup channel's limitations
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.
-
Open channel vs. Group channel vs. Supergroup channel
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.
Use cases
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.
Type | Used for |
---|---|
Open channel | - Short-lived live events, such as concerts and live streams. |
Group channel | - Private 1-on-1 conversations, such as clinical consultations and Instagram-style Direct Messages. |
Supergroup channel | - Ask-me-anything type events with a large number of users. |
Channel types
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.
Open channel | Group channel | Supergroup channel | |
---|---|---|---|
Maximum number in a channel | Up to millions of participants | 100 members | Up to tens of thousands of members |
Accessible by | Anyone within the application | Invited users only if private or anyone if public | Invited users only if private or anyone if public |
Ephemeral messaging | |||
Online presence | Supported | Supported | Supported |
Last message | N/A | ||
UIKit | Supported | Supported | Supported |
Ban users | |||
Mute users | |||
Freeze channels | |||
N/A | N/A | ||
Read receipts | N/A | N/A | |
Unread counts | N/A | Supported | |
Typing indicators | N/A | Supported | Supported |
Mention others in message | Supported | Supported | Supported |
Mention counts | N/A | Supported | Supported |
Reactions | N/A | ||
Polls | Supported | N/A | |
Spam flood protection | Supported | Supported | Supported |
Supported | Supported | Supported | |
Smart throttling | Supported (Default: | Supported (Default: | Supported (Default: |
Push notifications | N/A | Supported | Supported |
Get a channel with its participant list or member list | N/A | Supported | Supported |
Pagination for participant list or member list | |||
Order of channel list | - Chronological | - Chronological | - Chronological |
Manage channel information
With metadata and metacounter which consist of key-value items, you can store additional information about your channels.
Information types
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.
data | metadata | sorted_metaarray | metacounter | |
---|---|---|---|---|
Belongs to | message resource | channel but not included in channel resource. | ||
Type | string | nested object | nested object | object |
Value | A long text of any types of characters. | A collection of key-value pairs. | A collection of key-value pairs. A unique key can have an array of values. | A collection of key-value pairs. The value must be an integer. |
Maximum length | 4 GB | - key: 128 bytes | - key: 80 bytes | - key: 128 bytes |
Application | A container for long, customized data. | Suitable for classification and filtering. | Suitable for classification and filtering. | A channel metacounter is primarily used to track and update discrete indicators in a channel. |
The following code shows how the data
, metadata
, and sorted_metaarray
properties can be used for a user, channel, and message objects.
Resource representation
The following tables show the list of properties in open and group channel resources.
List of properties for open channels
Property name | Type | Description |
---|---|---|
name | string | The channel topic or the name of the channel. |
channel_url | string | The unique URL of the channel. |
cover_url | string | The URL of the cover image. |
custom_type | string | A custom channel type which is used for channel grouping. |
data | string | A |
is_ephemeral | boolean | Indicates whether to preserve the messages in the channel for the purpose of retrieving chat history. |
participant_count | int | The current number of participants in the channel. Once the number exceeds 500, this count is sent according to the following two rules. |
max_length_message | int | The maximum length of a message allowed to be sent within the channel. This is the same as a value of the |
created_at | long | The timestamp of when the channel was created, in Unix seconds format. |
operators[] | array of objects | The array of users registered as operators of the channel. Operators can delete any messages in the channel, and can also receive all messages that have been throttled. |
freeze | boolean | Indicates whether the channel is currently frozen. The value of |
is_dynamic_partitioned | boolean | Indicates whether the channel is a dynamic partitioning open channel. If set to |
List of properties for group channels
Property name | Type | Description |
---|---|---|
name | string | The name of the channel or the channel topic. |
channel_url | string | The unique URL of the channel. |
cover_url | string | The URL of the cover image. |
custom_type | string | A custom channel type which is used for channel grouping. |
data | string | A |
is_distinct | boolean | Indicates whether an existing channel is reused or a new channel has been created with a combination of the channel members as well as the custom channel type if specified. |
is_public | boolean | Indicates whether to allow a user to join the channel without an invitation. |
is_super | boolean | Indicates whether the channel is a group channel or a Supergroup channel. |
is_ephemeral | boolean | Indicates whether to preserve the messages in the channel for the purpose of retrieving chat history. |
is_access_code_required | boolean | Indicates whether to set an access code to the channel and require an access code to a user who attempts to join the channel. |
member_count | int | The number of all members who have joined the channel and who have been invited but not joined. |
joined_member_count | int | The number of members who have joined the channel only. |
members | array of strings | An array of users who are members of the group channel. |
operators | array of strings | An array of users registered as operators of the channel. The operators can ban, mute, or delete messages in the channel that they join as an operator. |
delivery_receipt | nested object | The timestamp of when the user has last received the messages in the channel, in Unix milliseconds. Each key-value pair has a key with the unique ID of a user and a values with the user's timestamp. |
read_receipt | nested object | The timestamps of when the user has last read the messages in the channel, in Unix milliseconds. Each key-value pair has a key with the unique ID of a user and a value with the user’s timestamp. |
max_length_message | int | The maximum length of a message allowed to be sent within the channel. This is the same as a value of the |
unread_message_count | int | The number of messages a specific user hasn't read in the channel. If not specified, the value of |
unread_mention_count | int | The number of messages in the channel a specific user is mentioned in but hasn't read. If a user isn't specified in the request, the value returns |
last_message | object | The latest message sent to the channel. |
created_by | object | Information about the user who has created the channel and invited other users as members to the channel. This consists of the |
created_at | long | The timestamp of when the channel was created, in Unix seconds format. |
freeze | boolean | Indicates whether the channel is currently frozen. The value of |
| nested object | (Deprecated) An object that exists only for backward compatibility. |
Actions
- API endpoints are relative to the base URL allocated to the application. For example, the
/open_channels
endpoint refers tohttps://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}
.
List of actions for managing open channels
Action | HTTP request |
---|---|
| |
| |
| |
| |
| |
|
List of actions for managing group channels
Action | HTTP request |
---|---|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
|
List of actions for setting up channels
Action | HTTP request |
---|---|
| |
| |
| |
| |
| |
| |
|
List of actions for channel metacounter
Action | HTTP Request |
---|---|
| |
| |
| |
|
List of actions for channel metadata
Action | HTTP Request |
---|---|
| |
| |
| |
|
List of actions for managing typing indicators
Action | HTTP request |
---|---|
| |
|