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 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 examplemarketing-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 tool in the same runbook to add the first members.
Authentication
The tool uses the first token it finds in this order:
- The per-tool User Token override.
- The user token of the Slack Tools connector. Follow the Slack Tools 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.
Configuration Options
- User Token (Optional override) - Per-tool Slack user token (
xoxp-*). Takes precedence over the Slack Tools connector. See 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-projectmention 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 guide.
Related
- Manage Slack User Group Members - add and remove members after you create the group
- Slack Tools Setup
Something wrong or missing? Report an issue · View as Markdown