Group Channel

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.


Creating a group channel

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

Distinct property : A channel with the Distinct property turned on is always reused for the same members. If a new member is invited, or if a member leaves the channel, then the distinct property is disabled automatically. 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 turn on the Distinct property in 1-on-1 messaging channels to reuse the same channel when a user chooses to directly message a friend. If the property is turned off, a new channel is created with the same friend even if there is a previous conversation between them, and you can't see previously sent messages or data.

GroupChannel.CreateChannelWithUserIds(userIds, false, (GroupChannel groupChannel, SendBirdException e) => {
    if (e != null) {
        // Error.
        return;
    }
});

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) {
        // 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.

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


Getting a group channel instance with a URL

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

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.

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

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

Inviting users to an existing channel

Only members of the channel can invite new users into the channel.

You can determine whether the newly invited user sees the past messages in the channelo or not. In your Dashboard Settings > Messages section, there is an option to show channel history. 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.

Note: By default, Show channel history is turned on.

groupChannel.InviteWithUserIds(userIds, (SendBirdException e) => {
    if (e != null) {
        // Error.
        return;
    }
});

Leaving the group channel

If a user leaves the group channel, the user can't receive messages from the channel anymore.

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

Getting a list of my group channels

You can obtain a list of all group channels by creating a GroupChannelListQuery. The Next() method 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 mQuery = GroupChannel.CreateMyGroupChannelListQuery();
mQuery.IncludeEmpty = true;
mQuery.Next((List<GroupChannel> list, SendBirdException e) => {
    if (e != null) {
        // Error.
        return;
    }
});

Querying group channels by User IDs

It is possible to filter a channel search by user IDs. This can be done by calling SetUserIdsExactFilter(List<string> userIds) or SetUserIdsIncludeFilter(List<string> userIds, QueryType queryType).

Given an example where a user (with the ID "User") is part of two group channels:

  • channelA: { "User", John", "Jay" }
  • channelB: { "User", John", "Jay", "Jin" }

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

GroupChannelListQuery filteredQuery = GroupChannel.CreateMyGroupChannelListQuery();
List<string> userIds = new List<string>();
userIds.Add("John");
userIds.Add("Jay");

filteredQuery.setUserIdsExactFilter(userIds);
filteredQuery.Next(
...
    // returns channelA only.
)

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

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

filteredQuery.SetUserIdsIncludeFilter(userIds, GroupChannelListQuery.QueryType.AND);
filteredQuery.Next(
...
    // Returns only channelB that include the ids { John, Jay, Jin } as a subset.
)

filteredQuery.SetUserIdsIncludeFilter(userIds, GroupChannelListQuery.QueryType.OR);
filteredQuery.Next(
...
    // Returns channelA and channelB that include { John }, plus channelA and channelB that include { Jay }, plus channelB that include { Jin }.
    // Actually channelA and channelB are returned.
)

Sending messages

Upon entering a 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 size, font type, or a custom JSON object.

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

channel.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 isn't 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. Then the file isn't uploaded to the SendBird servers.

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

// 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) {
        // 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 can be of one of three different types of messages.

  • 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) => {
    // Received a chat message.
};
SendBirdClient.AddChannelHandler(UNIQUE_HANDLER_ID, ch);

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

SendBirdClient.RemoveChannelHandler(UNIQUE_HANDLER_ID);

Loading previous messages

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

Note: Whether a user can load messages prior to joining the channel depends on your settings. In your Dashboard Settings - Messages section, there is an option to show channel history. 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 mPrevMessageListQuery = groupChannel.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.


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

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