# User Groups
User groups allow you to create named groups of users that can be mentioned in messages to notify all group members. When you mention a user group in a message, all members of that group who are also channel members receive a notification. User groups are managed independently of channels and are available across your entire app.
## Creating a User Group
To create a new user group, use the `createUserGroup` endpoint:
```js label="JavaScript"
const userGroup = await client.post("/usergroups", {
name: "Design Team",
description: "Product design team members",
member_ids: ["alice", "bob", "charlie"],
});
```
```python label="Python"
user_group = client.post('/usergroups', {
'name': 'Design Team',
'description': 'Product design team members',
'member_ids': ['alice', 'bob', 'charlie'],
})
```
### Create User Group Parameters
| Name | Type | Description | Default | Optional |
| ----------- | ------ | ------------------------------------------------------------------------------------------------ | -------------- | -------- |
| id | string | Unique identifier for the user group. Auto-generated as UUID if omitted. Maximum 255 characters. | Auto-generated | ✓ |
| name | string | The name of the user group. | | ✗ |
| description | string | An optional description of the group. Maximum 1024 characters. | | ✓ |
| team_id | string | Team ID for multi-tenant apps. Required if multi-tenancy is enabled. | | ✓ |
| member_ids | array | Array of user IDs to add as initial members. Maximum 100 members per request. | | ✓ |
The response returns the created user group object.
## Retrieving a User Group
To retrieve a specific user group by ID:
```js label="JavaScript"
const userGroup = await client.get("/usergroups/{id}", {
query: {
team_id: "my-team", // optional
},
});
```
```python label="Python"
user_group = client.get('/usergroups/{id}', params={
'team_id': 'my-team', # optional
})
```
## Listing User Groups
To list user groups with pagination:
```js label="JavaScript"
const response = await client.get("/usergroups", {
query: {
limit: 20,
id_gt: "last-id", // optional: cursor for pagination
created_at_gt: "2024-01-01T00:00:00Z", // optional: filter by creation date
team_id: "my-team", // optional
},
});
```
```python label="Python"
response = client.get('/usergroups', params={
'limit': 20,
'id_gt': 'last-id', # optional: cursor for pagination
'created_at_gt': '2024-01-01T00:00:00Z', # optional
'team_id': 'my-team', # optional
})
```
### List User Groups Parameters
| Name | Type | Description | Default | Optional |
| ------------- | ------- | --------------------------------------------------------------------------------------- | ------- | -------- |
| limit | integer | Number of user groups to return. Valid range: 1-100. | 20 | ✓ |
| id_gt | string | ID cursor for pagination. Return groups with IDs greater than this value. | | ✓ |
| created_at_gt | string | Timestamp for pagination. Return groups created after this timestamp (ISO 8601 format). | | ✓ |
| team_id | string | Filter by team ID for multi-tenant apps. | | ✓ |
## Searching User Groups
To search user groups by name:
```js label="JavaScript"
const response = await client.get("/usergroups/search", {
query: {
query: "design", // prefix search on group name
limit: 10,
name_gt: "abc", // optional: cursor for pagination by name
id_gt: "last-id", // optional: cursor for pagination by ID
team_id: "my-team", // optional
},
});
```
```python label="Python"
response = client.get('/usergroups/search', params={
'query': 'design', # prefix search on group name
'limit': 10,
'name_gt': 'abc', # optional: cursor for pagination by name
'id_gt': 'last-id', # optional: cursor for pagination by ID
'team_id': 'my-team', # optional
})
```
### Search User Groups Parameters
| Name | Type | Description | Default | Optional |
| ------- | ------- | --------------------------------------------------------------------------------- | ------- | -------- |
| query | string | Search term for prefix matching on group name. | | ✗ |
| limit | integer | Number of results to return. Valid range: 1-25. | 10 | ✓ |
| name_gt | string | Cursor for pagination by name. Returns groups with names greater than this value. | | ✓ |
| id_gt | string | Cursor for pagination by ID. Returns groups with IDs greater than this value. | | ✓ |
| team_id | string | Filter by team ID for multi-tenant apps. | | ✓ |
## Updating a User Group
To update a user group's name or description:
```js label="JavaScript"
const userGroup = await client.put("/usergroups/{id}", {
name: "Design & Product Team",
description: "Product and design team members",
});
```
```python label="Python"
user_group = client.put('/usergroups/{id}', {
'name': 'Design & Product Team',
'description': 'Product and design team members',
})
```
### Update User Group Parameters
| Name | Type | Description | Default | Optional |
| ----------- | ------ | ---------------------------------------------------------------------------------------- | ------- | -------- |
| name | string | Updated name for the group. At least one of name or description must be provided. | | ✓ |
| description | string | Updated description for the group. At least one of name or description must be provided. | | ✓ |
| team_id | string | Team ID for multi-tenant apps. The team_id is immutable and cannot be changed. | | ✓ |
## Deleting a User Group
To delete a user group:
```js label="JavaScript"
await client.delete("/usergroups/{id}", {
query: {
team_id: "my-team", // optional
},
});
```
```python label="Python"
client.delete('/usergroups/{id}', params={
'team_id': 'my-team', # optional
})
```
## Managing Members
### Adding Members
To add members to a user group:
```js label="JavaScript"
// Add members as regular members
const userGroup = await client.post("/usergroups/{id}/members", {
member_ids: ["dave", "eve", "frank"],
});
// Add members as group admins
const admins = await client.post("/usergroups/{id}/members", {
member_ids: ["grace"],
is_admin: true,
});
// Promote an existing member to admin
await client.post("/usergroups/{id}/members", {
member_ids: ["dave"],
is_admin: true,
});
// Demote an admin back to regular member
await client.post("/usergroups/{id}/members", {
member_ids: ["dave"],
is_admin: false,
});
```
```python label="Python"
# Add members as regular members
user_group = client.post('/usergroups/{id}/members', {
'member_ids': ['dave', 'eve', 'frank'],
})
# Add members as group admins
admins = client.post('/usergroups/{id}/members', {
'member_ids': ['grace'],
'is_admin': True,
})
# Promote an existing member to admin
client.post('/usergroups/{id}/members', {
'member_ids': ['dave'],
'is_admin': True,
})
# Demote an admin back to regular member
client.post('/usergroups/{id}/members', {
'member_ids': ['dave'],
'is_admin': False,
})
```
### Add Members Parameters
| Name | Type | Description | Default | Optional |
| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| member_ids | array | Array of user IDs to add to the group. Maximum 100 members per request. All user IDs must exist. | | ✗ |
| is_admin | bool | Whether to add the members as group admins. Applies to all members in the request. If the member already exists in the group, their admin status is updated to match this value. Group admins can update and delete the group without needing the `UpdateAnyUserGroup` or `DeleteAnyUserGroup` permissions. | false | ✓ |
| team_id | string | Team ID for multi-tenant apps. | | ✓ |
### Removing Members
To remove members from a user group:
```js label="JavaScript"
const userGroup = await client.post("/usergroups/{id}/members/delete", {
member_ids: ["dave", "eve"],
});
```
```python label="Python"
user_group = client.post('/usergroups/{id}/members/delete', {
'member_ids': ['dave', 'eve'],
})
```
### Remove Members Parameters
| Name | Type | Description | Default | Optional |
| ---------- | ------ | ---------------------------------------------------------------------------- | ------- | -------- |
| member_ids | array | Array of user IDs to remove from the group. Maximum 100 members per request. | | ✗ |
| team_id | string | Team ID for multi-tenant apps. | | ✓ |
## User Group Object
The user group response object contains the following fields:
| Name | Type | Description |
| ----------- | ------ | -------------------------------------------------------------------------------------- |
| id | string | Unique identifier for the user group. |
| name | string | The name of the user group. |
| description | string | The description of the user group. |
| team_id | string | Team ID for multi-tenant apps. |
| members | array | Array of member objects (see below). |
| created_at | string | Timestamp when the group was created (ISO 8601 format). |
| updated_at | string | Timestamp when the group was last updated (ISO 8601 format). |
| created_by | string | User ID of the user who created the group. Used for ownership-based permission checks. |
### Member Object
Each entry in the `members` array has the following fields:
| Name | Type | Description |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| user_id | string | The user ID of the group member. |
| is_admin | bool | Whether this member is a group admin. Group admins can update and delete the group even without the `UpdateAnyUserGroup` or `DeleteAnyUserGroup` permissions. |
| created_at | string | Timestamp when the member was added (ISO 8601 format). |
## Using User Groups in Messages
To mention a user group in a message, include the `mentioned_group_ids` field when sending a message. See [Sending Messages](/chat/docs/dotnet-csharp/send-message/#mentions) for details on message mentions.
Mentioning user groups requires the `NotifyGroup` permission. Only members of the group who are also members of the channel will receive notifications for the mention.
## Limits
- **Members per group**: Maximum 100 members total per group. Add and remove requests also accept a maximum of 100 member IDs per request
- **Groups per app**: Maximum 1000 user groups per app (or per team with multi-tenancy)
- **Search limit**: Maximum 25 results per search request
- **List limit**: Maximum 100 results per list request
- **Group mentions per message**: Maximum 10 group mentions per message
## Permissions
The following permissions control user group operations. Permissions marked as "owner" only apply when the requesting user is the creator of the group (`created_by`).
| Permission | Operation | Owner/Group Admin | Default Roles |
| -------------------- | ----------------------------------------------------------- | ----------------- | --------------------- |
| `CreateUserGroup` | Create new user groups | No | `user` and above |
| `ReadUserGroups` | Get, list, and search user groups | No | `user` and above |
| `UpdateUserGroup` | Update a user group the user created or is an admin of | Yes | `user` and above |
| `UpdateAnyUserGroup` | Update any user group regardless of creator or admin status | No | `moderator` and above |
| `DeleteUserGroup` | Delete a user group the user created or is an admin of | Yes | `user` and above |
| `DeleteAnyUserGroup` | Delete any user group regardless of creator or admin status | No | `moderator` and above |
| `NotifyGroup` | Mention user groups in messages | No | All channel roles |
### Permission resolution for updates and deletes
When a client-side user attempts to update or delete a group, the system checks permissions in the following order:
1. **Owner check**: If the user has `UpdateUserGroup` / `DeleteUserGroup` and is the group creator (`created_by`), the action is allowed.
2. **Admin check**: If the user is a group admin (`is_admin` is true on their membership), the action is allowed.
3. **Any-group fallback**: If neither of the above applies, the system checks `UpdateAnyUserGroup` / `DeleteAnyUserGroup`.
This means group admins can modify or delete the group without needing the broader `UpdateAnyUserGroup` or `DeleteAnyUserGroup` permissions.
### Scope
User group permissions (`CreateUserGroup`, `ReadUserGroups`, etc.) are application-level permissions. `NotifyGroup` is a channel-level permission — it controls whether a user can mention a group within a specific channel. The `guest` role does not have user group management permissions by default but can mention groups in channels.
These defaults can be customized through the [permission system](/chat/docs/dotnet-csharp/chat-permission-policies/).
---
This page was last updated at 2026-05-22T16:32:16.274Z.
For the most recent version of this documentation, visit [https://getstream.io/chat/docs/dotnet-csharp/user-groups/](https://getstream.io/chat/docs/dotnet-csharp/user-groups/).