Slack User Groups: The Complete Guide

Slack user groups are the @handles — @design, @platform, @oncall-payments — that notify a whole set of people with one mention. They look simple, and they mostly are. But there are enough rules around plans, permissions, guests, channels and the API that teams regularly trip over them. This guide collects them in one place, with every Slack-specific rule checked against Slack's help center and API docs as of October 2026.

What a user group is (and isn't)

A user group is a named list of workspace members with a handle. Mentioning the handle notifies everyone in the group. That's the core feature.

A user group is not a channel. It has no messages of its own and no history. Membership of a user group doesn't give anyone access to anything by itself — though you can attach default channels to it (below), and you can add a user group to a channel the same way you'd add one person.

If you're deciding between the two for a team, Slack user group vs channel goes through the trade-offs.

Which Slack plans include user groups

Per Slack's help center (2026), user groups are available on paid subscriptions. On the free plan, the API returns plan_upgrade_required for user group calls.

Plan	Workspace-level user groups	Org-level user groups	SCIM-managed user groups
Free	No	No	No
Pro	Yes	No	No
Business+	Yes	No	Yes (workspace-level)
Enterprise	Yes	Yes	Yes (org-level)

Org-level user groups, available to org owners and admins on Enterprise plans, are created from the admin dashboard and can be used for permissions and membership across multiple workspaces.

Who can create and edit user groups

By default, workspace owners and admins can create and edit workspace-level user groups. They can open that up to other members from the Permissions settings for the workspace (or organization policies on Enterprise). If you don't see the option to create or edit a group, an admin has restricted it.

Restricting creation is usually the right call past a few dozen people. Without it, you get @design, @designers, @design-team and @product-design, all slightly different. With it, you need a clear way for people to request a group — or, better, a source of truth that groups are generated from.

How to create a user group

In Slack (desktop), per the help center:

1. From the Home tab, open Directories, then User groups.
2. Select Create user group.
3. Choose a name and a handle.
4. Optionally set a purpose channel, choose default channels, or create a shared sidebar section. Click Next.
5. Search for and select members.
6. Click Create group.

You can change the name, handle and description later through Edit group details.

Naming conventions that scale

Pattern	Example	Use for
team-name	@platform	Whole team, mirrors a directory group
oncall-team	@oncall-payments	Whoever is on call right now
team-role	@platform-leads	A subset with a specific responsibility
function-region	@sales-emea	Geographic splits

Prefixes keep related groups together in the user group list and in autocomplete. Write the convention down before you have 200 groups.

Default channels

When you create or edit a user group, you can choose up to 100 default channels. Members of the group are added to those channels automatically. That's a convenient way to give a team its working channels.

Two caveats. Slack's documentation describes the adding behaviour; it doesn't describe removing people from those channels when they leave the group, so test that before you rely on it for anything access-related. And it's separate from workspace default channels, which every new member joins on their first day in the workspace. If you need channel membership to follow a group in both directions, see Automatically add and remove Slack channel members from a Google Group.

Guests and external people

Per Slack's help center, guests and people you work with in Slack Connect channels and DMs can't be added to user groups in your organization, and they can't mention the groups you create. The API enforces the same rule: bot users and guests can't be added, and single-channel guests return single_channel_guests_cannot_be_added.

Practical consequences: contractors on guest accounts won't be in team handles, and you can't put an alerting bot into @oncall.

Disabling a group

Deactivating a user group (three-dots menu → Deactivate group) keeps the group and its members in the list, but its handle can't be mentioned and its members can't be viewed. A deactivated group can be turned back on (the API method is usergroups.enable). That's useful for seasonal or project groups, and it's the only way to "empty" a group through the API (see below).

The user groups API

If you're automating, these are the Web API methods you'll use:

Method	What it does
usergroups.list	List user groups in the workspace
usergroups.create	Create a group (name, handle, description, default channels)
usergroups.update	Change name, handle, description, default channels
usergroups.users.list	List members of a group
usergroups.users.update	Set the members of a group
usergroups.disable / usergroups.enable	Deactivate or reactivate a group

Scopes are usergroups:read and usergroups:write.

The method with the most surprises is usergroups.users.update. According to Slack's API reference:

• It replaces the entire member list with the users you pass. There's no incremental add or remove; your code computes the full desired list every time.
• It won't accept an empty list (no_users_provided / invalid_users). To clear a group, disable it.
• failed_for_some_users means one or more users aren't in the workspace that owns the group.
• subteam_max_users_exceeded means you've hit the maximum group size.
• permission_denied means the calling user isn't allowed to modify the group under the workspace's settings.
• ratelimited comes with a Retry-After header; respect it.

A minimal sync from an external list looks like this:

curl -s -X POST https://slack.com/api/usergroups.users.update \
  -H "Authorization: Bearer $SLACK_TOKEN" \
  -d usergroup=S0123ABCD \
  -d users=U01AAAA,U02BBBB,U03CCCC

Getting the user IDs is usually users.lookupByEmail, one call per person, which only works when the email in your source matches the Slack account's email.

SCIM and user groups

On Business+ and Enterprise plans, Slack supports SCIM provisioning through a connector app with a supported identity provider. SCIM can create and delete user groups and add or remove members — workspace-level groups on Business+, org-level on Enterprise. Slack's help center notes that you can't set unique display names for user groups through SCIM.

If you're on Pro, SCIM isn't available. If you're on Business+ but your identity provider doesn't push the groups you care about — or your groups live in tools an IdP doesn't cover — you'll still need something else. Slack SCIM provisioning alternatives compares the options.

Keeping user groups accurate

User groups are only useful if their membership is right. A stale @platform handle notifies people who left the team and misses people who joined. The main ways to keep them accurate:

• Manual. Fine for a handful of groups, if someone owns each one.
• SCIM from your IdP. Business+ or Enterprise, groups pushed from Okta, Entra ID or similar. See Sync Microsoft Entra ID groups to Slack user groups.
• Scripts against usergroups.users.update.
• A group sync tool.

SyncMyGroup keeps Slack user groups (and channel membership) in sync with Google Groups, Entra ID, GitHub teams, Jira / Atlassian groups and teams, GitLab, PagerDuty and Opsgenie / JSM Ops on-call and teams, Linear and Zoom, in either direction. It can create and delete user groups to match the source, supports nested Google Groups, lets you filter and exclude groups and users, and keeps permanent users in a group regardless of the source. Every sync has a preview of the changes before anything is written. In Slack, the @SyncMyGroups bot can post each add and remove to a channel — @SyncMyGroups subscribe <team> — and @SyncMyGroups help lists the commands. It works on any Slack plan that has user groups, with no SCIM tier required.

Some useful sources for user groups:

Slack user group	Source
@platform	Google Group platform@ (Google Group ↔ Slack)
@oncall-payments	PagerDuty schedule (Slack ↔ PagerDuty)
@linear-mobile	Linear team (Slack ↔ Linear)
@jira-support	Jira / Atlassian team (Slack ↔ Jira)

If your Google Groups are nested, flatten them deliberately: decide whether a parent group's handle should include everyone in its sub-groups before you sync it. The step-by-step Google setup is in How to sync Google Groups to Slack user groups.

Common mistakes

• Letting everyone create groups in a large workspace, then wondering which of five near-identical handles to use.
• Using a user group for access control. It isn't one; channels and the tools themselves control access.
• Hand-maintaining on-call handles. They're wrong after the first missed handover.
• Two writers for one group. A SCIM push and a script both editing @platform will fight. One source per group.
• Forgetting guests. They can't be in user groups; plan for contractors separately.

FAQ

Are Slack user groups available on the free plan?

No. Slack's help center lists user groups as available on paid subscriptions, and the API returns plan_upgrade_required on plans without them.

Who can create user groups in Slack?

Workspace owners and admins by default. They can allow other members to create, disable and modify user groups in the workspace's permission settings. On Enterprise plans, org owners and admins can also create org-level groups.

Can guests be added to a Slack user group?

No. Slack doesn't allow guests or Slack Connect members in your organization's user groups, and the API also rejects bot users.

How do I empty a Slack user group with the API?

You can't set it to zero members — usergroups.users.update rejects an empty list. Call usergroups.disable instead, and usergroups.enable when you need it again.

---

Free up to 5 users, $2 per user per month after that (pricing). Start at app.syncmygroup.com or browse all workflows.