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 Chat SDK.
distinctoption: 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
distinctoption 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.
You can also append information by passing additional arguments.
List of arguments
Specifies a list of one or more users to invite to the channel.
Determines whether to reuse an existing channel or create a new channel. If set to true, returns a channel with the same users in the
Specifies the channel topic, or the name of the channel.
Specifies the cover image URL of the channel, or uploads a file for the cover image.
Specifies additional channel information such as a long description of the channel or
Specifies the custom channel type which is used for channel grouping.
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.
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 > 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 historyoption is turned on.
Leave a channel
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.
Retrieve a list of channels
You can get a list of the current user's group channels, using the
Next() method which returns a list of
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.
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.
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.
Filter channels by user IDs
To filter channels by user IDs, use the
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.
An IncludeFilter returns channels where the userIDs are included. This method can return one of two different results, based on the parameter
Send a message
Upon entering a group channel, a user can send messages of the following types:
A text message sent by a user
A binary file message sent by a user
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.
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.
Note: To send metadata along with a file, you can populate the
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.
A text message sent by a user
A binary file message sent by a user
A text message sent by an admin through the Platform API
UNIQUE_HANDLER_ID is a unique identifier to register multiple concurrent handlers.
When the UI isn't valid anymore, remove the channel handler.
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 > Chat > Channels > Group channels, there is the
Chat historyoption. 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.
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.
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.
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.
Retrieve a list of all members
You can retrieve a list of all members in a group channel using the
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.
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
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:
The user is not connected to Sendbird server.
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.