Open channel

An open channel is a Twitch-style public chat where users can easily join without permission. Sendbird Chat SDK now supports two operation systems for open channels, which are classic and dynamic partitioning. These two systems offer the same features and functions, except that dynamic partitioning allows open channels to accommodate a massive number of users.

Classic open channels are the original open channels Sendbird has been providing, and a single classic open channel can handle up to 1,000 participants.

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

On the other hand, dynamic partitioning open channels are designed to accommodate an even larger number of users using a set number of subchannels, starting from 2,000 up to millions of participants. This new system, called dynamic partitioning, enables flexible scaling of open channels by creating or merging subchannels within the open channels and evenly allocating participants among the subchannels while providing a seamless and well-paced chat experience to all users.

Note: The classic open channels will be deprecated by the end of March 2021 but the classic channels created before the deprecation will remain and function the same way. Meanwhile, all Chat SDK users will be automatically migrated to the new dynamic partitioning system when the deprecation takes place. If you wish to convert to dynamic partitioning open channels beforehand, contact our support team.

Learn more about how dynamic partitioning open channel operates in the Open channel guide of Platform API.

An open channel is ideal for use cases that require a small and static number of channel. To create an open channel from the Sendbird Dashboard, do the following:

1. In your dashboard, go to the Chat > Open channels, and then click Create channel at the top-right corner.
2. In the dialog box that appears, specify the name, unique URL, cover image, and custom type of a channel.

You can also create a channel on demand or dynamically via the Chat SDK or the Platform API.

OpenChannel.CreateChannel(NAME, COVER_URL, DATA, (OpenChannel openChannel, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    // An open channel is successfully created.
    // Through the "openChannel" parameter of the callback function,
    // you can get the open channel's data from the result object that Sendbird server has passed to the callback function.
    string ChannelUrl = openChannel.Url;
    ...
});

You can also append information by passing additional parameters.

OpenChannel.CreateChannel(NAME, COVER_IMAGE_OR_URL, DATA, CUSTOM_TYPE, (OpenChannel openChannel, SendBirdException e) =>
{
    if(e != null)
    {
        // Handle error.
    }

    // An open channel with detailed configuration is successfully created.
    // By using openChannel.Url, openChannel.Data, openChannel.CustomType, and so on,
    // you can access the result object from Sendbird server to check your parameter configuration.
    string CustomType = openChannel.CustomType;
    ...
});

Note: By default, the Allow creating open channels option is turned on which means that open channels can be created by any user with Sendbird Chat SDK. This may grant access to unwanted data or operations, leading to potential security concerns. To manage your access control settings, you can turn on or off each option in Settings > Application > Security > Access control list on Sendbird Dashboard.

A user must enter an open channel to receive messages. The user can enter up to 10 open channels at once, which are valid only within a current connection. So if the disconnected user is reconnected to Sendbird server, the user must re-enter the channels to continue receiving messages.

When a user who is already a participant in an open channel moves the app to the background, the user will be disconnected from Sendbird server. But when the user's app returns to the foreground, the Chat SDK will automatically re-enter the user to the participating channel.

OpenChannel.GetChannel(CHANNEL_URL, (OpenChannel openChannel, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    // Call the instance method of the result object in the "openChannel" parameter of the callback function.
    openChannel.Enter((SendBirdException e) =>
    {
        if (e != null)
        {
            // Handle error.
        }

        // The current user successfully enters the open channel,
        // and can chat with other users in the channel by using APIs.
        ...
    });
});

To stop receiving messages from the open channel, you must exit the channel.

OpenChannel.GetChannel(CHANNEL_URL, (OpenChannel openChannel, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    openChannel.Exit((SendBirdException e) =>
    {
        if (e != null)
        {
            // Handle error.
        }

        // The current user successfully exits the open channel,
        ...
    });
});

You can obtain a list of all open channels by creating a OpenChannelListQuery. The Next() method returns a list of OpenChannel objects.

OpenChannelListQuery mListQuery = OpenChannel.CreateOpenChannelListQuery();

mListQuery.Next((List<OpenChannel> channels, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    // A list of open channels is successfully retrieved.
    // Through the "channels" parameter of the callback function,
    // you can access the data of each open channel from the result list that Sendbird server has passed to the callback function.
    foreach (OpenChannel channel in channels)
    {
        ...
    }

    ...
});

Since a channel URL is a unique identifier of an open channel, you can use a URL to retrieve a channel instance. It is important to remember that a user must enter the channel to send or receive messages within it.

OpenChannel.GetChannel(CHANNEL_URL, (OpenChannel openChannel, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    // Through the "openChannel" parameter of the callback function,
    // the open channel object identified with the CHANNEL_URL is returned by Sendbird server,
    // and you can get the open channel's data from the result object.
    string ChannelName = openChannel.Name;
    ...
});

Note: We recommend that you store channel URLs to handle their lifecycle or state changes in your app. For example, if a user disconnects from Sendbird server by temporarily switching to another app, you can provide a smooth restoration of the user's state using a stored URL to fetch the appropriate channel instance, then re-entering the user into the channel.

Upon entering an open channel, a user can send messages of the following types:

In addition to these message types, you can further subclassify a message by specifying its customType property. This custom type takes on the form of a String and can be used to search or filter messages. By assigning arbitrary string to the data property, you can also set custom font size, font type or JSON object. It allows you to append information to your message and customize message categorization.

Through the callback function of the SendUserMessage() method, Sendbird server always notifies whether your message has been successfully sent to the channel. When there is a delivery failure due to network issues, an exception is returned through the callback function.

openChannel.SendUserMessage(MESSAGE, DATA, (UserMessage userMessage, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    // A text message is successfully sent to the channel.
    // By using userMessage.MessageId, userMessage.Message, userMessage.CustomType, and so on,
    // you can access the result object from Sendbird server to check your configuration.
    // The current user can receive messages from other users through the OnMessageReceived() method of a channel handler.
    long messageId = userMessage.MessageId;
    ...
});

A user can also send binary files through the Chat SDK. The two ways to send a binary file are: sending the file itself, or sending a URL.

Sending a raw file means you're uploading it to Sendbird server where it can be downloaded in client apps. When you upload a file directly to the server, there is a size limit imposed on the file depending on your plan. You can see the limit in your dashboard and adjust it with our sales team.

The other option is to send a file hosted on your server. You can pass the file's URL, which represents its location, as an argument to a parameter. In this case, your file is not hosted on Sendbird server and it can only be downloaded from your own server. When you send a file message with a URL, there is no limit on the file size since it's not directly uploaded to Sendbird server.

// Sending a file message with a raw file
openChannel.SendFileMessage(FILE_PATH, FILE_NAME, FILE_TYPE, FILE_SIZE, DATA, CUSTOM_TYPE, (FileMessage fileMessage, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    // A file message is successfully sent to the channel.
    // By using fileMessage.MessageId, fileMessage.FileName, fileMessage.CustomType, and so on,
    // you can access the result object from Sendbird server to check your configuration.
    // The current user can receive messages from other users through the onMessageReceived() method of a channel handler.
    long messageId = fileMessage.MessageId;
    ...
});

// Sending a file message with a file URL
channel.SendFileMessageWithURL(FILE_URL, NAME, TYPE, SIZE, DATA, CUSTOM_TYPE, (FileMessage fileMessage, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    long messageId = fileMessage.MessageId;
    ...
});

Note: To send metadata along with a file, you can populate the DATA property.

Messages can be received by adding a channel handler. A received BaseMessage object is one of the following three message types.

UNIQUE_HANDLER_ID is a unique identifier to register multiple concurrent handlers.

SendBirdClient.ChannelHandler ch = new SendBirdClient.ChannelHandler();

ch.OnMessageReceived = (BaseChannel baseChannel, BaseMessage baseMessage) =>
{
    ...
};

SendBirdClient.AddChannelHandler(UNIQUE_HANDLER_ID, ch);

After creating a query instance from the CreatePreviousMessageListQuery() method and using the Load() method which returns a list of message objects, you can retrieve a set number of previous messages in an open channel. With the returned list, you can display the past messages in your UI once they have loaded

// There should only be one single instance per channel view.
PreviousMessageListQuery mListQuery = openChannel.CreatePreviousMessageListQuery();
...

mListQuery.Load(LIMIT, true, (List<BaseMessage> messages, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    ...
});

A limit parameter (30 in the above sample code) determines how many messages should be included in a returned list. A PreviousMessageListQuery instance itself does pagination according to the value of the limit parameter and internally manages a token to retrieve the next page in the result set. Each time the Load() method is called, the instance retrieves a set number of messages in the next page, and then updates the value of the token to complete the current call and prepare a next call.

If you create a new PreviousMessageListQuery instance and call the Load() method, a set number of the most recent messages are retrieved because its token has nothing to do with that of the existing instance. So we recommend that you create a single query instance and store it as a member variable for traversing through the entire message history.

Note: Before calling the Load() method again, you must receive a success callback from the server first.

You can query a set number of previous messages starting from the timestamp of the earliest message.

Note: The number of results may be larger than the set limit when there are multiple messages with the same timestamp as the earliest message.

MessageListQuery mListQuery = openChannel.CreateMessageListQuery();

mListQuery.Prev(EARLIEST_MESSAGE_TIMESTAMP, LIMIT, REVERSE_ORDER, (List<BaseMessage> list, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    // A list of previous messages is successfully retrieved.
    // Through the "list" parameter of the callback function,
    // you can access and display the data of each message from the result list that Sendbird server has passed to the callback function.
    foreach (BaseMessage message in list)
    {
        ...
    }

    ...
});

A user can delete any messages sent by themselves. An error is returned if a user attempts to delete the messages of other participants. Also operators of a channel can delete any messages in the channel.

channel.DeleteMessage(BASE_MESSAGE, (SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    // The message is successfully deleted from the channel.
    ...
});

The OnMessageDeleted() of a channel handler will be invoked after a message is deleted, and the result also notified to all other participants in the channel.

SendBirdClient.ChannelHandler ch = new SendBirdClient.ChannelHandler();

ch.OnMessageDeleted = (BaseChannel baseChannel, long messageId) =>
{
    ...
};

SendBirdClient.AddChannelHandler(UNIQUE_HANDLER_ID, ch);

Participants are online users who are currently receiving all messages from the open channel.

UserListQuery mListQuery = openChannel.CreateParticipantListQuery();

mListQuery.Next((List<User> list, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    // A list of participants in the channel is successfully retrieved.
    // Through the "list" parameter of the callback function,
    // you can access and display the data of each message from the result list that Sendbird server has passed to the callback function.
    foreach (User participant in list)
    {
        ...
    }

    ...
});

To retrieve the latest and updated information on each online participant in an open channel, you need another UserListQuery instance for the channel. Like the Retrieve a list of participants section above, create a query instance using the openChannel.CreateParticipantListQuery(), and then call its Next() method consecutively to retrieve the latest.

If you want to retrieve the online status of users at the application level, create another UserListQuery instance using the SendBirdClient.CreateUserListQuery(), and use its Next() method to retrieve instead.

By calling the ConnectionStatus at each User object in a returned list, you can then retrieve the current connection status of each user.

The user.ConnectionStatus returns one of the following two values:

Note: If you need to keep track of the connection status of some users in real time, we recommend that you call periodically the Next() method of a UserListQuery instance with its userIdsFilter filter specified, perhaps in intervals of one minute or more.

You can also create a query to get a list of muted or banned users in an open channel. This query is only available for users who are registered as operators of the open channel.

UserListQuery mListQuery = openChannel.CreateBannedUserListQuery(); //or CreateMutedUserListQuery()

mListQuery.Next((List<User> list, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    ...
});