Update a user group

PATCH https://zulip.in.tum.de/api/v1/user_groups/{user_group_id}

Update the name or description of a user group.

Usage examples

#!/usr/bin/env python3

import zulip

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

request = {
    "group_id": user_group_id,
    "name": "marketing",
    "description": "The marketing team.",
}
result = client.update_user_group(request)
print(result)

curl -sSX PATCH https://zulip.in.tum.de/api/v1/user_groups/33 \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode 'name=marketing team' \
    --data-urlencode 'description=The marketing team.' \
    --data-urlencode 'can_manage_group={"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 11}' \
    --data-urlencode 'can_mention_group={"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 11}'

Parameters

user_group_id integer required in path

Example: 33

The ID of the target user group.


name string optional

Example: "marketing team"

The new name of the group.

Changes: Before Zulip 7.0 (feature level 165), this was a required field.


description string optional

Example: "The marketing team."

The new description of the group.

Changes: Before Zulip 7.0 (feature level 165), this was a required field.


can_manage_group object optional

Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 11}

The set of users who have permission to manage this user group expressed as an update to a group-setting value.

This setting cannot be set to "role:internet" and "role:everyone" system groups.

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

can_manage_group object details:

  • new: integer | object required

    The new group-setting value for who would have the permission to manage the group.

    This parameter must be one of the following:

    1. The ID of the user group with this permission.

    2. An object with the following 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.

  • old: integer | object optional

    The expected current group-setting value for who has the permission to manage the group.

    This parameter must be one of the following:

    1. The ID of the user group with this permission.

    2. An object with the following 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.


can_mention_group object optional

Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 11}

The set of users who have permission to mention this group, expressed as an update to a group-setting value.

This setting cannot be set to "role:internet" and "role:owners" system groups.

Changes: In Zulip 9.0 (feature level 260), this parameter was updated to only accept an object with the old and new fields described below. Prior to this feature level, this parameter could be either of the two forms of a group-setting value.

Before Zulip 9.0 (feature level 258), this parameter could only be the integer form of a group-setting value.

Before Zulip 8.0 (feature level 198), this parameter 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.

can_mention_group object details:

  • new: integer | object required

    The new group-setting value for who would have the permission to mention the group.

    This parameter must be one of the following:

    1. The ID of the user group with this permission.

    2. An object with the following 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.

  • old: integer | object optional

    The expected current group-setting value for who has the permission to mention the group.

    This parameter must be one of the following:

    1. The ID of the user group with this permission.

    2. An object with the following 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.


Response

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

An example JSON response when the user group ID is invalid:

{
    "code": "BAD_REQUEST",
    "msg": "Invalid user group",
    "result": "error"
}