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

POST https://api-{application_id}.sendbird.com/v3/group_channels

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 `user_ids` or `users`.

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 `user_ids` or `users`.
name	string	Specifies the name of the channel, or the channel topic. The length is limited to 191 characters. (Default: `group channel`)
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. * Custom types are also used when viewing data with Sendbird's Advanced analytics, as data can be grouped by their custom type.
data	string	Additional channel information such as a long description of the channel or `JSON` formatted string. More detail on what can be stored in the data field is available here.
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_distinct` to `true`. You can also reuse channels if the new channel has the same members, and the same `custom_type`, or create an entirely new channel if there are the same members but had a different `custom_type`. (Default: `false`) * You can also use this property in conjunction with `custom_type` and `user_ids` to create distinct channels for a specified channel custom type and group of users. To enable this functionality, visit this page and contact us on Sendbird Dashboard.
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_public` to `true`. Public group channels are similar to open channels but include extra features like typing indicators and are limited to 100 members. (Default: `false`)
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. A group channel can be created as a Supergroup channel by setting `is_super` to `true`. The `is_distinct` property must be `false` in order to create a Supergroup. (Default: `false`)
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. If `is_ephemeral` is set to `true` then no chat history is stored. In this case, the chat history can't be retrieved in the future. This option may be helpful for exceptional data privacy requirements. (Default: `false`)
access_code	string	Specifies an access code that is only applicable to public group channels. If a value is specified for `access_code`, users will be required to enter this code when joining a group channel. This parameter can only be used when the channel operator creates a public group channel. If specified, the `is_access_code_required` property of the channel resource is automatically set to `true`. (Default: `false`)
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 `user_ids` property if needed.
strict	boolean	Determines whether to receive a `400111` error and cease channel creation when there is at least one user that doesn't exist in the specified `user_ids` or `users` property. Channel creation by default won't fail if a user passed to `user_ids` or `users` doesn't exist in the Sendbird application. Setting `strict` to `true` causes a `400111` error during creation if any users passed to `user_ids` or `users` haven't already been sucesfully created. (Default: `false`)
invitation_status	object	Specifies one or more key-value pair items which set the invitation status of each user invited to the channel. The key should be a `user_id` and the value should be their joining status. Acceptable values are `joined`, `invited_by_friend`, and `invited_ by_non_friend`. (Default: `joined`)
hidden_status	object	Specifies one or more key-value pair items which set the channel's hidden status for each user. The key should be a `user_id` and the value should be their hidden status. Acceptable values are: - `unhidden` (default): the channel is shown when a user's channel list is retrieved. - `hidden_allow_auto_unhide`: if a new message is sent to a hidden channel, the channel automatically reappears to a user's channel list. - `hidden_prevent_auto_unhide`: even if a new message is sent to a hidden channel, the channel remains hidden.
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 `user_ids` property to invite them to the channel as members. They can delete any messages in the channel, and also view all messages without any filtering or throttling. A channel may have up to 100 operators.
block_sdk_user_channel_join	boolean	Determines whether to block users from joining the channel through the Chat SDK. If set to `true`, users can only join the channel using the Sendbird Platform API join a channel action. (Default: `false`)

Request body example

{
    "name": "Saturday soccer members",
    "channel_url": "private_chat_room_424",
    "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
    "custom_type": "sports",
    "is_distinct": true,
    "inviter_id": "Jay",
    "user_ids": ["Jay", "James", "Young"],
    "invitation_status": {
        "James": "invited_by_friend",
        "Young": "invited_by_non_friend"
    },
    "hidden_status": {
        "Jay": "hidden_allow_auto_unhide"
    },
    "operator_ids": ["Jeff"]
}

Responses

If successful, this action returns a group channel resource in the response body.

Note : The role property in each user resource under the member property indicates whether the user is a channel operator or a channel member.

Status: 200 OK

{
    "name": "Saturday soccer members",
    "channel_url": "private_chat_room_424",
    "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
    "custom_type": "sports",
    "unread_message_count": 0,
    "data": "",
    "is_distinct": true,
    "is_public": false,
    "is_super": false,
    "is_ephemeral": false,
    "is_access_code_required": false,
    "is_broadcast": false,
    "hidden_state": "hidden_allow_auto_unhide", // This shows the channel hidden status of the inviter.
    "member_count": 3,
    "joined_member_count": 1,
    "unread_mention_count": 0,
    "last_message": null,
    "message_survival_seconds": -1,
    "sms_fallback": { "wait_seconds": -1, "exclude_user_ids": [] },
    "max_length_message": 5000,
    "created_at": 1543468122,
    "freeze": false,
    "channel": {
        ...  # This key has been deprecated and only exists for backward compatibility.
    },
    "members": [
        // Only including first member for simplicity
        {
            "user_id": "Jay",
            "nickname": "Rooster",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
            "is_active": true,
            "is_online": false,
            "friend_discovery_key": ["543-098-4567", "010-4567-6543"],
            "last_seen_at": 1530232836311,
            "state": "joined",
            "role": "",         // Either 'operator' or empty string. The value of null indicates that this user is a normal channel member.
            "metadata": {

                "myAdditionalUserField1": "abcd",
            }
        }
    ],
    "operators": [
        {
            "user_id": "Jeff",
            "nickname": "Captain",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_22_512px.png",
            "metadata": {
                "location": "Seoul",
                "marriage": "Y"
            }
        }
    ]
}

Error

In the case of an error, an error object like below is returned. See the error codes section for more details.

Status: 400 Bad Request

{
  "message":"Invalid value: \"is_distinct. If you want this value to be set \"true\", user_ids must be required.\".",
  "code":400111,
  "error":true
}

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.