Update a user group

PATCH https://your-org.zulipchat.com/api/v1/user_groups/{user_group_id}

Update the name, description or any of the permission settings of a user group.

This endpoint is also used to reactivate a user group.

Note that while permissions settings of deactivated groups can be edited by this API endpoint, and those permissions settings do affect the ability to modify the deactivated group and its membership, the deactivated group itself cannot be mentioned or used in the value of any permission without first being reactivated.

Changes: Prior to Zulip 12.0 (feature level 496), bot users were not permitted to call this endpoint.

Starting with Zulip 11.0 (feature level 386), this endpoint can be used to reactivate a user group.

Prior to Zulip 10.0 (feature level 340), only the name field of deactivated groups could be modified.

Usage examples

Python
curl

#!/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://your-org.zulipchat.com/api/v1/user_groups/38 \ -u EMAIL_ADDRESS: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}' \ --data-urlencode deactivated=false

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 who would have this permission.
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.
    
    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 this permission.
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.
    
    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 this permission.
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.
    
    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 this permission.
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.
    
    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 this permission.
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.
    
    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 this permission.
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.
    
    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 this permission.
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.
    
    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 this permission.
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.
    
    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 this permission.
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.
    
    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 this permission.
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.
    
    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 who would have this permission.
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.
    
    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 this permission.
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.
    
    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 optional

Example: false

A deactivated user group can be reactivated by passing this parameter as false.

Passing true does nothing as user group is deactivated using POST /user_groups/{user_group_id}/deactivate endpoint.

Changes: New in Zulip 11.0 (feature level 386).

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

API documentation home

Messages

Scheduled messages

Message reminders

Drafts

Navigation views

Channels

Users

Invitations

Server & organizations

Real-time events

Interactive bots

Specialty endpoints

Back to Zulip

Update a user group

Usage examples

Parameters

Response

Example response(s)