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

    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
    RequiredTypeDescription

    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.

    OptionalTypeDescription

    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)

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

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

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

    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)

    * Supergroup channels are not supported with the is_distinct property and the property is set to 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"]
    }
    

    Responses

    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": 1530232801201,
                "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"
                }
            }
        ]
    }
    

    Error

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

    {
        "message": "\"is_super\" must be a boolean.",
        "code": 400104,
        "error": true
    }