Group channel

A group channel is a private chat. A user may join the chat only through an invitation by another user who is already a member of the chatroom. A group channel can consist of one to hundreds of members. Creating a channel with two members allows 1-on-1 messaging.

A user automatically receives all messages from the group channels that they are a member of.

A group channel can be created on demand by a user through the Chat SDK.

distinct option: Determines whether to resume an old channel or to create an entirely new one when someone attempts to open a new channel with a pre-existing member combination. If there is a group channel with those members, the attempt will re-start the existing channel that has their chat history. For example, in the case that a group channel with 3 members, A, B, and C, already exists, attempting to create a new channel with the same members just returns a reference to the existing channel.

Consequently, we recommend that you set the distinct option to true in 1-on-1 messaging channels to reuse the existing channel when a user directly sends a message to another user. If the option is false, a new group channel is created with the same user even if there is a previous chat between them, and you can't see the old messages or data.

GroupChannel.CreateChannelWithUserIds(userIds, false, (GroupChannel groupChannel, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

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

You can also append information by passing additional arguments.

GroupChannel.CreateChannel(USER_IDS, IS_DISTINCT, NAME, COVER_IMAGE_OR_URL, DATA, CUSTOM_TYPE, (GroupChannel groupChannel, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

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

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

You can also create channels through Chat Platform API. If you want to control channel creations and member invitations on the server-side, use the Chat API.

Note: By default, the Allow creating group channels option is turned on which means that group 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.

Only members of a group channel can invite new users into the channel. You can determine whether the newly invited user sees the past messages in the channel or not. In your dashboard, go to the Settings > Chat > Channels > Group channels, and there is the Chat history option. If you turn on the option, new users can view all messages sent before they have joined the channel. If not, new users can see only messages sent after they have been invited.

Note: By default, the Chat history option is turned on.

groupChannel.InviteWithUserIds(userIds, (SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    ...
});

A user can leave group channels as shown below. After leaving, the user can't receive messages from the channel, and this method can't be called for deactivated users.

groupChannel.Leave((SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    ...
});

You can get a list of the current user's group channels, using the GroupChannelListQuery instance's Next() method which returns a list of GroupChannel objects.

Note: You can also set an option to include empty channels with mQuery.IncludeEmpty = true. Empty channels are channels that have been created but contain no sent messages. By default, empty channels are not shown.

GroupChannelListQuery mListQuery = GroupChannel.CreateMyGroupChannelListQuery();
mListQuery.IncludeEmpty = true;

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

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

    ...
});

Since a channel URL is a unique identifier of a group channel, you can use a URL to retrieve a channel instance.

GroupChannel.GetChannel(channelUrl, (GroupChannel groupChannel, SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

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

Note: We recommend that you store a user's channel URLs to handle the lifecycle or state changes of your app. 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, then re-entering the user into the channel.

To filter channels by user IDs, use the SetUserIdsExactFilter() or SetUserIdsIncludeFilter(). Let's assume the ID of the current user is Harry and the user is a member of two group channels:

• channelA consists of Harry, John, and Jay.
• channelB consists of Harry, John, Jay, and Jin.

An ExactFilter returns the list of channels containing exactly the queried userIDs.

GroupChannelListQuery mListQuery = GroupChannel.CreateMyGroupChannelListQuery();

List<string> userIds = new List<string>();
userIds.Add("John");
userIds.Add("Jay");

mListQuery.setUserIdsExactFilter(userIds);

mListQuery.Next(
    ...

    // Only channelA is returned in a result list through the "groupChannels" parameter of the callback function.
    ...
)

An IncludeFilter returns channels where the userIDs are included. This method can return one of two different results, based on the parameter queryType.

GroupChannelListQuery mListQuery = GroupChannel.CreateMyGroupChannelListQuery();

List<String> userIds = new List<string>();
userIds.Add("John");
userIds.Add("Jay");
userIds.Add("Jin");

mListQuery.SetUserIdsIncludeFilter(userIds, GroupChannelListQuery.QueryType.AND);

mListQuery.Next(
    ...

    // Only channelB including {'John', 'Jay', 'Jin'} as a subset is returned in a result list.
    ...
)

mListQuery.SetUserIdsIncludeFilter(userIds, GroupChannelListQuery.QueryType.OR);

mListQuery.Next(
    ...

    // channelA and channelB including {'John'}, channelA and channelB including {'Jay'}, channelB that including {'Jin'}.
    // Actually, channelA and channelB are returned in a result list.
    ...
)

Upon entering a group 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.

channel.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
channel.SendFileMessage(FILE, FILE_NAME, FILE_TYPE, FILE_SIZE, CUSTOM_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 file message with a file URL
channel.SendFileMessageWithURL(FILE_URL, FILE_NAME, FILE_TYPE, FILE_SIZE, CUSTOM_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 can be of one of three different types of messages.

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

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

ch.OnMessageReceived = (BaseChannel baseChannel, BaseMessage baseMessage) =>
{
    // A chat message has been received.
};

SendBirdClient.AddChannelHandler(UNIQUE_HANDLER_ID, ch);

When the UI isn't valid anymore, remove the channel handler.

SendBirdClient.RemoveChannelHandler(UNIQUE_HANDLER_ID);

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 a group channel. With the returned list, you can display the past messages in your UI once they have loaded

Note: Whether a user can load previous messages sent before joining the channel depends on your settings. In your dashboard, go to the Settings > Chat > Channels > Group channels, there is the Chat history option. If this option is turned on, new users can view all messages sent before they have joined the channel. If not, new users can see only messages sent after they had been invited.

PreviousMessageListQuery mListQuery = groupChannel.CreatePreviousMessageListQuery();
...

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

    ...
});

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

A user can delete their own messages. An error is returned if a user attempts to delete messages sent by others. Also channel operators can delete any message in the channel, including those by other users.

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

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

The MessageDeleted() method of a channel handler will receive a callback from the server when a message is deleted, and the result also notified to all other members in the channel, including who has deleted their own message.

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

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

SendBirdClient.AddChannelHandler(UNIQUE_HANDLER_ID, ch);

You can retrieve a list of all members in a group channel using the channel.Members property.

List<User> members = groupChannel.Members;

Members of a group channel are automatically updated when a user is online. But when a user is disconnected from Sendbird server and reconnected, you must call the Refresh() method to update the user's group channels with the latest information.

groupChannel.Refresh((SendBirdException e) =>
{
    if (e != null)
    {
        // Handle error.
    }

    ...
});

To stay updated on each member's connection status, you should call the channel.Refresh() before accessing the channel.Members. You can then check each of the users' connection statuses by accessing user.ConnectionStatus.

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 your application needs to keep track of the connection status of users in real time, we recommend that you call periodically the Next() method of a UserListQuery, perhaps in intervals of one minute or more.