# Create Slack User Group

Create a Slack user group such as @engineering from a runbook

Creates a Slack user group. A user group is a mention group such as `@engineering` or `@design` that notifies many people at once. Use [Manage Slack User Group Members](https://www.tryrisotto.com/docs/integrations/tools/slack/manage_usergroup_members) to add people to the group after you create it.

## How It Works

The agent gives the tool these values:

- **Name** (required) - the display name, for example `Marketing Team`. It must be unique among user groups.
- **Handle** (optional) - the mention handle without the `@`, for example `marketing-team`. It must be unique among channels, users, and user groups. The tool removes a leading `@` if the agent includes one.
- **Description** (optional) - a short description of the group.

Slack accepts a handle that has 21 characters or fewer. It can contain only lowercase letters, numbers, hyphens, underscores, and periods.

When the group exists, the tool returns its ID and handle. Chain the [Manage Slack User Group Members](https://www.tryrisotto.com/docs/integrations/tools/slack/manage_usergroup_members) tool in the same runbook to add the first members.

## Authentication

> **Warning:** This tool needs a Slack **user token** with the `usergroups:write` scope. A
> bot token cannot manage user groups. The tool never falls back to a bot token
> or to the Slack app that handles your ticket conversations.

The tool uses the first token it finds in this order:

1. The per-tool **User Token** override.
2. The user token of the Slack Tools connector. Follow the [Slack Tools Setup](https://www.tryrisotto.com/docs/integrations/tools/slack/setup) guide to configure it. The connector's user token includes `usergroups:write`.

The person who authorized the connector must be allowed to manage user groups in your Slack workspace settings. Many workspaces limit this to admins. If creation fails with a permission error although the scope is present, check **who can manage user groups** in Slack. You can also reconnect the connector with an admin account.

> **Warning:** **Check for the missing-scopes banner before you rely on this tool.** If your
> connector predates the `usergroups:write` scope, the tool's page in the
> dashboard shows a **Missing scopes** banner: *"The Slack tools app is missing
> required scopes. Reconnect it on the Slack page."* Click the link in the
> banner, or go to **Settings → Integrations → Slack**, then click **Connected**
> on the **Tools app** card and choose **Reconnect...**. Follow the [Slack Tools
> Setup](https://www.tryrisotto.com/docs/integrations/tools/slack/setup#reconnecting-the-connector) guide.

## Configuration Options

- **User Token** *(Optional override)* - Per-tool Slack user token (`xoxp-*`). Takes precedence over the Slack Tools connector. See [per-tool token override](https://www.tryrisotto.com/docs/integrations/tools/slack/setup#per-tool-token-override).
- **Team ID** *(Optional)* - The workspace to create groups in. Required when you use a per-tool user token override. On an Enterprise Grid organization, it also picks the workspace.

## Example Runbook Uses

- Create a `@new-project` mention group in a project kickoff runbook, then add the team with the members tool.
- Create a department mention group during an organization restructure without a Slack admin doing it by hand.

## Limitations

- User groups exist only on paid Slack plans.
- The name and the handle must be unique. The tool does not rename or reuse an existing group.
- The tool creates the group only. It does not add members, edit, or delete the group.

## Troubleshooting

### The authorized user is not allowed to create user groups

Slack returned a permission error. Update the workspace's user group
permissions, or reconnect the Slack Tools connector with an admin account.

### A user group with this name already exists

Slack requires a unique name. Choose another name. If the handle conflicts,
the message says a user group, channel, or user already has the handle. Choose
another handle.

### Invalid handle

Handles must be 21 characters or fewer. Use only lowercase letters, numbers,
hyphens, underscores, and periods.

### User groups are only available on paid Slack plans

Slack does not offer user groups on your plan. Upgrade the Slack plan to use
this tool.

### Slack could not tell which workspace to create the user group in

This happens with an organization-wide Enterprise Grid install. Set the **Team
ID** in the tool configuration to the workspace where Risotto creates the
group.

### Missing-scopes banner on the tool page

Your connector app does not grant `usergroups:write`. Click the link in the banner, or go to **Settings → Integrations → Slack**, then click **Connected** on the **Tools app** card and choose **Reconnect...**.
Follow the [Slack Tools
Setup](https://www.tryrisotto.com/docs/integrations/tools/slack/setup#reconnecting-the-connector) guide.

## Related

- [Manage Slack User Group Members](https://www.tryrisotto.com/docs/integrations/tools/slack/manage_usergroup_members) - add and remove members after you create the group
- [Slack Tools Setup](https://www.tryrisotto.com/docs/integrations/tools/slack/setup)

Source: https://www.tryrisotto.com/docs/integrations/tools/slack/create_usergroup
