Get user groups

GET https://chat.zulip.org/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://chat.zulip.org/api/v1/user_groups \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode include_deactivated_groups=true

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.

  • date_created: integer | null

    The UNIX timestamp for when the user group was created, in UTC seconds.

    A null value means the user group has no recorded date, which is often because the group predates the metadata being tracked starting in Zulip 8.0, or because it was created via a data import tool or management command.

    Changes: New in Zulip 10.0 (feature level 292).

  • creator_id: integer | null

    The ID of the user who created this user group.

    A null value means the user group has no recorded creator, which is often because the group predates the metadata being tracked starting in Zulip 8.0, or because it was created via a data import tool or management command.

    Changes: New in Zulip 10.0 (feature level 292).

  • members: (integer)[]

    The integer user IDs of the user group's members, which are guaranteed to be non-deactivated users in the organization.

    Changes: Prior to Zulip 10.0 (feature level 303), this list also included deactivated users who were members of the user group before being deactivated.

  • 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_add_members_group: integer | object

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

    Changes: New in Zulip 10.0 (feature level 305). Previously, this permission was controlled by the can_manage_group setting.

    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.

        Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

      • direct_subgroups: (integer)[]

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

  • can_join_group: integer | object

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

    Changes: New in Zulip 10.0 (feature level 301).

    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.

        Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

      • direct_subgroups: (integer)[]

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

  • can_leave_group: integer | object

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

    Changes: New in Zulip 10.0 (feature level 308).

    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.

        Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

      • direct_subgroups: (integer)[]

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

  • can_manage_group: integer | object

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

    Changes: New in Zulip 10.0 (feature level 283).

    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.

        Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

      • direct_subgroups: (integer)[]

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

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

        Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

      • direct_subgroups: (integer)[]

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

  • can_remove_members_group: integer | object

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

    Changes: New in Zulip 10.0 (feature level 324). Previously, this permission was controlled by the can_manage_group setting.

    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.

        Changes: Prior to Zulip 10.0 (feature level 303), this list would include deactivated users who had the permission before being deactivated.

      • direct_subgroups: (integer)[]

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

  • deactivated: boolean

    Whether the user group is deactivated. Deactivated groups cannot be used as a subgroup of another group or used for any other purpose.

    Changes: New in Zulip 10.0 (feature level 290).

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_add_members_group": 16,
            "can_join_group": 16,
            "can_leave_group": 15,
            "can_manage_group": 16,
            "can_mention_group": 11,
            "can_remove_members_group": 16,
            "creator_id": null,
            "date_created": null,
            "description": "Owners of this organization",
            "direct_subgroup_ids": [],
            "id": 1,
            "is_system_group": true,
            "members": [
                1
            ],
            "name": "role:owners"
        },
        {
            "can_add_members_group": 17,
            "can_join_group": 17,
            "can_leave_group": 15,
            "can_manage_group": 17,
            "can_mention_group": 12,
            "can_remove_members_group": 16,
            "creator_id": null,
            "date_created": null,
            "description": "Administrators of this organization, including owners",
            "direct_subgroup_ids": [
                1
            ],
            "id": 2,
            "is_system_group": true,
            "members": [
                2
            ],
            "name": "role:administrators"
        },
        {
            "can_add_members_group": 20,
            "can_join_group": 20,
            "can_leave_group": 15,
            "can_manage_group": 20,
            "can_mention_group": 13,
            "can_remove_members_group": 16,
            "creator_id": null,
            "date_created": 1717484476,
            "description": "Characters of Hamlet",
            "direct_subgroup_ids": [],
            "id": 3,
            "is_system_group": false,
            "members": [
                3,
                4
            ],
            "name": "hamletcharacters"
        }
    ]
}