Create a group channel

Creates a new group channel.

Note: See this page to learn more about channel types.

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.

Note: If you are creating a 1-on-1 direct messaging channel, it is recommended that you set the value of is_distinct to true. If is_distinct is set to true, no new channel is created for a group of users with shared chat history, and every 1-on-1 conversation between the same two users will continue in the existing channel. However, if is_distinct is set to false, a new channel is created even for a group of users with shared chat history and previous conversations between these users will not carry over to the new channel.

Properties

Required	Type	Description
users[]	array of strings	Specifies an array of one or more IDs of users to invite to the channel, which can be used interchangeably with `user_ids`. Up to 100 users can be invited at a time.

Optional	Type	Description
user_ids[]	array of strings	Specifies an array of one or more IDs of users to invite to the channel, which can be used interchangeably with `user`. Up to 100 users can be invited at a time.
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, characters, and underscores are allowed. The 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. The length is limited to 2,048 characters.
cover_file	file	Uploads an image file of your choice to be used as the channel's cover image.
custom_type	string	Specifies the custom channel type which is used for channel grouping. The length is limited to 128 characters. * Custom types are also used within Sendbird's Advanced analytics to segment metrics as channel metrics can be grouped by channel custom type.
data	string	Specifies additional channel information such as a long description of the channel or `JSON` formatted string.
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. If set to true, returns a channel with the same users in the `user_ids` or `users` property or creates a new channel if no such channel exists. A potential use case is a 1-on-1 direct messaging channel where setting the `is_distinct` property to true ensures that conversation between the same users takes place in the same channel. (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 the Sendbird Dashboard.
is_public	boolean	Determines whether to allow users to join the channel without an invitation. If set to true, users can join without an invitation. (Default: false)
is_super	boolean	Determines whether to allow the channel to accommodate 100 or more members. If set to true, creates a Supergroup channel. (Default: false) * Supergroup channels are not supported with the `is_distinct` property and the `is_distinct` property is set to false by default.
is_ephemeral	boolean	Determines whether to preserve messages in the channel for the purpose of retrieving chat history. If set to true, messages in the channel are not preserved. (Default: false)
access_code	string	Specifies the access code that is only applicable to public group channels. If specified, the `is_access_code_required` property is set to true. Access code can be set by channel operators on the Sendbird Dashboard or through Platform API. A user is required to enter the specified access code to join the channel.
inviter_id	string	Specifies the ID of the 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. If set to false, the channel will be created excluding the users that don't exist without receiving this error. (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. Each key-value pair should be specified with the ID of invited user, a colon (:), and the user’s invitation status (for example, *user_id_1: invitation 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 value in `hidden_status` determines whether to hide the channel from the user's channel list. Each key-value pair should be specified with the ID of invited user, a colon (:), and the channel's hidden status (for example, *user_id_1: channel hidden status). Acceptable values are the following: - 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 on a user's channel list. - hidden_prevent_auto_unhide*: even when 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 can 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 join a channel API. (Default: false)

Note: If you want to upload a profile picture by passing an image file instead of a URL, see Multipart requests.

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"]
}

Response

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,
    "hidden_state": "hidden_allow_auto_unhide", // This shows the channel hidden status of the inviter.
    "member_count": 3,
    "joined_member_count": 1,
    "members": [
        {
            "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 null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "location": "New York",
                "marriage": "Y"
            }
        },
        {
            "user_id": "James",
            "nickname": "Knight",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_08_512px.png",
            "is_active": true,
            "is_online": false,
            "friend_discovery_key": ["789-012-7834", "010-1245-3658"],
            "last_seen_at": 1530237133254,
            "state": "invited",     // 'invited_by_friend'
            "role": "",             // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "location": "Tokyo",
                "marriage": "N"
            }
        },
        {
            "user_id": "Young",
            "nickname": "Sportsman",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_23_512px.png",
            "is_active": true,
            "is_online": true,
            "friend_discovery_key": ["357-642-1369", "010-4030-1357"],
            "last_seen_at": 0,
            "state": "invited",     // 'invited_by_non_friend'
            "role": "",             // Either 'operator' or null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "location": "Chicago",
                "marriage": "N"
            }
        }
    ],
    "operators": [
        {
            "user_id": "Jeff",
            "nickname": "OldBoy",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_22_512px.png",
            "metadata": {
                "location": "Seoul",
                "marriage": "Y"
            }
        }
    ],
    "max_length_message": 500,
    "last_message": null,
    "created_at": 1543468122,
    "freeze": false,
    "channel": {
        ...  # This key has been deprecated and only exists for backward compatibility.
    }
}

Create a 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 is_super to true. Once a group channel has been converted to a Supergroup channel, it can't be switched back to a group channel.

Note: Some features aren't supported for Supergroup channels. For more information, see Supergroup channel's limitations.

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.

Required

Property name	Type	Description
is_super	boolean	Determines whether to create a Supergroup channel. (Default: false)

Note: Supergroup channels are not supported with the is_distinct property and the property is false by default.

{
    "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": false,
    "is_super": 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"]
}

Response

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

{
    "is_distinct": false,
    "is_public": false,
    "is_super": true,
    "is_ephemeral": false,
    "is_access_code_required": false,
    "freeze": false,
    "max_length_message": 500,
    "name": "Saturday soccer members",
    "channel_url": "private_chat_room_424",
    "cover_url": "https:/sendbird.com/main/img/cover/cover_08.jpg",
    "custom_type": "sports",
    "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"
    },
    "members": [
        {
            "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 null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "location": "New York",
                "marriage": "Y"
            }
        },
        {
            "user_id": "James",
            "nickname": "Knight",
            "profile_url": "https:/sendbird.com/main/img/profiles/profile_08_512px.png",
            "is_active": true,
            "is_online": false,
            "friend_discovery_key": ["789-012-7834", "010-1245-3658"],
            "last_seen_at": 1530237133254,
            "state": "invited",
            "role": "",             // Either operator or null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "location": "Tokyo",
                "marriage": "N"
            }
        },
        {
            "user_id": "Young",
            "nickname": "Sportsman",
            "profile_url": "https:/sendbird.com/main/img/profiles/profile_23_512px.png",
            "is_active": true,
            "is_online": true,
            "friend_discovery_key": ["357-642-1369", "010-4030-1357"],
            "last_seen_at": 0,
            "state": "invited",
            "role": "",             // Either operator or null. The value of null indicates that this user is a normal channel member.
            "metadata": {
                "location": "Chicago",
                "marriage": "N"
            }
        }
    ],
    "operator_ids": ["Jeff"],
    "operators": [
        {
            "user_id": "Jeff",
            "nickname": "OldBoy",
            "profile_url": "https:/sendbird.com/main/img/profiles/profile_22_512px.png",
            "metadata": {
                "location": "Seoul",
                "marriage": "Y"
            }
        }
    ]
}

In the case of an error, an error object is returned. A detailed list of error codes is available here.