Get user groups

GET https://zulip.innoventum.fi/api/v1/user_groups

Fetches all of the user groups in the organization.

Usage examples

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# Get all user groups of the organization.
result = client.get_user_groups()
print(result)

curl -sSX GET -G https://zulip.innoventum.fi/api/v1/user_groups \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY

Parameters

This endpoint does not accept any parameters.

Response

Return values

• user_groups: (object)[]

  A list of user_group objects.

  • description: string

    The human-readable description of the user group.

  • id: integer

    The user group's integer ID.

  • members: (integer)[]

    The integer user IDs of the user group members.

  • direct_subgroup_ids: (integer)[]

    The integer user group IDs of the direct subgroups.

    Changes: New in Zulip 6.0 (feature level 131). Introduced in feature level 127 as subgroups, but clients can ignore older events as this feature level predates subgroups being fully implemented.

  • name: string

    User group name.

  • is_system_group: boolean

    Whether the user group is a system group which cannot be modified by users.

    Changes: New in Zulip 5.0 (feature level 93).

  • can_mention_group: integer | object

    A group-setting value defining the set of users who have permission to mention this user group.

    Changes: Before Zulip 9.0 (feature level 258), this setting was always the integer form of a group-setting value.

    Before Zulip 8.0 (feature level 198), this setting was named can_mention_group_id.

    New in Zulip 8.0 (feature level 191). Previously, groups could be mentioned only if they were not system groups.

    Will be one of the following:

    • The ID of the user group with this permission.

    • An object with these fields:

      • direct_members: (integer)[]

        The list of IDs of individual users in the collection of users with this permission.

      • direct_subgroups: (integer)[]

        The list of IDs of the groups in the collection of users with this permission.

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "msg": "",
    "result": "success",
    "user_groups": [
        {
            "can_mention_group": 11,
            "description": "Owners of this organization",
            "direct_subgroup_ids": [],
            "id": 1,
            "is_system_group": true,
            "members": [
                1
            ],
            "name": "role:owners"
        },
        {
            "can_mention_group": 12,
            "description": "Administrators of this organization, including owners",
            "direct_subgroup_ids": [
                1
            ],
            "id": 2,
            "is_system_group": true,
            "members": [
                2
            ],
            "name": "role:administrators"
        },
        {
            "can_mention_group": 13,
            "description": "Characters of Hamlet",
            "direct_subgroup_ids": [],
            "id": 3,
            "is_system_group": false,
            "members": [
                3,
                4
            ],
            "name": "hamletcharacters"
        }
    ]
}