SEsendbird
Group channel

List channels

Changed on

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.

https://sendbird.com/docs/chat/platform-api/v3/channel/listing-channels-in-an-application/list-group-channels#1-list-group-channels

get/v3/group_channels

Request

  • Base URL
    https://api-APP_ID.sendbird.com
  • Auth
    none declared. Required headers: api-token

Query parameters

tokenstring

Specifies a page token that indicates the starting index of a chunk of results. If not specified, the index is set as 0.

limitinteger
Example:10

Specifies the number of results to return per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

distinct_mode'all' | 'distinct' | 'nondistinct'

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.

Example:all
public_mode'all' | 'private' | 'public'

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.

Example:all
super_mode'all' | 'super' | 'nonsuper'

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.

Example:all
created_afterinteger

Restricts the search scope to only retrieve group channels which have been created after the specified time, in Unix milliseconds format.

created_beforeinteger

Restricts the search scope to only retrieve group channels which have been created before the specified time, in Unix milliseconds format.

show_emptyboolean
show_memberboolean
show_delivery_receiptboolean
show_read_receiptboolean
show_metadataboolean
show_frozenboolean
order'chronological' | 'latest_last_message' | 'channel_name_alphabetical' | 'metadata_value_alphabetical'
metadata_order_keystring

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_typesstring

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_startswithstring

Searches for group channels with the custom type which starts with the specified value. URL encoding the value is recommended.

channel_urlsstring

Specifies a comma-separated string of one or more group channel URLs to restrict the search scope. URL encoding each channel URL is recommended.

namestring

Specifies one or more group channel names.

name_containsstring

Searches for group channels whose names contain the specified value. Note that this parameter is case-insensitive. URL encoding the value is recommended.

name_startswithstring

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_instring

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_instring

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_typestring

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_nicknamestring

Searches for group channels with members whose nicknames match the specified value. URL encoding the value is recommended.

members_nickname_containsstring

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_keystring

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_valuesstring

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_startswithstring

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_keystring

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_valuesstring

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_gtstring

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_gtestring

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_ltstring

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_ltestring

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_messageboolean

Determines whether to include the sorted_metaarray as one of the last_message’s properties in the response.

Headers

api-tokenstring required
Example:{{API_TOKEN}}

Response

Successful response

nextstring
tsinteger

Example response

{
  "next": "next",
  "channels": [
    {
      "metadata": "{}",
      "count_preference": "false",
      "data": "data",
      "custom_type": "custom_type",
      "invited_at": 1,
      "disappearing_message": {
        "is_triggered_by_message_read": true,
        "message_survival_seconds": 6
      },
      "is_hidden": true,
      "created_at": 0,
      "is_super": true,
      "last_message": null,
      "user_last_read": 1,
      "is_discoverable": true,
      "is_muted": true,
      "joined_member_count": 5,
      "freeze": true,
      "is_distinct": true,
      "members": [
        {
          "metadata": "{}",
          "is_active": true,
          "is_blocking_me": true,
          "require_auth_for_profile_image": true,
          "role": "",
          "profile_url": "profile_url",
          "muted_end_at": 2,
          "delivered_ts": 9,
          "do_not_disturb": true,
          "is_muted": true,
          "read_ts": 4,
          "is_blocked_by_me": true,
          "friend_name": "friend_name",
          "friend_discovery_key": [
            "friend_discovery_key",
            "friend_discovery_key"
          ],
          "muted_description": "muted_description",
          "push_enabled": true,
          "user_id": "user_id",
          "nickname": "nickname",
          "is_online": true,
          "push_trigger_option": null,
          "state": "",
          "last_seen_at": 3
        },
        {
          "metadata": "{}",
          "is_active": true,
          "is_blocking_me": true,
          "require_auth_for_profile_image": true,
          "role": "",
          "profile_url": "profile_url",
          "muted_end_at": 2,
          "delivered_ts": 9,
          "do_not_disturb": true,
          "is_muted": true,
          "read_ts": 4,
          "is_blocked_by_me": true,
          "friend_name": "friend_name",
          "friend_discovery_key": [
            "friend_discovery_key",
            "friend_discovery_key"
          ],
          "muted_description": "muted_description",
          "push_enabled": true,
          "user_id": "user_id",
          "nickname": "nickname",
          "is_online": true,
          "push_trigger_option": null,
          "state": "",
          "last_seen_at": 3
        }
      ],
      "max_length_message": 2,
      "my_role": "",
      "inviter": {
        "metadata": "{}",
        "require_auth_for_profile_image": true,
        "is_active": true,
        "role": "",
        "user_id": "user_id",
        "profile_url": "profile_url",
        "nickname": "nickname",
        "is_blocked_by_me": true
      },
      "push_trigger_option": null,
      "member_count": 7,
      "message_survival_seconds": 7,
      "has_ai_bot": true,
      "cover_url": "cover_url",
      "is_ephemeral": true,
      "is_exclusive": true,
      "unread_mention_count": 6,
      "joined_ts": 5,
      "created_by": {
        "metadata": "{}",
        "require_auth_for_profile_image": true,
        "is_active": true,
        "role": "",
        "user_id": "user_id",
        "profile_url": "profile_url",
        "nickname": "nickname",
        "is_blocked_by_me": true
      },
      "has_bot": true,
      "unread_message_count": 7,
      "channel_url": "channel_url",
      "is_broadcast": true,
      "hidden_state": "hidden_allow_auto_unhide",
      "member_state": "invited",
      "is_push_enabled": true,
      "is_public": true,
      "name": "name",
      "read_receipt": {
        "key": 1
      },
      "sms_fallback": {
        "exclude_user_ids": [
          "exclude_user_ids",
          "exclude_user_ids"
        ],
        "wait_seconds": 1
      },
      "ignore_profanity_filter": true,
      "delivery_receipt": "{}",
      "is_access_code_required": true,
      "ts_message_offset": 1
    },
    {
      "metadata": "{}",
      "count_preference": "false",
      "data": "data",
      "custom_type": "custom_type",
      "invited_at": 1,
      "disappearing_message": {
        "is_triggered_by_message_read": true,
        "message_survival_seconds": 6
      },
      "is_hidden": true,
      "created_at": 0,
      "is_super": true,
      "last_message": null,
      "user_last_read": 1,
      "is_discoverable": true,
      "is_muted": true,
      "joined_member_count": 5,
      "freeze": true,
      "is_distinct": true,
      "members": [
        {
          "metadata": "{}",
          "is_active": true,
          "is_blocking_me": true,
          "require_auth_for_profile_image": true,
          "role": "",
          "profile_url": "profile_url",
          "muted_end_at": 2,
          "delivered_ts": 9,
          "do_not_disturb": true,
          "is_muted": true,
          "read_ts": 4,
          "is_blocked_by_me": true,
          "friend_name": "friend_name",
          "friend_discovery_key": [
            "friend_discovery_key",
            "friend_discovery_key"
          ],
          "muted_description": "muted_description",
          "push_enabled": true,
          "user_id": "user_id",
          "nickname": "nickname",
          "is_online": true,
          "push_trigger_option": null,
          "state": "",
          "last_seen_at": 3
        },
        {
          "metadata": "{}",
          "is_active": true,
          "is_blocking_me": true,
          "require_auth_for_profile_image": true,
          "role": "",
          "profile_url": "profile_url",
          "muted_end_at": 2,
          "delivered_ts": 9,
          "do_not_disturb": true,
          "is_muted": true,
          "read_ts": 4,
          "is_blocked_by_me": true,
          "friend_name": "friend_name",
          "friend_discovery_key": [
            "friend_discovery_key",
            "friend_discovery_key"
          ],
          "muted_description": "muted_description",
          "push_enabled": true,
          "user_id": "user_id",
          "nickname": "nickname",
          "is_online": true,
          "push_trigger_option": null,
          "state": "",
          "last_seen_at": 3
        }
      ],
      "max_length_message": 2,
      "my_role": "",
      "inviter": {
        "metadata": "{}",
        "require_auth_for_profile_image": true,
        "is_active": true,
        "role": "",
        "user_id": "user_id",
        "profile_url": "profile_url",
        "nickname": "nickname",
        "is_blocked_by_me": true
      },
      "push_trigger_option": null,
      "member_count": 7,
      "message_survival_seconds": 7,
      "has_ai_bot": true,
      "cover_url": "cover_url",
      "is_ephemeral": true,
      "is_exclusive": true,
      "unread_mention_count": 6,
      "joined_ts": 5,
      "created_by": {
        "metadata": "{}",
        "require_auth_for_profile_image": true,
        "is_active": true,
        "role": "",
        "user_id": "user_id",
        "profile_url": "profile_url",
        "nickname": "nickname",
        "is_blocked_by_me": true
      },
      "has_bot": true,
      "unread_message_count": 7,
      "channel_url": "channel_url",
      "is_broadcast": true,
      "hidden_state": "hidden_allow_auto_unhide",
      "member_state": "invited",
      "is_push_enabled": true,
      "is_public": true,
      "name": "name",
      "read_receipt": {
        "key": 1
      },
      "sms_fallback": {
        "exclude_user_ids": [
          "exclude_user_ids",
          "exclude_user_ids"
        ],
        "wait_seconds": 1
      },
      "ignore_profanity_filter": true,
      "delivery_receipt": "{}",
      "is_access_code_required": true,
      "ts_message_offset": 1
    }
  ],
  "ts": 4
}

Changes

  • 2a35c3c56c0fRevision changes
    • breaking

      added to the // response property oneOf list for the response status

    • info

      removed from the // response property oneOf list for the response status

  • b05d4e3c6329Revision changes
    • breaking

      added to the // response property oneOf list for the response status

    • info

      removed from the // response property oneOf list for the response status