Chat / Platform API
Current version: v3
    Chat Platform API v3
    Chat Platform API
    Chat
    Platform API
    Home
    /
    Chat
    /
    Platform API

    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
    RequiredTypeDescription

    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.

    OptionalTypeDescription

    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.

    {
        "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.

    {
        "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 nameTypeDescription

    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.