Unity
Group Channel

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.


Create a channel

A group channel can be created on demand by a user through the Unity 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.

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

You can also append information by passing additional arguments.

Light Color Skin
Copy
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 page for more information on cover images and custom types.

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


Retrieve a channel by URL

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

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

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

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.


Invite users as members

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 > Application > Messages tab, and there is the Show channel 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 Show channel history option is turned on.

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

Leave a channel

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

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

Retrieve a list of channels

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.

Light Color Skin
Copy
GroupChannelListQuery mQuery = GroupChannel.CreateMyGroupChannelListQuery();
mQuery.IncludeEmpty = true;
mQuery.Next((List<GroupChannel> list, SendBirdException e) => {
    if (e != null) {
        // Error.
        return;
    }
});

Filter channels by user IDs

To filter a channel search by user ID, call the SetUserIdsExactFilter() or SetUserIdsIncludeFilter() method. 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.

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

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

Send a message

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

Message delivery failures due to the network issues return an exception. By implementing the callback method of the sendUserMessage(), it is possible to display only the messages that are successfully sent.

Light Color Skin
Copy
channel.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 a SendBird server and it can be downloaded from the SendBird server when needed in client apps. As another option, you can choose to send a file hosted in your own server by passing a URL that represents the location of the file as a parameter. In this case, your file isn't hosted in a SendBird server, and can be downloaded only from your own server instead.

Note: If you upload a 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 a SendBird server.

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


Receive messages through a channel handler

Messages can be received by adding a channel handler. 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.

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

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

Light Color Skin
Copy
SendBirdClient.RemoveChannelHandler(UNIQUE_HANDLER_ID);

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 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 > Application > Messages tab, there is the Show channel 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.

Light Color Skin
Copy
PreviousMessageListQuery mPrevMessageListQuery = groupChannel.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.


Delete a message

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.

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

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.

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 all members

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

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

Light Color Skin
Copy
groupChannel.Refresh((SendBirdException e) => {
    if (e != null) {
        //Error.
        return;
    }
});

Retrieve the online status of members

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:

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

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.