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.

Note: Sendbird's JavaScript Chat SDK v3.0.140 or later is recommended to use dynamic partitioning open channels.

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 to 60,000 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 channels. 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 through the Chat SDK or the Chat API.

OpenChannel.createChannel(NAME, COVER_IMAGE_OR_URL, DATA, OPERATOR_IDS, CUSTOM_TYPE, function(openChannel, error) {
    if (error) {
        // 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.
    const channeUrl = openChannel.channelUrl;
    ...
});

Otherwise, you can create an open channel by passing a configured OpenChannelParams object as an argument to the parameter in the createChannel() method like the following.

var params = new sb.OpenChannelParams();
params.name = NAME;
params.coverUrlOrImage = FILE | COVER_URL;
params.operatorUserIds = ['Hoon', 'Doo']; // Or .operators(Array<User>)
params.data = DATA;
params.customType = CUSTOM_TYPE;
params.channelUrl = UNIQUE_CHANNEL_URL; // For an open channel, you can create a channel by specifying its unique channel URL in a `OpenChannelParams` object.

sb.OpenChannel.createChannel(params, function(openChannel, error) {
    if (error) {
        // Handle error.
    }

    // An open channel with detailed configuration is successfully created.
    // By using openChannel.channelUrl, openChannel.data, openChannel.customType, and so on,
    // you can access the result object from Sendbird server to check your OpenChannelParams configuration.
    const channeUrl = openChannel.channelUrl;
    ...
});

When creating a channel, you can also append additional information like cover image and description by passing several arguments to the corresponding parameters.

Note: Using the updateChannel() method, you can update the cover image URL of a channel.

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 when a user is disconnected from Sendbird server with the disconnect() and reconnected to the server with the connect(), you should make sure the user re-enters the open channels for them 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 particpating channel.

Note: When a user is reconnected by attempts of the SendBird instance from a temporary unstable connection, the Chat SDK will automatically re-enter the user to the participating channel.

sb.OpenChannel.getChannel(CHANNEL_URL, function(openChannel, error) {
    if (error) {
        // Handle error.
    }

    // Call the instance method of the result object in the "openChannel" parameter of the callback function.
    openChannel.enter(function(response, error) {
        if (error) {
            // Handle error.
        }

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

If a user exits an open channel, the user can't receive any messages from that channel.

sb.OpenChannel.getChannel(CHANNEL_URL, function(openChannel, error) {
    if (error) {
        // Handle error.
    }

    openChannel.exit(function(response, error) {
        if (error) {
            // Handle error.
        }

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

Only the operators of an open channel can delete the channel (the following code works properly in the operators' client apps only). Otherwise, an error is returned to a callback function.

sb.OpenChannel.getChannel(CHANNEL_URL, function(openChannel, error) {
    if (error) {
        // Handle error.
    }

    openChannel.delete(function(response, error) {
        if (error) {
            // Handle error.
        }

        // The channel is successfully deleted.
        ...
    });
});

An open channel can be freezed only with the Sendbird Dashboard or Chat API as opposed to a group channel which operators of the channel can do that via the Chat SDK.

To freeze, go to your dashboard and do the following: on the Chat > Open channels, select an open channel to freeze, and click the Freeze icon at the upper right corner. To unfreeze, click the icon again with the frozen channel selected.

Note: In a frozen channel, participants can't chat with each other but the operators can send a message to the channel.

You can retrive a list of OpenChannel objects using the next() method of an OpenChannelListQuery instance like the following.

var listQuery = sb.OpenChannel.createOpenChannelListQuery();

listQuery.next(function(openChannels, error) {
    if (error) {
        // Handle error.
    }

    // A list of open channels is successfully retrieved.
    // Through the "openChannels" 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.
    openChannels.forEach(channel => {
        ...
    });

    ...
});

Since a channel URL is a unique identifier of an open channel, you can use a URL when retrieving a channel object.

sb.OpenChannel.getChannel(CHANNEL_URL, function(openChannel, error) {
    if (error) {
        // 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.
    const channelName = openChannel.name;
    ...
});

Note: We recommend that you store a user's channel URLs to handle the lifecycle or state changes of your app, or any other unexpected situations. For example, when a user is disconnected from Sendbird server due to switching to another app temporarily, you can provide a smooth restoration of the user's state using a stored URL to fetch the appropriate channel instance.

In an entered 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 custom type. This custom type takes on the form of a String and can be used to search or filter messages. It allows you to append information to your message and customize message categorization.

The following code shows several types of parameters that you can configure to customize text messages by using UserMessageParams. Under the UserMessageParams object, you can assign specific values to message, data and other properties. By assigning arbitrary string to the data property, you can set custom font size, font type or JSON object. To send your messages, you need to pass the UserMessageParams object as an argument to the parameter in the sendUserMessage() method.

Through the callback function of the sendUserMessage() method, Sendbird server always notifies whether your text 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.

const params = new sb.UserMessageParams();

params.message = TEXT_MESSAGE;
params.customType = CUSTOM_TYPE;
params.data = DATA;
params.mentionType = 'users';                       // Either 'users' or 'channel'
params.mentionedUserIds = ['Jeff', 'Julia'];        // Or mentionedUsers = Array<User>;
params.metaArrays = [   // A pair of key-value
    new sendBirds.me.MessageMetaArray('itemType', ['tablet']),
    new sendBirds.me.MessageMetaArray('quality', ['best', 'good'])
];
params.translationTargetLanguages = ['fe', 'de'];   // French and German
params.pushNotificationDeliveryOption = 'default';  // Either 'default' or 'suppress'

openChannel.sendUserMessage(params, function(userMessage, error) {
    if (error) {
        // Handle error.
    }

    // A text message with detailed configuration is successfully sent to the channel.
    // By using userMesage.messageId, userMessage.message, userMessage.customType, and so on,
    // you can access the result object from Sendbird server to check your UserMessageParams configuration.
    // The current user can receive messages from other users through the onMessageReceived() method of an event handler.
    const messageId = userMessage.messageId;
    ...
});

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.

Note: You can use sendFileMessages(), which is another method that allows you to send up to 20 file messages per one method call. Refer to our API Reference to learn more about it.

The following code shows several types of parameters that you can configure to customize file messages by using FileMessageParams. Under the FileMessageParams object, you can assign specific values to customType and other properties. To send your messages, you need to pass the FileMessageParams object as an argument to the parameter in the sendFileMessage() method.

Through the callback function of the sendFileMessage() method, Sendbird server always notifies whether your file 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.

// Sending a file message with a raw file
const params = new sb.FileMessageParams();

params.file = FILE;             // Or .fileUrl = FILE_URL (You can also send a file message with a file URL.)
params.fileName = FILE_NAME;
params.fileSize = FILE_SIZE;
params.thumbnailSizes = [{maxWidth: 100, maxHeight: 100}, {maxWidth: 200, maxHeight: 200}]; // Add the maximum sizes of thumbnail images (allowed number of thumbnail images: 3).
params.mimeType = MIME_TYPE;
params.customType = CUSTOM_TYPE;
params.mentionType = 'users';                       // Either 'users' or 'channel'
params.mentionedUserIds = ['Jeff', 'Julia'];        // Or mentionedUsers = Array<User>;
params.pushNotificationDeliveryOption = 'default';  // Either 'default' or 'suppress'

openChannel.sendFileMessage(params, function(fileMessage, error) {
    if (error) {
        // Handle error.
    }

    // A file message with detailed configuration is successfully sent to the channel.
    // By using fileMesage.messageId, fileMessage.fileName, fileMessage.customType, and so on,
    // you can access the result object from Sendbird server to check your FileMessageParams configuration.
    // The current user can receive messages from other users through the onMessageReceived() method of an event handler.
    const messageId = fileMessage.messageId;
    ...
});

Messages sent from other participants can be received through the onMessageReceived() method in the channel event handler. A BaseMessage object for each received message is one of the following three message types.

The UNIQUE_HANDLER_ID is a unique identifier to register multiple concurrent handlers.

var channelHandler = new sb.ChannelHandler();

channelHandler.onMessageReceived = function(channel, message) {
    ...
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, channelHandler);

When a participant wants to call the attention of other participants in an open channel where push notifications are not allowed by default, they can mention those participants in a message. To do so, you should:

1. Specify a list of the user IDs to mention.
2. Add the list to either UserMessageParams or FileMessageParams which may contain options for further action.
3. Pass the params to either sendUserMessage() or sendFileMessage().
4. Then only up to 10 participants mentioned in the message will be notified.

var params = new sb.UserMessageParams();
params.message = MESSAGE;
params.mentionedUserIds = ['Harry', 'Jay', 'Jin'];

openChannel.sendUserMessage(params, function(message, error) {
    if (error) {
        // Handle error.
    }

    ...
});

After creating a query instance using 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 a 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.
var listQuery = openChannel.createPreviousMessageListQuery();
listQuery.limit = LIMIT;
listQuery.reverse = REVERSE;
listQuery.customType = CUSTOM_TYPE;
...

// Retrieving previous messages.
listQuery.load(function(messageList, error) {
    if (error) {
        // Handle error.
    }

    ...
});

A LIMIT parameter indicates how many messages should be included in a returned list. A query instance itself does pagination of a result set 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 query instance and call the load() method, a set number of the most recently sent messages are retrieved because its token has nothing to do with the previously created 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.

Using the getMessagesByTimestamp() method, you can retrieve a set number of previous and next messages on both sides of a specific timestamp in an open channel.

The following code shows several types of parameters that you can configure to customize a message query by using MessageListParams. Under the MessageListParams object, you can assign values to previousResultSize, messageType, customType, and other properties. To retrieve messages in a channel, you need to pass the MessageListParams object as an argument to the parameter in the getMessagesByTimestamp() method.

const params = new sb.MessageListParams();
params.isInclusive = IS_INCLUSIVE;
params.prevResultSize = PREV_RESULT_SIZE;
params.nextResultSize = NEXT_RESULT_SIZE;
params.shouldReverse = REVERSE;
params.messageType = MESSAGE_TYPE;
params.customType = CUSTOM_TYPE;
...

openChannel.getMessagesByTimestamp(TIMESTAMP, params, function(messages, error) {
    if (error) {
        // Handle error.
    }

    // A list of previous and next messages on both sides of a specified timestamp is successfully retrieved.
    // Through the "messages" 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.
    messages.forEach(message => {
        ...
    });

    ...
});

You can also retrieve a set number of previous and next messages on both sides of a specific message ID in an open channel, using the getMessagesByMessageId() method and MessageListParams object.

const params = new sb.MessageListParams();
params.isInclusive = IS_INCLUSIVE;
params.prevResultSize = PREV_RESULT_SIZE;
params.nextResultSize = NEXT_RESULT_SIZE;
params.shouldReverse = REVERSE;
params.messageType = MESSAGE_TYPE;
params.customType = CUSTOM_TYPE;
...

openChannel.getMessagesByMessageId(MESSAGE_ID, params, function(messages, error) {
    if (error) {
        // Handle error.
    }

    // A list of previous and next messages on both sides of a specified message ID is successfully retrieved.
    // Through the "messages" 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.
    messages.forEach(message => {
        ...
    });

    ...
});

A user can update any of their own text and file messages sent. An error is returned if a user attempts to update another user's messages. In addition, channel operators can update any messages sent in a channel.

const params = new sb.UserMessageParams();

params.message = NEW_TEXT_MESSAGE;
params.customType = NEW_CUSTOM_TYPE;
params.data = NEW_DATA;

// The MESSAGE_ID below indicates the unique message ID of a UserMessage object to update.
openChannel.updateUserMessage(MESSAGE_ID, params, function(userMessage, error) {
    if (error) {
        // Handle error.
    }

    // The message is successfully updated.
    // Through the "userMessage" parameter of the callback function,
    // you could check if the update operation has been performed right.
    const text = userMessage.message;
    ...
});

const params = new sb.FileMessageParams();

params.fileUrl = NEW_FILE_URL;      // The file in a message can't be updated.
params.fileName = NEW_FILE_NAME;
params.fileSize = NEW_FILE_SIZE;
params.customType = NEW_CUSTOM_TYPE;

// The MESSAGE_ID below indicates the unique message ID of a FileMessage object to update.
openChannel.updateFileMessage(MESSAGE_ID, params, function(fileMessage, error) {
    if (error) {
        // Handle error.
    }

    // The message is successfully updated.
    // Through the "fileMessage" parameter of the callback function,
    // you could check if the update operation has been performed right.
    const customType = fileMessage.customType;
    ...
});

If a message is updated, the onMessageUpdated() method in the channel event handler will be invoked on all channel participants' devices including the one that updated the message.

var channelHandler = new sb.ChannelHandler();

channelHandler.onMessageUpdated = function(channel, message) {
    ...
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, channelHandler);

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

// The MESSAGE below indicates a UserMessage or FileMessage object to delete.
openChannel.deleteMessage(MESSAGE, function(response, error) {
    if (error) {
        // Handle error.
    }

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

If a message is deleted, the onMessageDeleted() method in the channel event handler will be invoked on all channel participants' devices including the one that deleted the message.

var channelHandler = new sb.ChannelHandler();

channelHandler.onMessageDeleted = function(channel, messageId) {
    ...
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, channelHandler);

A user can copy and send their own message in the same channel or to another channel.

openChannel.copyUserMessage(TARGET_CHANNEL, MESSAGE_TO_COPY, function(message, error) {
    if (error) {
        // Handle error.
    }

    // The message is successfully copied to the target channel.
    ...
});

openChannel.copyFileMessage(TARGET_CHANNEL, MESSAGE_TO_COPY, function(message, error) {
    if (error) {
        // Handle error.
    }

    // The message is successfully copied to the target channel.
    ...
});

You can retrieve a list of participants who are currently online and receiving all messages from an open channel.

var listQuery = openChannel.createParticipantListQuery();

listQuery.next(function(participantList, error) {
    if (error) {
        // Handle error.
    }

    ...
});

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

You can also retrieve the latest and updated information on users at the application level. Like the Retrieve a list of users section, create a new query instance by using the sb.createApplicationUserListQuery(), and then call its next() method consecutively to retrieve the latest.

When retrieving the online (connection) status of a user, by checking the connectionStatus of each user object in a returned list, you can get the user's current connection status. The connectionStatus property has 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 ApplicationUserListQuery instance after specifying its userIdsFilter filter, perhaps in intervals of one minute or more.

You can follow the simple implementation below to retrieve a list of operators who monitor and control the activities in an open channel.

var listQuery = openChannel.createOperatorListQuery();

listQuery.next(function(operators, error) {
    if (error) {
        // Handle error.
    }

    ...
});

You can also retrieve a list of operators and check each of them like the following.

for(var operator in openChannel.operators) {
    ...
}

You can register participants as operators of an open channel.

openChannel.addOperators(OPERATOR_USER_IDS, function(response, error) {
    if (error) {
        // Handle error.
    }

    // The participants are successfully registered as operators of the channel.
    ...
});

You can cancel the registration of operators from an open channel but leave them as participants.

openChannel.removeOperators(OPERATOR_USER_IDS, function(response, error) {
    if (error) {
        // Handle error.
    }

    // The cancel operation is succeeded,
    // and you could display some message to those who are not operators anymore.
    ...
});

You can 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.

var listQuery = openChannel.createBannedUserListQuery();

bannedUserListQuery.next(function(userList, error) {
    if (error) {
        // Handle error.
    }

    ...
});

var listQuery = openChannel.createMutedUserListQuery();

listQuery.next(function(userList, error) {
    if (error) {
        // Handle error.
    }

    ...
});

Operators of an open channel can remove any users that behave inappropriately in the channel by using our Ban feature. Banned users are immediately expelled from a channel and allowed to participate in the channel again after the time period set by the operators. Operators can ban and unban users in open channels using the following code.

sb.OpenChannel.getChannel(CHANNEL_URL, function(openChannel, error) {
    if (error) {
        // Handle error.
    }

    // Banning and unbanning a user
    if (openChannel.isOperator(sb.getCurrentUser())) {
        openChannel.banUser(USER, SECONDS, function(response, error) {
            if (error) {
                // Handle error.
            }

            // The user is successfully banned from the channel.
            // You could notify the user of being banned by displaying a prompt.
            ...
        });

        openChannel.unbanUser(USER, function(response, error) {
            if (error) {
                // Handle error.
            }

            // The user is successfully unbanned for the channel.
            // You could notify the user of being unbanned by displaying a prompt.
            ...
        });
    }
});

Note: You can also use the banUserWithUserId() and unbanUserWithUserId() methods, instead of the banUser() and unbanUser(), as they have the same functionalities. You can find more information on the banUserWithUserId() and unbanUserWithUserID() in our API reference.

Operators of an open channel can prohibit the selected users from sending messages using our Mute feature. Muted users remain in the channel and are allowed to view the messages, but can't send any messages until the operators unmute them. Operators can mute and unmute users in open channels using the following code:

sb.OpenChannel.getChannel(CHANNEL_URL, function(openChannel, error) {
    if (error) {
        // Handle error.
    }

    // Muting and unmuting a user
    if (openChannel.isOperator(sb.getCurrentUser())) {
        openChannel.muteUser(USER, function(response, error) {
            if (error) {
                // Handle error.
            }

            // The user is successfully muted in the channel.
            // You could notify the user of being muted by displaying a prompt.
            ...
        });

        openChannel.unmuteUser(USER, function(response, error) {
            if (error) {
                // Handle error.
            }

            // The user is successfully unmuted in the channel.
            // You could notify the user of being unmuted by displaying a prompt.
            ...
        });
    }
});

Note: You can also use the muteUserWithUserId() and unmuteUserWithUserId(), instead of the muteUser() and unmuteUser(), as they have the same functionalities. You can find more information on the muteUserWithUserId() and unmuteUserWithUserID() in our API reference.

In an open channel, a user can report suspicious or harrassing messages as well as the other users who use abusive language. The user can also report channels if there are any inappropriate content or activity within the channel. Based on this feature and our report API, you can build your own in-app system for managing objectionable content and subject.

// Reporting a message.
openChannel.reportMessage(MESSAGE_TO_REPORT, REPORT_CATEGORY, DESCRIPTION, function(error) {
    if (error) {
        // Handle error.
    }

    ...
});

// Reporting a user.
openChannel.reportUser(OFFENDING_USER, REPORT_CATEGORY, DESCRIPTION, function(error) {
    if (error) {
        // Handle error.
    }

    ...
});

// Reporting a channel.
openChannel.report(REPORT_CATEGORY, DESCRIPTION, function(erorr) {
    if (error) {
        // Handle error.
    }

    ...
});