Update a user group
PATCH https://chat.zulip.org/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": "leadership",
"description": "The leadership team.",
}
result = client.update_user_group(request)
print(result)
curl -sSX PATCH https://chat.zulip.org/api/v1/user_groups/38 \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode 'name=marketing team' \
--data-urlencode 'description=The marketing team.' \
--data-urlencode 'can_add_members_group={"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 11}' \
--data-urlencode 'can_join_group={"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 11}' \
--data-urlencode 'can_leave_group={"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 15}' \
--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}' \
--data-urlencode 'can_remove_members_group={"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 11}'
Parameters
user_group_id integer required in path
Example: 38
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_add_members_group object optional
Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 11}
The set of users who have permission to add members to this user group
expressed as an update to a group-setting value.
Changes: New in Zulip 10.0 (feature level 305). Previously, this
permission was controlled by the can_manage_group setting.
can_add_members_group object details:
-
new: integer | object required The new group-setting value for the set of users
who would have the permission to add members to the group.
This parameter must be one of the following:
The ID of the user group with this permission.
An object with the following 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.
-
old: integer | object optional The expected current group-setting value
for the set of users who have the permission to add members to the group.
This parameter must be one of the following:
The ID of the user group with this permission.
An object with the following 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 object optional
Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 11}
The set of users who have permission to join this user group
expressed as an update to a group-setting value.
Changes: New in Zulip 10.0 (feature level 301).
can_join_group object details:
-
new: integer | object required The new group-setting value for who would
have the permission to join the group.
This parameter must be one of the following:
The ID of the user group with this permission.
An object with the following 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.
-
old: integer | object optional The expected current group-setting value
for who has the permission to join the group.
This parameter must be one of the following:
The ID of the user group with this permission.
An object with the following 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 object optional
Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 15}
The set of users who have permission to leave this user group
expressed as an update to a group-setting value.
Changes: New in Zulip 10.0 (feature level 308).
can_leave_group object details:
-
new: integer | object required The new group-setting value for who would
have the permission to leave the group.
This parameter must be one of the following:
The ID of the user group with this permission.
An object with the following 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.
-
old: integer | object optional The expected current group-setting value
for who has the permission to leave the group.
This parameter must be one of the following:
The ID of the user group with this permission.
An object with the following 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 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:
The ID of the user group with this permission.
An object with the following 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.
-
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:
The ID of the user group with this permission.
An object with the following 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 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:
The ID of the user group with this permission.
An object with the following 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.
-
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:
The ID of the user group with this permission.
An object with the following 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 object optional
Example: {"new": {"direct_members": [10], "direct_subgroups": [11]}, "old": 11}
The set of users who have permission to remove members from this user group
expressed as an update to a group-setting value.
Changes: New in Zulip 10.0 (feature level 324). Previously, this
permission was controlled by the can_manage_group setting.
can_remove_members_group object details:
-
new: integer | object required The new group-setting value for the set of users
who would have the permission to remove members from the group.
This parameter must be one of the following:
The ID of the user group with this permission.
An object with the following 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.
-
old: integer | object optional The expected current group-setting value for
the set of users who have the permission to remove members from the group.
This parameter must be one of the following:
The ID of the user group with this permission.
An object with the following 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.
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"
}