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

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

    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

    int

    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: false)

    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 metatdata_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. Urlencoding each type is recommended (for example, ?custom_types=urlencoded_type_1,urlencoded_type_2). 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. Urlencoding the value is recommended.

    channel_urls

    string

    Specifies a comma-separated string of one or more group channel URLs to restrict the search scope. Urlencoding each channel URL is recommended (for example, ?channel_urls=urlencoded_url_1, urlencoded_url_2).

    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. Urlencoding 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. Urlencoding 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 multiple user IDs separated by commas. Only user IDs that match those of existing users are used for channel search. Urlencoding each ID is recommended (for example, ?members_exactly_in=urlencoded_user_id_1, urlencoded_user_id_2).

    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 multiple user IDs separated by commas. Only user IDs that match those of existing users are used for channel search. Urlencoding each ID is recommended (for example, members_include_in= urlencoded_user_id_1, urlencoded_user_id_2).

    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. Urlencoding 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. Urlencoding 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. Urlencoding each value is recommended (for example, ?metadata_values=urlencoded_value_1, urlencoded_value_2). 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. Urlencoding 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 action instead.

    ?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.

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

    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.

    {
        "message": "\"User\" not found.",
        "code": 400201,
        "error": true
    }
    

    List Supergroup channels

    To only retrieve Supergroup channels, you can use the same 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 nameTypeDescription

    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.

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

    Error

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

    {
        "message": "\"User\" not found.",
        "code": 400201,
        "error": true
    }