Create a group channel
You can create a group channel for 1-to-1 and 1-to-N conversations. By default, group channels are used for conversations between up to 100 members. This number can stretch up to tens of thousands in Supergroup channels. Group channels can either be private and invite only, or public. They support typing indicators, unread count and read receipts, allowing for an interactive chat experience. A user can join up to 2000 group channels, and higher numbers would negatively impact the performance for the end user. The Chat history is turned off by default and its settings can be changed on Sendbird Dashboard by going to Settings > Chat > Channels > Group channels > Chat history. To learn more about group channels, see Channel Overview.
Note: If you are seeing the error message
Maximum "channel join" count reached.
, then consider deleting channels that are no longer used. For situations where an agent connects with many customers such as support, delivery logistics or sales, we recommend using Sendbird Desk.
HTTP request
Request body
The following table lists the properties of an HTTP request that this action supports.
If you are creating a 1-to-1 direct messaging channel, it is recommended that you set the value of is_distinct
to true
. If is_distinct
is set to false
, a new channel is created even for users with shared chat history and all previous conversations will be lost. On the other hand, if the is_distinct
property is set to true
, no new channel is created for users with shared chat history, and every 1-to-1 conversation between the same two users will continue in the existing channel.
Properties
Required | Type | Description |
---|---|---|
users | array of objects | Specifies an array of one or more user objects to invite to the channel. Up to 100 users can be invited at a time. Specify a value for either |
Optional | Type | Description |
---|---|---|
user_ids | array of strings | Specifies an array of one or more IDs of users to invite to the channel. Up to 100 users can be invited at a time. Specify a value for either |
name | string | Specifies the name of the channel, or the channel topic. The length is limited to 191 characters. (Default: |
channel_url | string | Specifies the URL of the channel. Only numbers, letters, underscores, and hyphens are allowed. The allowed length is 4 to 100 characters, inclusive. If not specified, a URL is automatically generated. |
cover_url | string | Specifies the URL of the channel's cover image. This should be no longer than 2,048 characters. |
cover_file | file | Uploads an image file of your choice to be used as the channel's cover image. If you want to upload a picture by passing an image file instead of a URL, see Multipart requests. |
custom_type | string | Specifies a custom channel type which is used for channel grouping. Maximum length is 128 characters. |
data | string | Additional channel information such as a long description of the channel or |
is_distinct | boolean | Determines whether to reuse an existing channel or create a new channel when attempting to create a channel with the same group of members. By default, a new channel is created even if one already exists for the same members. You can override this and force an existing channel to be returned by setting a value of |
is_public | boolean | Determines whether to allow users to join the channel without an invitation. By default, a user must be invited to join a group channel. It is possible to allow any user to join a group channel without an invite by setting |
is_super | boolean | Determines whether to allow the channel to accommodate 100 or more members. By default, a group channel has a member limit of 100. A Supergroup channel must be used in order to have more than 100 channel members. A Supergroup channel has a member limit of 2000. |
is_ephemeral | boolean | Determines whether to preserve messages in the channel for the purpose of retrieving chat history. By default, all chat messages will be stored by Sendbird. This means that chat histories can easily be retrieved when using the SDK or API. |
access_code | string | Specifies an access code that is only applicable to public group channels. If a value is specified for |
inviter_id | string | Specifies the ID of a user who invites other users to the channel. The inviter isn't automatically registered to the channel as a member, so you should specify the ID of the inviter in the |
strict | boolean | Determines whether to receive a |
invitation_status | object | Specifies one or more key-value pair items which set the invitation status of each user invited to the channel. |
hidden_status | object | Specifies one or more key-value pair items which set the channel's hidden status for each user. |
operator_ids[] | array of strings | Specifies an array of one or more IDs of users to register as operators of the channel. You should also include these IDs in the |
block_sdk_user_channel_join | boolean | Determines whether to block users from joining the channel through the Chat SDK. If set to |
Responses
If successful, this action returns a group channel resource in the response body.
Note : The
role
property in each user resource under themember
property indicates whether the user is a channel operator or a channel member.
Error
In the case of an error, an error object like below is returned. See the error codes section for more details.
Supergroup channel
Creating a Supergroup channel follows the same approach as creating a group channel with the is_super
property as the only exception. The is_super
property needs to be set to true
in order to convert a group channel to a Supergroup channel. A Supergroup channel can't be converted to a group channel but a group channel can be converted to a Supergroup channel by changing a value of the is_super
property to true
. Once a group channel has been converted to a Supergroup channel, it can't be switched back to a group channel. Some features aren't supported for Supergroup channels. For more information, see Supergroup channel's limitations.
Request body
The following table lists the properties of an HTTP request that this action supports.
Required
Property name | Type | Description |
---|---|---|
is_super | boolean | Determines whether to create a Supergroup channel. (Default: |
Responses
If successful, this action returns a Supergroup channel resource in the response body.
Error
In the case of an error, an error object like below is returned. See the error codes section for more details.