A group channel is a chat that allows close interactions among a limited number of users.
Group channels can be private or public. A private group channel can let a user join the chat through an invitation by another user who is already a member of the chatroom. For 1-to-1 messaging, you can create a private group channel with two members. A public group chat can let a user join the chat without invitation from others. A group channel can consist of one to one hundred members by default setting. This default number of members can increase per request.
A user can receive all messages from the group channels that they are a member of, and sends a message to those channels. They can also receive push notifications, typing indicators, unread counts and read receipts from the joined channels when they go offline. For more information, see the Push notifications page.
Sendbird Chat SDK for Flutter allows you to use a variety of behavior-related properties when creating different types of group channels.
A private group channel can be joined only by users that have accepted an invitation from an existing channel member by default. On the other hand, a public group channel can be joined by any user without an invitation, like an open channel.
distinct group channel can be reused for the same users. If a user is invited as a new member, or if a member leaves the channel, then the distinct property is automatically disabled. For example, when attempting to create a new group channel with three users, A, B, and C, if a channel with the same users already exists, a reference to the existing channel is just returned to who has attempted the new channel.
Note: We recommend that you set the
isDistinctproperty to true in 1-to-1 messaging channels to continue using the same existing channel when a user sends a message to another user. If the property is false*, a new group channel is created with the same users even if there is an existing channel containing them.
For occasions that demand engagement among a high volume of members, you can create a Supergroup channel, an expanded version of a group channel. When the
isSuper property is set to true, a Supergroup channel is created and more than 2,000 members can gather in the channel. The maximum number of members in a Supergroup channel varies by your Sendbird plan.
Note: When the
isSuperis set to true, the
isDistinctoption can't be supported.
Messages sent in an ephemeral group channel are not saved in Sendbird's database. As such, old messages that are pushed out of a user's chat view due to new messages can't be retrieved. On the other hand, messages sent in a persistent group channel are stored permanently in the database by default.
A user can create a group channel from inviting other users in their client app. At the implemention level, you need to create a
GroupChannelParams object with a list of user IDs to invite. In the params, you can also specify a user ID to designate as an operator in the channel. Then, write a code what passes the user ID list as an argument to a parameter in the
Before you write the code for creating a group channel for a typical 1-to-1 chat, you should make sure that you turn on the
isDistinct property of the channel. Otherwise, if you turn off the
isDistinct property, a new channel will be created with the same partner user even if there is already an existing channel between them. In this case, multiple 1-to-1 channels between the same two users can exist, each with its own chat history and data.
However, if you plan to create a Supergroup channel, the
isDistinct property should be turned off.
Only members of a group channel can invite new users to the channel. You can also determine whether the newly invited user sees the past messages in the channel or not.
Note: You can set the
Chat historyoption under Settings > Chat > Channels > Group channels in the Sendbird Dashboard. If the option is turned on, new members can view all messages that had been sent before they joined the channel. If turned off, new members only see messages sent after they came in. By default, this option is turned on.
A user who is invited to a group channel can accept or decline the invitation. If a user accepts an invitation, they join the channel as a new member and can start chatting with other members. Otherwise, the invitation will be canceled if a user declines it. Since a user is allowed to join up to 2,000 group channels, the invitation to a user who already belongs to a maximum number of group channels will be canceled automatically.
By implementing the
onUserDeclinedInvitation() in the channel event handler, you can make the client apps of other members in the foreground to be notified of the results of two actions above.
Note: By using the
setChannelInvitationPreference()you can determine for users within an application whether or not to automatically join a private group channel promptly from an invitation without having to accept it. By default, the value of channel invitation preference is true. If you want to give them the option to decide whether to accept or decline an invitation, you should set the value of the preference to false through the
setChannelInvitationPreference()like the following sample code.
This is only for public group channels. Any user can join a public group channel as a member without an invitation and chat with other members in the channel. Since a user is allowed to join up to 2,000 group channels, a user who already belongs to a maximum number of group channels can't join a new channel.
If a user leaves a group channel, the user can't receive messages from the channel anymore.
You can temporarily freeze a group channel in order to stop members from chatting in the channel. Unfreezing the channel will enable the members to enjoy the chat again.
Note: In a frozen channel, regular members can't chat with each other, but the operators can send a message to the channel.
Note: Using the
includeEmptyChanneloption of a
GroupChannelListQueryinstance, you can determine whether to include empty channels in the result. Empty channels are group channels that have been created but don't contain any messages, and thus aren't included in the result by default. However, if you turn off the
Chat historyoption in your dashboard, you may retrieve empty channels in the result.
Note: Refer to this section in the Group channel > Advanced page for information on how to search for specific group channels with keywords and filters.
Since a channel URL is a unique identifier of a group channel, you can use a URL when retrieving a channel object.
Note: We recommend that you store a user's channel URLs to handle the lifecycle or state changes of your client app, or 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.
The following code will allow you to hide or archive a specific group channel from a list of the channels.
userIdsIncludeFilter, you can filter group channels by user IDs. Let's assume the ID of the current user is “Harry” and the user is a member of three group channels:
- Channel A: Harry and Jay.
- Channel B: Harry, John, and Jin.
- Channel C: Harry, John, Jin, and Jay.
userIdsExactFilter returns a list of the current user's group channels containing exactly the queried user IDs. In case you specify only one user ID in the filter, the filter returns a list of the current user's one or more distinct 1-to-1 group channels with the specified user.
userIdsIncludeFilter returns a list of the current user's group channels including the queried user IDs partially and exactly. Depending on the value of the
GroupChannelListQueryType parameter, different results can be returned.
In a group channel, users 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 custom type. This custom type takes on the form of a
String and can be used to search or filter messages. It allows you to append information to your message and customize message categorization.
The following code shows several types of parameters that you can configure to customize text messages by using a
UserMessageParams. Under the
UserMessageParams object, you can assign values to
data and other properties. By assigning an arbitrary string to the
data property, you can set custom font size, font type or
JSON object. To send your messages, you need to pass the
UserMessageParams object as an argument to the parameter in the
Through the result 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 will return.
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 file 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 the Sendbird 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.
The following code shows several types of parameters that you can configure to customize your file messages by using a
FileMessageParams. Under the
FileMessageParams object, you can assign specific values to customType and other properties. To send your messages, you need to pass the
FileMessageParams object as an argument to the parameter in the
Through the result of the
sendFileMessage() 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 will return.
You can reply to a specific message in a channel through the
sendFileMessage() method. To do so, you should create a
UserMessageParams or a
FileMessageParams object and then specify the
parentMessageId property of the object. Sending reply messages works the same way as sending regular messages to a channel except replies have an additional
When replying to a message through the
sendUserMessage() method, specify and pass a
UserMessageParams object to the method as a parameter.
When replying with a file message through the
sendFileMessage() method, specify and pass a
FileMessageParams object as an argument to a parameter in the method.
When a member wants to call the attention of other members in a group channel, they can mention those members in a message. To do so, you should:
- Specify a list of the user IDs to mention in the
- Add the list to either the
FileMessageParamswhich may contain options for further action.
- Pass the params to either to the
- Only up to ten members mentioned in the message will be notified.
The following code shows how to mention channel members in a message.
Message reactions will help you build an engaging chat experience that goes beyond text messages. They are a quick and easy way for users to respond to a message. Users can express their acknowledgement of or feelings about a message without written text by simply adding reactions. They can also view and delete their reactions to the message.
Note: Currently, message reactions are only available in group channels.
You can also decide how to display reactions that were added to messages in the current user’s chat view.
If one of the group channel members reacts to a message, the
onReactionUpdated() method in the channel event handler will be invoked on all channel members’ devices including the one that belongs to the current user. The
apply() method will reflect the reaction change to the message in real time.
loadNext() method of a
PreviousMessageListQuery instance which returns a list of
BaseMessage objects, you can retrieve a set number of previous messages in an group channel. With a returned list, you can display the past messages in your UI once they have loaded.
Note: You can decide whether a user can see the messages sent prior to the user joining a group channel. In the Sendbird Dashboard, go to the Settings > Chat > Channels > Group channels, there is the Chat history option. If turned on, new users are allowed to view a message history in joined group channels. If turned off, new users aren't allowed to see the messages prior to joining a group channel.
limit parameter determines how many messages should be included in a returned list. A
PreviousMessageListQuery instance itself does pagination of a result set based on the value of the
limit parameter, and internally manages a token to retrieve the next page in the result set.
Each time the
loadNext() 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 query instance and call the
loadNext() method, a set number of the most recent messages are retrieved because its token has nothing to do with the previously created 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
loadNext()method again, the previous call should have been completed.
The following table shows all the supported filters for
PreviousMessageListQuery to search for messages you want to retrieve. You can use any filters in a similar fashion with the sample code above.
Messages with the specified message type. The
Messages with the specified custom types. The
Messages that are sent by the specified users. The
getMessagesByTimestamp() method, you can retrieve a set number of previous and next messages on both sides of a specific timestamp in a group channel.
The following code shows several types of parameters that you can configure to customize a message query by using MessageListParams. Under the
MessageListParams object, you can assign specific values to
customType, and other properties. To retrieve messages in a channel, you need to pass the
MessageListParams object as an argument to the parameter in the
You can also retrieve a set number of previous and next messages on both sides of a specific message ID in a group channel, using the
getMessagesById() and a
loadNext() method of the
PreviousMessageListQuery instance returns a list of
BaseMessage objects. With this method, you can retrieve previous messages in a specific channel.
To include the replies of the target messages in the results, change the value of the
includeReplies property set to true.
When using either of the methods above, you can also pass a
MessageListParams object as an argument to the parameter in those methods.
getMessagesByTimestamp() method returns a set number of messages of previous and next messages on both sides of a specific timestamp in a channel.
getMessagesById() method returns a set number of previous and next messages on both sides of a specific message ID in a channel.
A user can update any of their own text and file messages sent through the
updateFileMessage methods. An error is returned if a user attempts to update another user's messages. In addition, channel operators can update any messages sent in a channel.
If a message is updated, the
onMessageUpdated() method in the channel event handler will be invoked on all channel participants' devices except the one that updated the message.
A user can delete any messages which were sent by themselves. An error is returned if a user attempts to delete the messages of other members. Channel operators can delete any messages in a channel as well.
If a message is deleted, the
onMessageDeleted() method in the channel event handler will be invoked on all channel participants' devices including the one that deleted the message.
A user can copy and send their own message in the same channel or to another channel. Both user messages and file messages can be copied.
Type: Function(BaseMessage, SBError)
resetMyHistory() method, you can help the current user clear the chat history in a group channel and start a fresh conversation with other members in the same channel.
The method clears the chat history only from the current user’s channel view and other members can still see all the messages in their channel view. Also, those messages aren’t deleted from the database of the Sendbird server.
resetMyHistory() method simply clears the messages for the current user by updating the properties of a
groupChannel object, including the
readReceipts and other internally managed data such as the number of unread messages.
Note: This feature is effective only when the Chat history option is turned on in the Sendbird Dashboard under Settings > Chat > Channels > Group channels.
When a user is online, all data associated with the group channels they are a member of are automatically updated by the
SendbirdSdk instance. However, when a user is disconnected from Sendbird server and reconnected later, you should call the
refresh() method to update the channels with the latest information.
Note: If you want your users to see the most recently updated channels when their client app comes to the foreground, we recommend you call the
onReconnectionSucceeded()method which receives a callback from Sendbird server when successfully reconnected.
You can retrieve a list of members in a group channel using the members property of a
To stay updated on the online status of each member in a group channel, call the
refresh() method before using the members property of a
groupChannel object to retrieve the members of the channel.
By checking the
connectionStatus property of each
Member object in the members property, you can then retrieve the user's current connection status.
Note: If your client app needs to keep track of the connection status of users in real time, we recommend that you periodically call the
loadNext()method of a
ApplicationUserListQueryinstance after specifying its
userIdsfilter, perhaps in intervals of one minute or more.
Members and operators of a group channel can be retrieved by using the
loadNext() method of a
GroupChannelMemberListQuery instance. For a specific order, set either of the values in the following table to the order property of a
The following table lists the values you can set to sort the list of members and operators.
Arranges members and operators in the alphabetical order of their nickname (default).
Lists operators before members, both in the alphabetical order of their nickname.
Operators are those who monitor and control the activities in a group channel. The following table lists the values you can set to filter operators in a group channel. Set one of these values to the
operatorFilter of a
Not applies any filter to the group channel member list (default).
Retrieves only the operators of a group channel.
Retrieves only the regular members of a group channel, excluding operators.
Operators are those who monitor and control the activities in a group channel. You can create an
OperatorListQuery instance and use the
loadNext() method to retrieve only a list of operators of a specific group channel.
You can register members as an operator of a group channel by passing their user ID into the
You can remove operators from a group channel by passing the user ID of operators into the
removeOperators() method. However, the demoted operators will still be kept as channel members.
If you want to remove all operators in a group channel at once, use the
removeAllOperators() method as follows.
You can create a query instance to get a list of users who are banned or muted from a group channel.
Note: Only operators of a group channel can use this functionality.
The Ban feature allows operators of a group channel to remove any users that display inappropriate behaviors in the channel. Banned users are immediately expelled from a channel and allowed to join the channel again only after the time period set by the operators. The operators can ban and unban users from group channels using a user ID as follows.
The Mute feature allows operators of a group channel to prohibit a group of selected users from sending messages. Muted users can remain in the channel and are allowed to view the messages, but can't send any new messages until the operators unmute them. Operators can mute and unmute users in the channel using a user ID as follows.
In a group channel, a user can report suspicious or inappropriate messages as well as the other users who use abusive language. The user can also report channels if there is any inappropriate content or activity within the channel. Based on this feature and our report API, you can build a clean in-app chat environment without objectionable content and subject.
To report a message, user, or channel, you should specify the report category in the code. The following table lists the categories you can use.
Messages, users, and channels that attempt to conspire, plot, or organize dangerous and illegal activities that could harm other people, including crime and terrorism.
Messages, users, and channels that are intended to intimidate, harass, bully, or insult other people.
Messages, users, and channels that are disrespectful, offensive, and hurtful toward other people.
A cascade of repetitive messages that contain identical, and irrelevant content to the interaction and context of the channel. They can also entice people to install malicious software in their devices.