Platform API
Supergroup Channel

Supergroup Channel

A Supergroup channel is an expanded version of a group channel, which can accommodate more than 2,000 members while serving most of the functions of a group channel. The maximum number of channel members can stretch up to 20,000 depending on your Sendbird plan. Because a Supergroup channel is built upon the same foundation as a group channel, Platform APIs and SDK functions for both channel types are identical.

Note: Supergroup and group channels are alike in terms of Platform API and SDK design, except for the is_super. The is_super property indicates whether the channel is a Supergroup channel or a group channel.


Use cases

Supergroup channels can be used for a wide range of occasions that demand real-time engagement among a large number of users. One of the common use cases for Supergroup channels is community building, ranging from public forums to private events with a large membership.

  • Consultation: Supergroup channels also work as a platform for users to seek advice from an influencer or expert.
  • Gaming community: Another common set-up is gaming communities, where users gather to find players to team up with or exchange ideas and strategies to advance further in the game.

Limitations

To secure stable operation and optimized user experience of a Supergroup channel, a few functions are subject to limits. Some of those limitations include:

  • Visual interactions: read and delivery receipts aren’t supported in Supergroup channels to provide an optimal performance in Supergroup channels.
  • Unread counts: unread counts are marked up to 100 only. In the case they surpass 100, we suggest you display the counts as 99+ to avoid confusion.
  • Push notifications: The way push notifications for Supergroup channels work is determined by two factors: the number of members in a channel and the online status of its member.
    • When there are less than 100 members: A push notification will be sent for every message created in the channel.
    • When there are 100 members or more: A ten-minute time window will be applied to Supergroup channels with more than 100 members. Once the number of members exceeds 100 and a new message is created, a push notification will be sent for the new message and then the next push notification can come ten minutes after that.
      For example, the number of members in Channel A surpasses 100 at 13:00 and then a new message is sent at 13:01, a push notification will be sent for the 13:01 message and the ten-minute time window begins. For the following ten minutes, there will be no push notifications for any messages created within the time frame. When ten minutes pass and another message is sent at 13:11, the second push notification will be made for that message.
    • When a user becomes active: If one of the Supergroup channel members enters the channel and reads a message, the user will be recognized as active. Then only for the following one minute, the user will be receiving push notifications for all messages sent within the time frame.

Open channel vs. Group channel vs. Supergroup channel

The following table compares the difference among three types of channels that can accommodate a large number of users: Open channels, Group channels, and Supergroup channels.

Open channelGroup channelSupergroup channel

Maximum number in a channel

*The maximum number can be adjusted depending on use cases. Contact our sales team.

1,000 participants

100 members

2,000 and more members

* The number varies depending on your Sendbird plan.

Accessible by

Anyone within the application

Invited users only if private or anyone if public

Invited users only if private or anyone if public

Ephemeral messaging

Supported

Supported

Supported

Add users as friends

N/A

Supported

Supported

Online presence

Supported

Supported

Supported

Last message

N/A

Supported

Supported

UIKit

N/A

Supported

Supported

Operators

Supported

Supported

Supported

Ban users

Supported

Supported

Supported

Mute users

Supported

Supported

Supported

Freeze channels

Supported

Supported

Supported

Delivery receipts

N/A

Supported

N/A

Read receipts

N/A

Supported

N/A

Unread counts

N/A

Supported

Supported

* Up to 100 unread counts are supported.

Typing indicators

N/A

Supported

Supported

* Up to 3 concurrent indicators are supported.

Mention others in message

Supported

Supported

Supported

Mention counts

N/A

Supported

Supported

Reactions

N/A

Supported

Supported

Spam flood protection

Supported

Supported

Supported

Chatbot interface

Supported

Supported

Supported

Smart throttling

Supported (Default: true)

Supported (Default: false)

Supported (Default: false)

Push notifications

N/A

* Push notifications for announcements only.

Supported

* Push notifications for every message sent.

Supported

* Refer to Limitations.

View a channel with its participant list or member list

N/A

Supported

Supported

* Only ten members are retrieved as a preview.
To get an entire list of members, use the list members API instead.

Pagination for participant list or member list

Supported

Supported

Supported

Order of channel list

- Chronological

- Chronological
- Latest last message
- Channel name
- Metadata value

- Chronological
- Latest last message
- Channel name
- Metadata value


Resource representation

The properties of a Supergroup channel are much the same as those of a group channel, except for the is_super property. Refer to the Group Channel's Resource representation section for the properties Supergroup and group channels share.

Property nameTypeDescription

is_super

boolean

Indicates whether a group channel is a Supergroup channel or not.

* This parameter has to be set to true to create a Supergroup channel.

Note: Because Supergroup channels can't be distinct channels, the is_distinct property must set to false. If not specified, the default will be false.

Actions

  • API endpoints are relative to the base URL allocated to the application. The /group_channels endpoint in this page refers to https://api-{application_id}.sendbird.com/v3/group_channels.

Note: Other than setting the is_super property to true when creating a Supergroup channel, the rest of the operations of Supergroup channels are the same as group channels. The shared actions for Supergroup and group channels can be found in the Group Channel's Actions section.

ActionHTTP request

List Supergroup channels

GET /group_channels?super_mode=true
Retrieves a list of Supergroup channels in the application.

Create a Supergroup channel

POST /group_channels
Creates a Supergroup channel.


List Supergroup channels

Similar to creating a group channel, you can use the List channels action and see if the returned Channel object has a value of true for the is_super property. Or, you can specify the super_mode property to filter and list a certain type of channels.

HTTP request

Light Color Skin
Copy
GET https://api-{application_id}.sendbird.com/v3/group_channels?super_mode=true

Parameters

The following table lists the parameters that this action supports.

ParameterTypeDescription

super_mode

string

Specifies which type of group channels to retrieve. Acceptable values are all, super, nonsuper. (Default: all)

- all: retrieves both group channels and Supergroup channels.
- super: retrieves Supergroup channels only.
- nonsuper: retrieves group channels only.

Response

If successful, this action returns a group channel resource including a property that indicates whether the channel is a Supergroup or not in the response body.

Status: 200 OK
Light Color Skin
Copy
{
    "is_distinct": false,
    "is_public": false,
    "is_super": true, 
    "is_ephemeral": false,
    "is_access_code_required": false,
    "freeze": false,
    "max_length_message": 500,
    "custom_type": "schedule_on_progress",
    "name": "On the upcoming AWS event",
    "channel_url": "sendbird_group_channel_25108471_a1bc35f5f0d237207bc1rd343562c878fc2fd426",
    "created_at": 1484185346,
    "created_by": {
        "user_id": "Jin",
        "nickname": "JinJin",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_09_512px.png",
        "require_auth_for_profile_image": false
    },  
    "cover_url": "https://sendbird.com/main/img/cover/cover_43.jpg",
    "data": "{u'background_color': u'yellow', u'description': u'preparing presentation'}",
    "member_count": 3,
    "joined_member_count": 3,
    "members": [
        {
            "user_id": "Jay",
            "nickname": "Rooster",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_13_512px.png",
            "is_active": true,
            "is_online": false,
            "last_seen_at": 1542762346134,
            "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"
            }
        },
        ... # More members  
    ],
    "delivery_receipt": {
        "Jay": 1542762344162,
        "Jin": 1542394323413,
        "David": 1542543464371
    },
    "read_receipt": {
        "Jay": 1542762343245,
        "Jin": 1542394301402,
        "David": 1542543456343
    },
    "last_message": {
        "message_id": 640903435,
        "type": "MESG",
        "custom_type": "",
        "mention_type": "users",
        "mentioned_users": [],
        "created_at": 1542762343245,
        "updated_at": 0,
        "is_removed": false,
        "channel_url": "sendbird_group_channel_25108471_a1bc35f5f0d237207bc1rd343562c878fc2fd426",
        "user": {
            "user_id": "Jay",
            "nickname": "Rooster",
            "profile_url": "https://sendbird.com/main/img/profiles/profile_13_512px.png"
            "metadata": {
                "location": "New York",
                "marriage": "Y"
            }
        },
        "message": "Can you please make the presentation for me?",
        "translations": {},
        "data": "",
        "file": {}
    },
    "invited_at": 1542132194342,
    "inviter": {
        "user_id": "Jin",
        "nickname": "JinJin",
        "profile_url": "https://sendbird.com/main/img/profiles/profile_09_512px.png",
        "metadata": {
            "location": "San Francisco",
            "marriage": "Y"
        }
    },
    "unread_message_count": 0,
    "unread_mention_count": 0,
    "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 an exception of the is_super property. The is_super property needs to be set to true in order to turn a group channel into a Supergroup channel.

HTTP request

Light Color Skin
Copy
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.

Property nameTypeDescription

is_super

boolean

Determines whether to create a Supergroup channel. This property is required when creating a Supergroup channel. (Default: false)

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

Light Color Skin
Copy
{
    "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.

Light Color Skin
Copy
{
    "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/rofile_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": 1530232801201,
            "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"
            }
        }
    ],
    "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"
            }
        }
    ]
}