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:

const userGroup = await client.post("/usergroups", {
  name: "Design Team",
  description: "Product design team members",
  member_ids: ["alice", "bob", "charlie"],
});

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:

const userGroup = await client.get("/usergroups/{id}", {
  query: {
    team_id: "my-team", // optional
  },
});

user_group = client.get('/usergroups/{id}', params={
    'team_id': 'my-team',  # optional
})

Listing User Groups

To list user groups with pagination:

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
  },
});

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:

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
  },
});

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:

const userGroup = await client.put("/usergroups/{id}", {
  name: "Design & Product Team",
  description: "Product and design team members",
});

user_group = client.put('/usergroups/{id}', {
    'name': 'Design & Product Team',
    'description': 'Product and design team members',
})

Update User Group Parameters

Name	Type	Description	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:

await client.delete("/usergroups/{id}", {
  query: {
    team_id: "my-team", // optional
  },
});

client.delete('/usergroups/{id}', params={
    'team_id': 'my-team',  # optional
})

Managing Members

Adding Members

To add members to a user group:

// 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,
});

# 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:

const userGroup = await client.post("/usergroups/{id}/members/delete", {
  member_ids: ["dave", "eve"],
});

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 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:

Owner check: If the user has UpdateUserGroup / DeleteUserGroup and is the group creator (created_by), the action is allowed.
Admin check: If the user is a group admin (is_admin is true on their membership), the action is allowed.
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.

Managing Users

Authless Users