List group channels

This action retrieves a list of group channels. You can use various query parameters to determine the search scope and select what kind of information you want to receive about the queried channels.

If you want to retrieve a list of group channels that a specific user has joined, use the list group channels by user action under the User section.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Optional

Parameter name	Type	Description
token	string	Specifies a page token that indicates the starting index of a chunk of results. If not specified, the index is set as 0.
limit	integer	Specifies the number of results to return per page. Acceptable values are `1` to `100`, inclusive. (Default: `10`)
distinct_mode	string	Restricts the search scope to only retrieve distinct or nondistinct group channels. Acceptable values are the following: - `all` (default): All group channels are returned. - `distinct`: Only distinct group channels are returned. - `nondistinct`: Only group channels that aren't distinct are returned.
public_mode	string	Restricts the search scope to only retrieve either public or private group channels. Acceptable values are the following: - `all` (default): All group channels are returned. - `private`: All private group channels are returned. - `public`: All public group channels are returned.
super_mode	string	Specifies which type of group channels to retrieve. Acceptable values are the following: - `all` (default): All types of group channels including Supergroup channels are returned. - `super`: Only Supergroup channels are returned. - `nonsuper`: Group channels excluding Supergroup channels are returned.
created_after	long	Restricts the search scope to only retrieve group channels which have been created after the specified time, in Unix milliseconds format.
created_before	long	Restricts the search scope to only retrieve group channels which have been created before the specified time, in Unix milliseconds format.
show_empty	boolean	Determines whether to include empty channels in the response. Empty channels are channels that have been created but that don't have any messages. If set to `true`, empty channels are included in the response. (Default: `true`)
show_member	boolean	Determines whether to include information about the members of each channel in the response. (Default: `false`)
show_delivery_receipt	boolean	Determines whether to include information about the delivery receipts of each channel in the response. The delivery receipt indicates the timestamp of when each member has last received messages from the Sendbird server in the channel, in Unix milliseconds. (Default: `false`)
show_read_receipt	boolean	Determines whether to include information about the read receipts of each channel in the response. The read receipt indicates the timestamp of when each member has last read the messages in the channel, in Unix milliseconds. (Default: `false`)
show_metadata	boolean	Determines whether to include channel metadata in the response. (Default: `false`)
show_frozen	boolean	Determines whether to include frozen channels in the response. Frozen channels are channels where only operators are allowed to send messages. (Default: `true`)
order	string	Specifies the method to sort a list of results. Acceptable values are the following: - `chronological` (default): sorts by time of channel creation, from most to least recent. - `latest_last_message`: sorts by the time of the last message in the channel, from most to least recent. This is available only when `user_id` is specified. - `channel_name_alphabetical`: sorts by channel name in alphabetical order. - `metadata_value_alphabetical`: sorts by a value of metadata in alphabetical order. This is available only when the `metadata_order_key` parameter is specified.
metadata_order_key	string	Specifies the key of an item in metadata. When a value of the `order` parameter is set to `metadata_value_alphabetical`, the results are alphabetically sorted by the value of the item specified by the key.
custom_types	string	Specifies a comma-separated string of one or more custom types to filter group channels. URL encoding each type is recommended. If not specified, all channels are returned, regardless of their custom type.
custom_type_startswith	string	Searches for group channels with the custom type which starts with the specified value. URL encoding the value is recommended.
channel_urls	string	Specifies a comma-separated string of one or more group channel URLs to restrict the search scope. URL encoding each channel URL is recommended.
name	string	Specifies one or more group channel names.
name_contains	string	Searches for group channels whose names contain the specified value. Note that this parameter is case-insensitive. URL encoding the value is recommended.
name_startswith	string	Searches for group channels whose names start with the specified value. Note that this parameter is case-insensitive. URL encoding the value is recommended.
members_exactly_in	string	Searches for group channels with all the specified users as members. The parameter value should consist of user IDs separated by commas. Only user IDs that match those of existing users are used for channel search. URL encoding each ID is recommended.
members_include_in	string	Searches for group channels that include one or more users as members among the specified users. The value should consist of user IDs separated by commas or `%2C`. You can specify up to 60 user IDs. Only user IDs that match those of existing users are used for channel search. URL encoding each ID is recommended.
query_type	string	Specifies a logical condition applied to the `members_include_in` parameter. Acceptable values are either `AND` or `OR`. For example, if you specify three members, A, B, and C, in `members_include_in`, the value of `AND` returns all channels that include every one of {A. B, C} as members. The value of `OR` returns channels that include {A}, plus those that include {B}, plus those that include {C}. (Default: `AND`)
members_nickname	string	Searches for group channels with members whose nicknames match the specified value. URL encoding the value is recommended.
members_nickname_contains	string	Searches for group channels with members whose nicknames contain the specified value. Note that this parameter is case-insensitive. URL encoding the value is recommended. * We recommend using at least three characters for the parameter value for better search efficiency when you design and implement related features. If you would like to allow one or two characters for searching, use `members_nickname` instead to prevent performance issues.
metadata_key	string	Searches for group channels with metadata containing an item with the specified value as its key. To use this parameter, either the `metadata_values` parameter or the `metadata_value_startswith` parameter should be specified.
metadata_values	string	Searches for group channels with metadata containing an item with the key specified by the `metadata_key` parameter, and the value of that item matches one or more values specified by this parameter. The string should be specified with multiple values separated by commas. URL encoding each value is recommended. To use this parameter, the `metadata_key` parameter should be specified.
metadata_value_startswith	string	Searches for group channels with metadata containing an item with the key specified by the `metadata_key` parameter, and the values of that item that start with the specified value of this parameter. URL encoding the value is recommended. To use this parameter, the `metadata_key` parameter should be specified.
metacounter_key	string	Searches for group channels with metacounter containing an item with the specified value as its key. To use this parameter, either the `metacounter_values` parameter or one of the `metacounter_value_gt`, `metacounter_value_gte`, `metacounter_value_lt`, and `metacounter_value_lte` parameters should be specified.
metacounter_values	string	Searches for group channels with metacounter containing an item with the key specified by the `metadata_key` parameter, where the value of that item is equal to one or more values specified by this parameter. The string should be specified with multiple values separated by commas. To use this parameter, the `metacounter_key` parameter should be specified.
metacounter_value_gt	string	Searches for group channels with metacounter containing an item with the key specified by the `metadata_key` parameter, where the value of that item is greater than the value specified by this parameter. To use this parameter, the `metacounter_key` parameter should be specified.
metacounter_value_gte	string	Searches for group channels with metacounter containing an item with the key specified by the `metadata_key` parameter, where the value of that item is greater than or equal to the value specified by this parameter. To use this parameter, the `metacounter_key` parameter should be specified.
metacounter_value_lt	string	Searches for group channels with metacounter containing an item with the key specified by the `metadata_key` parameter, where the value of that item is lower than the value specified by this parameter. To use this parameter, the `metacounter_key` parameter should be specified.
metacounter_value_lte	string	Searches for group channels with metacounter containing an item with the key specified by the `metadata_key` parameter, where the value of that item is lower than or equal to the value specified by this parameter. To use this parameter, the `metacounter_key` parameter should be specified.
include_sorted_metaarray_in_last_message	boolean	Determines whether to include the `sorted_metaarray` as one of the `last_message`’s properties in the response.
~~custom_type~~	string	*(Deprecated)* Returns channels whose `custom_type` matches the given value. If this field is not specified, all channels are returned, regardless of their custom type. The string passed here must be urlencoded.
~~read_receipt~~	boolean	*(Deprecated)* Superseded by `show_read_receipt`.
~~member~~	boolean	*(Deprecated)* Superseded by `show_member`.
~~is_distinct~~	boolean	*(Deprecated)* Superseded by `distinct_mode`.
~~members_in~~	string	*(Deprecated)* Superseded by `members_exactly_in`.
~~user_id~~	string	*(Deprecated)* Restricts the search scope to only retrieve the target user's group channels. It's recommended to use the list group channels by user action instead.

Query string example

?limit=5&order=latest_last_message&show_member=true&show_delivery_receipt=true&show_read_receipt=true&members_include_in=Jay&query_type=AND

Responses

If successful, in the response body, this action returns a list of group channel resources.

Status: 200 OK

{
    "channels": [
        {
            "is_distinct": true,
            "is_public": false,
            "is_super": false,
            "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": {
                        "font_preference": "times new roman",
                        "font_color": "black"
                    }
                },
                ... # 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": {
                        "font_preference": "times new roman",
                        "font_color": "black"
                    }
                },
                "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": {
                    "font_preference": "times new roman",
                    "font_color": "black"
                }
            },
            "unread_message_count": 0,
            "unread_mention_count": 0,
            "metadata": {
                "background_image": "https://sendbird.com/main/img/bg/theme_013.png",
                "text_size": "large"
            },
            "channel": {
                ... # This key has been deprecated and only exists for backward compatibility.
            }
        },
        ... # More group channels
    ],
    "next": "ansYQFFRQ1AIEUBXX1RcE2d0FUZSUlkJFVQRHB86AkAgNn8eABABBBNFX11fUlsWYnMS"
}

List of response properties

Property name	Type	Description
channels[]	array of objects	An array of group channel objects that match the specified optional parameters.
next	string	The value for the `token` parameter to retrieve the next page in the result.

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": "\"User\" not found.",
    "code": 400201,
    "error": true
}

Supergroup channels

To only retrieve Supergroup channels, you can use the same the list group channels action but set the super_mode parameter to super.

You can also see whether a returned channel object is a Supergroup channel by checking that the is_super response property has a value of true.

HTTP request

GET https:/api-{application_id}.sendbird.com/v3/group_channels?super_mode=super

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
super_mode	string	Specifies which type of group channels to retrieve. Acceptable values are the following: - `all` (default): retrieves all types of group channels including Supergroup channels. - `super`: retrieves only Supergroup channels. - `nonsuper`: retrieves group channels excluding Supergroup channels.

Responses

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

Status: 200 OK

{
    "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": {
                "font_preference": "times new roman",
                "font_color": "black"
            }
        },
        ... # 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": {
                "font_preference": "times new roman",
                "font_color": "black"
            }
        },
        "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": {
            "font_preference": "times new roman",
            "font_color": "black"
        }
    },
    "unread_message_count": 0,
    "unread_mention_count": 0,
    "channel": {
        ... # This key has been deprecated and only exists for backward compatibility.
    }
}

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": "\"User\" not found.",
    "code": 400201,
    "error": true
}

On this page

HTTP request Parameters Responses

Error

Supergroup channels

HTTP request Parameters Responses