/ Platform API
Platform API
    Chat Platform API v3
    Chat Platform API
    Chat Platform API
    Version 3

    List group channels by user

    Copy link

    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

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

    Parameters

    Copy link

    The following table lists the parameters that this action supports.

    Parameters
    RequiredTypeDescription

    user_id

    string

    Specifies the unique ID of the user.

    OptionalTypeDescription

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

    ?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

    Copy link

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

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

    Copy link
    NameTypeDescription

    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.

    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
    }