List group channels by user

This action retrieves a list of group channels that a specific user has joined. 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're looking to retrieve a list of group channels in a specific application, visit the list group channels page under the Channel section.

HTTP request

GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/my_group_channels

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
user_id	string	Specifies the unique ID of the user.

Optional	Type	Description
token	string	Specifies a page token that indicates the starting index of results to retrieve. If not specified, the index is set to `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 `all`, `distinct`, and `nondistinct`. (Default: `all`)
public_mode	string	Restricts the search scope to only retrieve public or private group channels. Acceptable values are `all`, `public`, and `private`. (Default: `all`)
super_mode	string	Restricts the search scope to only retrieve super or nonsuper group channels. Acceptable values are `all`, `super`, and `nonsuper`. (Default: `all`)
hidden_mode	string	Restricts the search scope to group channels that match a specific `hidden_status` and operating behavior. Acceptable values are the following: - `unhidden_only` (default): Specifies channels which the target user joined with the `unhidden` status. - `hidden_only`: Specifies all channels which the target user joined with either the `hidden_allow_auto_unhide` or `hidden_prevent_auto_unhide` status. - `hidden_allow_auto_unhide`: Specifies channels which the target user joined with the `hidden_allow_auto_unhide` status. - `hidden_prevent_auto_unhide`: Specifies channels which the target user joined with the `hidden_prevent_auto_unhide` status. - `all`: Specifies all channels regardless of their `hidden_status`.
member_state_filter	string	Restricts the search scope to retrieve group channels based on whether the user has accepted an invitation and whether the user has been invited by a friend. Acceptable values are `all`, `invited_only`, `joined_only`, `invited_by_friend`, and `invited_by_non_friend`. The values `invited_by_friend` and `invited_by_non_friend` indicate that the user has been invited but hasn't joined the channel yet. (Default: `all`)
unread_filter	string	Restricts the search scope to only retrieve group channels with one or more unread messages. This filter doesn't support Supergroup channels. Acceptable values are `all` and `unread_message`. (Default: `all`)
created_after	long	Restricts the search scope to only retrieve group channels that have been created after the specified time in Unix milliseconds format.
created_before	long	Restricts the search scope to only retrieve group channels that 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 contain no messages. (Default: `false`)
show_frozen	boolean	Determines whether to include frozen channels in the response. In frozen channels, only operators are allowed to send messages. (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 the messages from Sendbird server, 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 user has last read the messages in the channel, in Unix milliseconds. (Default: `false`)
order	string	Specifies the method to sort a list of results. Acceptable values are the following: - `chronological` (default): sorts the results in a descending order of when the channel was created. - `latest_last_message`: sorts the results in a descending order of when the last message in the channel was sent and received. - `channel_name_alphabetical`: sorts the results in an alphabetical order of the channel names. - `metadata_value_alphabetical`: sorts the results in an alphabetical order of the value of metadata. The value of `order` should be set to `metadata_value_alphabetical` in order to use the `metadata_order_key` parameter.
metadata_order_key	string	Specifies the key of an item in metadata. This is effective only when the `order` parameter is set to `metadata_value_alphabetical`.
custom_types	string	Specifies a comma-separated string of one or more custom types to filter the user's 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 a custom type that starts with the specified string. URL encoding the value is recommended.
channel_urls	string	Specifies a comma-separated string of one or more group channel URLs to search for. URL encoding each channel URL is recommended.
name	string	Specifies the name of group channels.
name_contains	string	Searches for group channels that contain the specified string in their names. This parameter isn't case-sensitive. URL encoding the value is recommended.
name_startswith	string	Searches for group channels that have names that begin with the specified string. URL encoding the value is recommended.
members_exactly_in	string	Searches for group channels that contain the exact members specified in a comma-separated string of URL encoded user IDs.
members_include_in	string	Searches for group channels that contain one or more members specified in a comma-separated string of URL encoded user IDs.
query_type	string	Specifies a logical operator applied to the `members_include_in` filter. This parameter isn't case-sensitive. Acceptable values are `AND` and `OR`. For example, if you specify three members, A, B, and C, in `members_include_in` above, the value `AND` returns all channels that include all of {A, B, C} as a subset. The value `OR` returns channels that include {A}, those that include {B}, and those that include {C}. (Default: `AND`)
members_nickname	string	Searches for group channels with members whose nicknames match the specified string. URL encoding the value is recommended.
members_nickname_startswith	string	Searches for group channels with members whose nicknames begin with the specified value. This parameter isn't case-sensitive. URL encoding the value is recommended.
members_nickname_contains	string	Searches for group channels with members whose nicknames contain the specified value. This parameter isn't case-sensitive. URL encoding the value is recommended. When you design and implement related features, we recommend that the parameter value has at least three characters for better search efficiency. If you would like to allow one or two characters for searching, use `members_nickname` instead to prevent performance issues. * To reduce latency and database load issues, it's best to use `members_nickname` or `members_nickname_startswith` over `members_nickname_contains`.
search_query	string	Searches for group channels where the specified query string matches the channel name or the nickname of the member. This parameter isn't case-sensitive and should be specified in conjunction with the `search_fields` parameter below. URL encoding the value is recommended.
search_fields	string	Specifies a comma-separated string of one or more search fields to apply to the query, which restricts the results within the specified fields (`OR` search condition). Acceptable values are `channel_name` and `member_nickname`. This is effective only when the `search_query` parameter above is specified. (Default: `channel_name`, `member_nickname` together)
metadata_key	string	Searches for group channels with metadata containing an item with the specified string as its key. This parameter should be specified in conjunction with the `metadata_values` or `metadata_value_startswith` parameters below.
metadata_values	string	Searches for group channels with metadata containing an item with the key specified by the `metadata_key` parameter above. The value of `metadata_key` must also match one or more values specified in this parameter. The string should be specified with multiple URL encoded values separated by commas. An example of a URL encoded string is `?metadata_values=urlencoded_value_1, urlencoded_value_2`. This parameter should be specified in conjunction with the `metadata_key` parameter above.
metadata_value_startswith	string	Searches for group channels with metadata containing an item with the key specified by the `metadata_key`parameter above. The value of `metadata_key` must also start with the specified string by this parameter. URL encoding the value is recommended. This parameter should be specified in conjunction with `metadata_key` above.
metacounter_key	string	Searches for group channels with metacounter containing an item with the specified string as its key. This parameter should be specified in conjunction with the `metacounter_values` or one of the following: `metacounter_value_gt`, `metacounter_value_gte`, `metacounter_value_lt`, and `metacounter_value_lte`.
metacounter_values	string	Searches for group channels with metacounter containing an item with the key specified by the `metadata_key` parameter above. The value of `metadata_key` must be equal to one or more values specified by this parameter. The string should be specified with multiple values separated by commas. This parameter should be specified in conjunction with the `metacounter_key` above.
metacounter_value_gt	string	Searches for group channels with metacounter containing an item with the key specified by the `metadata_key` parameter above. The value of `metadata_key` must be greater than the string specified by this parameter. This parameter should be specified in conjunction with the `metacounter_key` above.
metacounter_value_gte	string	Searches for group channels with metacounter containing an item with the key specified by the `metadata_key` parameter above. The value of `metadata_key` must be greater than or equal to the string specified by this parameter. This parameter should be specified in conjunction with the `metacounter_key` above.
metacounter_value_lt	string	Searches for group channels with metacounter containing an item with the key specified by the `metadata_key` parameter above. The value of `metadata_key` must be lower than the string specified by this parameter. This parameter should be specified in conjunction with the `metacounter_key` above.
metacounter_value_lte	string	Searches for group channels with metacounter containing an item with the key specified by the `metadata_key` parameter above. The value of `metadata_key` must be lower than or equal to the string specified by this parameter. This parameter should be specified in conjunction with the `metacounter_key` above.
~~custom_type~~	string	*(Deprecated)* Searches for channels with the specified `custom_type`. If this field is not specified, all channels are returned, regardless of their custom type. The string passed here must be URL encoded.

Query string example

?limit=2&order=latest_last_message&show_member=true&show_delivery_receipt=true&show_read_receipt=true&members_include_in=Jeff&query_type=AND

Responses

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

Status: 200 OK

{
    "channels": [
        {
            "is_distinct": true,
            "is_public": false,
            "is_super": false,
            "is_ephemeral": false,
            "is_hidden": false,
            "is_push_enabled": true,        # Indicates whether the specified user turns on the push notification for the channel.
            "is_access_code_required": false,
            "freeze": false,
            "max_length_message": -1,
            "custom_type": "colleagues",
            "name": "Push notification improvement",
            "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
            "created_at": 1484182653,
            "cover_url": "https://sendbird.com/main/img/cover/cover_08.jpg",
            "data": "{u'background_color': u'blue', u'description': u'product enhancing'}",
            "member_count": 3,
            "joined_member_count": 3,
            "members": [
                {
                    "user_id": "Jeff",
                    "nickname": "OldBoy",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_29_512px.png",
                    "state": "joined",
                    "is_active": true,
                    "is_online": false,
                    "friend_name": "Geunhui",
                    "friend_discovery_key": ["345-678-9012", "010-1234-5678"],
                    "is_blocked_by_me": false,
                    "is_blocking_me": false,
                    "last_seen_at": 1542762639292,
                    "metadata": {
                        "font_preference": "times new roman",
                        "font_color": "black"
                    }
                },
                ...     # More members
            ],
            "delivery_receipt": {
                "Jeff": 1542762344162,
                "Craig": 1542543464371,
                "Jin": 1542394323413
            },
            "read_receipt": {
                "Jeff": 1542762343245,
                "Craig": 1542756098734,
                "Jin": 1542756034123
            },
            "last_message": {
                "message_id": 640904364,
                "type": "MESG",
                "custom_type": "",
                "mention_type": "users",
                "mentioned_users": [],
                "created_at": 1484269498708,
                "updated_at": 0,
                "is_removed": false,
                "channel_url": "sendbird_group_channel_24901438_c1bc35f5f0d237207bc1cba27351c878fc2f345b",
                "user": {
                    "user_id": "Craig",
                    "nickname": "Shopperholic",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_17_512px.png",
                    "is_blocked_by_me": false,
                    "metadata": {
                        "font_preference": "times new roman",
                        "font_color": "black"
                    }
                },
                "message": "Can you share the plan with me?",
                "translations": {},
                "data": ""
            },
            "invited_at": 1542732195580,
            "inviter": {
                "user_id": "Jeff",
                "nickname": "OldBoy",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_29_512px.png",
                "metadata": {
                    "font_preference": "times new roman",
                    "font_color": "black"
                }
            },
            "hidden_state": "unhidden",     // One of 'unhidden', 'hidden_allow_auto_unhide', and 'hidden_prevent_auto_unhide'
            "member_state": "joined",
            "my_role": "",
            "is_muted": false,
            "count_preference": "all",
            "unread_message_count": 1,
            "unread_mention_count": 0,
            "channel": {
                ... # This key has been deprecated and only exists for backward compatibility.
            }
        },
        ...     # More group channels
    ],
    "next": "ansYQFFRQ1AIEUBXX1RcE2d0FUZSUlkJFVQRHB86AkAgNn8eABABBBNFX11fUlsWYnMS"
}

List of response properties

Name	Type	Description
channels[]	array of objects	An array of group channels associated with the user.
next	string	The value that can be used in the `token` parameter to retrieve the next page in the result set.

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