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 { user_group } = await client.createUserGroup({
  name: "Design Team",
  description: "Product design team members",
  member_ids: ["alice", "bob", "charlie"],
});

Create User Group Parameters

The response returns the created user group object.

Retrieving a User Group

To retrieve a specific user group by ID:

const { user_group } = await client.getUserGroup("design-team", {
  team_id: "my-team", // optional
});

Listing User Groups

To list user groups with pagination:

const { user_groups } = await client.queryUserGroups({
  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
});

List User Groups Parameters

Searching User Groups

To search user groups by name:

const { user_groups } = await client.searchUserGroups({
  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

Updating a User Group

To update a user group's name or description:

const { user_group } = await client.updateUserGroup("design-team", {
  name: "Design & Product Team",
  description: "Product and design team members",
});

Update User Group Parameters

Deleting a User Group

To delete a user group:

await client.deleteUserGroup("design-team", {
  team_id: "my-team", // optional
});

Managing Members

Adding Members

To add members to a user group:

// Add members as regular members
const { user_group } = await client.addUserGroupMembers("design-team", {
  member_ids: ["dave", "eve", "frank"],
});

// Add members as group admins
const { user_group: admins } = await client.addUserGroupMembers("design-team", {
  member_ids: ["grace"],
  as_admin: true,
});

// Promote an existing member to admin
await client.addUserGroupMembers("design-team", {
  member_ids: ["dave"],
  as_admin: true,
});

// Demote an admin back to regular member
await client.addUserGroupMembers("design-team", {
  member_ids: ["dave"],
  as_admin: false,
});

Add Members Parameters

Removing Members

To remove members from a user group:

const { user_group } = await client.removeUserGroupMembers("design-team", {
  member_ids: ["dave", "eve"],
});

Remove Members Parameters

User Group Object

The user group response object contains the following fields:

Member Object

Each entry in the members array has the following fields:

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.

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