Open Channel

Open Channel is a public chat. In this channel type, anyone can enter and participate in the chat without permission. A single channel can handle thousands of simultaneous users like Twitch-style public chat.


Creating an open channel

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:

In the dashboard, click OPEN CHANNELS, then click CREATE at the top-left corner. In the dialog box that appears, specify the name, url, cover image, and custom type of a channel. The channel url is a unique identifier.

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

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

You can also append information by passing additional arguments.

OpenChannel.CreateChannel(NAME, COVER_IMAGE_OR_URL, DATA, CUSTOM_TYPE, (OpenChannel openChannel, SendBirdException e) => {
    if(e != null) {
        / Error.
        return;
    }
});
  • NAME: the name of a channel, or the channel topic.
  • COVER_IMAGE_OR_URL: the file or URL of the cover image, which you can fetch to render into the UI.
  • DATA: the String field to store structured information, such as a JSON String.
  • CUSTOM_TYPE: the String field that allows you to subclassify your channel.

Note: See the Advanced section for more information on cover images and custom types.


Getting a list of open channels

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

OpenChannelListQuery mChannelListQuery = OpenChannel.CreateOpenChannelListQuery();
mChannelListQuery.Next((List<OpenChannel> channels, SendBirdException e) => {
    if (e != null) {
        // Error.
        return;
    }
});

Getting an open channel instance with a URL

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.

Store channel URLs to handle lifecycle or state changes in your app. For example, if a user disconnects from SendBird 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.

OpenChannel.GetChannel(channelUrl, (OpenChannel openChannel, SendBirdException e) => {
    if (e != null) {
        // Error!
        return;
    }

    // Successfully fetched the channel.
    // Do something with openChannel.
});

Entering an open channel

A user must enter an open channel to receive messages. You can enter up to 10 open channels at once. Entered open channels are valid only within the current connection. If you disconnect or reconnect to SendBird, you must re-enter channels to continue receiving messages.

OpenChannel.GetChannel(CHANNEL_URL, (OpenChannel openChannel, SendBirdException e) => {
    if (e != null) {
        // Error.
        return;
    }

    openChannel.Enter((SendBirdException e) => {
        if (e != null) {
            // Error.
            return;
        }
    });
});

Exiting the open channel

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

OpenChannel.GetChannel(CHANNEL_URL, (OpenChannel openChannel, SendBirdException e) => {
    if (e != null) {
        // Error.
        return;
    }

    openChannel.Exit((SendBirdException e) => {
        if (e != null) {
            // Error.
            return;
        }
    });
});

Sending messages

In an entered channel, a user can send messages of the following types:

  • UserMessage: text message sent by user.
  • FileMessage: binary message sent by user.

You can additionally specify a CUSTOM_TYPE to further subclassify a message. When you send a text message, you can additionally attach arbitrary strings via a data field. You can utilize this field to send structured data such as font sizes, font types, or custom JSON objects.

Delivery failures due to the network issues returns an exception. By implementating the callback within sendUserMessage(), it is possible to display only the messages that are successfully sent.

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

A user can also send any binary file through SendBird. There are two ways in which you can send a binary file: by sending the file itself, or by sending a URL.

By sending a raw file, you are uploading it to the SendBird servers. Alternatively, you can choose to send a file hosted in your own servers by passing in a URL that points to the file. In this case, your file is hosted in the SendBird servers, and downloaded through your own servers instead.

Note: If you upload your file directly, a size limit is imposed per file. This limit depends on your plan, and can be viewed from your Dashboard. No file size limit is imposed if you send a file message via a URL. The the file isn't uploaded to the SendBird servers.

// 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) {
        // Error.
        return;
    }
});

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

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


Receiving messages

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

  • UserMessage: text message sent by user.
  • FileMessage: binary message sent by user.
  • AdminMessage: message sent by an admin through the Platform API.

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);

Loading previous messages

You can load previous messages by creating a PreviousMessageListQuery instance and calling Load(). You can display the past messages in your UI once they have loaded.

PreviousMessageListQuery mPrevMessageListQuery = openChannel.CreatePreviousMessageListQuery();
mPrevMessageListQuery.Load(30, true, (List<BaseMessage> messages, SendBirdException e) => {
    if (e != null) {
        // Error.
        return;
    }
});

Past messages are queried in fixed numbers (30 in the above code). A new PreviousMessageListQuery instance loads the most recent n messages. Load() on the same query instance returns n messages before that. So if you store your query instance as a member variable, you can traverse through your entire message history.

Note: You must ensure that you have received a callback before calling Load() again.


Loading messages by timestamp

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 mMessageListQuery = openChannel.CreateMessageListQuery();
mMessageListQuery.Prev(EARLIEST_MESSAGE_TIMESTAMP, LIMIT, REVERSE_ORDER, (List<BaseMessage> list, SendBirdException e) => {
    if (e != null) {
        // Error.
        return;
    }
});

Getting a list of participants in a channel

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

UserListQuery mQuery = openChannel.CreateParticipantListQuery();
mQuery.Next((List<User> list, SendBirdException e) => {
    if (e != null) {
        // Error.
        return;
    }
});

Getting participants' online statuses

To retrieve current connection status of each participant, you must obtain a new UserListQuery for seeing the latest and updated information on each user. To get a UserListQuery for a specific channel, call OpenChannel.CreateParticipantListQuery(). If you want to get the list of all users of your app, call SendBirdClient.CreateUserListQuery().

You can then check each of the users' connection statuses by retrieving user.ConnectionStatus.

Note: If your app needs to keep track of users' connection statuses in real time, we recommend that you receive a new UserListQuery periodically, perhaps in intervals of one minute or more.

ConnectionStatus can return one of three values:

  • User.ConnectionStatus.NON_AVAILABLE: user's status information cannot be reached.
  • User.ConnectionStatus.OFFLINE: user is disconnected from SendBird.
  • User.ConnectionStatus.ONLINE: user is connected to SendBird.

Getting a list of banned or muted users in a channel

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 mQuery = openChannel.CreateBannedUserListQuery(); //or CreateMutedUserListQuery()
mQuery.Next((List<User> list, SendBirdException e) => {
    if (e != null) {
        // Error.
        return;
    }
});

Deleting messages

Users can delete messages. An error is returned if a user tries to delete messages sent by someone else. Also channel operators can delete any message in the channel, including those by other users.

Deleting a message fires a MessageDeleted event to all other users in the channel.

channel.DeleteMessage(BASE_MESSAGE, (SendBirdException e) => {
    if (e != null) {
        // Error.
        return;
    }
});

You can receive a MessageDeleted event using a ChannelHandler.

SendBirdClient.ChannelHandler ch = new SendBirdClient.ChannelHandler();
ch.OnMessageDeleted = (BaseChannel baseChannel, long messageId) => {
};
SendBirdClient.AddChannelHandler(UNIQUE_HANDLER_ID, ch);