.NET
Open Channel

Open Channel

An open channel is basically a public chat and it can handle a large number of participants online. In this channel type, anyone can enter and participate in the chat without permission. A single open channel can accomodate up to 1,000, simultaneous users like Twitch-style public chat. This maximum number of an open channel's participants can increase per request.


Create a channel

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 Moderation > Open Channels menu, and then click Create Channel at the top-right corner.
  2. 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 of a channel.)

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

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

You can also append information by passing additional parameters.

Light Color Skin
Copy
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.


Retrieve a list of channels

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

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

Retrieve a channel by 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.

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

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

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.


Enter 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. (In case a user is reconnected by attempts of the SendBird instance from a temporary unstable connection, the user is automatically re-entered into the participating channels.)

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

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

Exit a channel

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

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

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

Send a message

In an entered open 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.

Message delivery failures caused by the unexpected network issues return an exception. By implementing the callback method of the SendUserMessage(), you can display messages that are successfully sent to a channel.

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

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

Sending a raw file indicates that you upload it to SendBird server and it can be downloaded from the server when needed in client apps. As another option, you can choose to send a file hosted on your server by passing a URL that represents the location of the file as a parameter. In this case, your file isn't hosted on SendBird server, and can be downloaded only from your own server instead.

Note: If you upload your file directly, a size limit is imposed per file depending on your plan. You can see your limit in the dashboard and adjust the limit via our sales team. No file size limit is imposed if you send a file message with its URL since the file isn't uploaded to SendBird server.

Light Color Skin
Copy
// 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.


Receive messages through a channel handler

Messages can be received through the OnMessageReceived() method of a channel handler. 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.

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

Light Color Skin
Copy
SendBirdClient.ChannelHandler ch = new SendBirdClient.ChannelHandler();
ch.OnMessageReceived = (BaseChannel baseChannel, BaseMessage baseMessage) => {
};
SendBirdClient.AddChannelHandler(UNIQUE_HANDLER_ID, ch);

Load previous messages

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

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

A limit parameter (30 in the above sample code) indicates 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 managess 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.


Load 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.

Light Color Skin
Copy
MessageListQuery mMessageListQuery = openChannel.CreateMessageListQuery();
mMessageListQuery.Prev(EARLIEST_MESSAGE_TIMESTAMP, LIMIT, REVERSE_ORDER, (List<BaseMessage> list, SendBirdException e) => {
    if (e != null) {
        // Error.
        return;
    }
});
  • EARLIEST_MESSAGE_TIMESTAMP: the reference timestamp.
  • LIMIT: the number of messages to retrieve.
  • REVERSE_ORDER: whether to reverse the results.

Delete a message

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.

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

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.

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

Retrieve a list of participants

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

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

Retrieve the latest information on participants

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:

  • User.ConnectionStatus.OFFLINE: the user is not connected to SendBird server.
  • User.ConnectionStatus.ONLINE: the user is connected to SendBird server.

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.


Retrieve a list of banned or muted users

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.

Light Color Skin
Copy
UserListQuery mQuery = openChannel.CreateBannedUserListQuery(); //or CreateMutedUserListQuery()
mQuery.Next((List<User> list, SendBirdException e) => {
    if (e != null) {
        // Error.
        return;
    }
});