userGroup/create

Create a new Slack User Group (also known as a handle group). Once created, workspace members can @mention the group handle to notify all members simultaneously.

When to Use

Create an @oncall group during incident rotation setup so on-call engineers can be paged as a group.
Provision a new team group when a department is created, as part of an automated onboarding workflow.
Create a @reviewers group for a code review workflow where pull request notifications target the group.
Set up a @stakeholders group for a project channel to streamline communication to decision makers.

Configuration

Connection

Field	Required	Description
`botToken`	Required	Slack Bot Token starting with `xoxb-`. Requires the `usergroups:write` OAuth scope.

Operation Fields

Field	Required	Description
`name`	Required	Display name for the user group as shown in Slack (e.g. `Frontend Team`). This is the human-readable label, not the @handle.
`handle`	Required	The @handle for the group, without the @ prefix (e.g. `frontend-team`). Must be unique in the workspace. Only lowercase letters, numbers, and hyphens are allowed.
`description`	Optional	A short description of the group's purpose, shown in the Slack groups directory.
`channels`	Optional	Comma-separated channel IDs to associate with the group. Associated channels are listed in the group's details in Slack.

Sample Configuration

{
  "operation": "userGroup/create",
  "connection": {
    "botToken": "{{ $credentials.slackBot.token }}"
  },
  "name": "Platform On-Call",
  "handle": "platform-oncall",
  "description": "Current on-call rotation for the Platform team",
  "channels": "C08PLATFORM1,C08INCIDENTS"
}

Validation Errors

Error Code	Cause	Resolution
`name_already_exists`	A user group with the same handle already exists in the workspace (including disabled groups).	Use a unique handle or re-enable the existing disabled group with `userGroup/enable`.
`invalid_handle`	The handle contains invalid characters or is too long.	Use only lowercase letters, numbers, and hyphens. Maximum 21 characters.
`missing_scope`	Token lacks the `usergroups:write` scope.	Add `usergroups:write` under OAuth & Permissions and reinstall the app.
`invalid_channel`	One or more of the specified channel IDs in `channels` is invalid.	Verify each channel ID exists and the bot is a member.

Output

Success Port

Field	Type	Description
`userGroupId`	string	Slack-assigned user group identifier (e.g. `S08ABCDEFGH`). Store this for subsequent `userGroup/addUsers` and `userGroup/update` operations.
`handle`	string	The @handle assigned to the group (without @).
`name`	string	Display name of the created group.
`description`	string	Group description.
`userCount`	number	Current member count — `0` for a newly created group with no members yet.
`status`	string	`"success"` on successful creation.
`errorCode`	string	Empty on success. Slack API error code on failure.
`payload`	object	Raw Slack API response.

Error Port

Activated when a group with the same handle already exists, the handle is invalid, or the token lacks write permissions.

Sample Output

{
  "userGroupId": "S08ONCALL01",
  "handle": "platform-oncall",
  "name": "Platform On-Call",
  "description": "Current on-call rotation for the Platform team",
  "userCount": 0,
  "status": "success",
  "errorCode": "",
  "payload": {
    "ok": true,
    "usergroup": {
      "id": "S08ONCALL01",
      "name": "Platform On-Call",
      "handle": "platform-oncall",
      "description": "Current on-call rotation for the Platform team",
      "user_count": 0
    }
  }
}

Expression Reference

Expression	Result
`{{ $output.createGroup.userGroupId }}`	Group ID for use in `userGroup/addUsers`, `userGroup/update`, and `userGroup/disable` nodes.
`{{ $output.createGroup.handle }}`	Group handle for logging or message confirmation (prefix with @ for display).
`{{ $output.createGroup.name }}`	Display name for confirmation messages.
`{{ $output.createGroup.userCount }}`	Initial member count — always 0 for new groups; add members with `userGroup/addUsers`.

Node Policies & GuardRails

Policy Area	Recommendation
Idempotency	Check for an existing group with the same handle using `userGroup/getMany` before creating. Duplicate handle creation fails with `name_already_exists` and the error port fires.
Handle Naming	Use a consistent naming convention (e.g. `team-oncall`, `dept-reviewers`) to avoid handle collisions and make groups discoverable.
Membership After Creation	Newly created groups have zero members. Always follow group creation with a `userGroup/addUsers` call to populate the initial membership list.
Channel Association	The `channels` field associates the group with channels for display purposes only. It does not automatically add the group's members to those channels.
Disabled Groups	Slack retains disabled groups with their original handles. If you need to reuse a handle, enable the old group with `userGroup/enable` and update it rather than creating a new one.

Examples

Create On-Call Rotation Group

During incident rotation setup, create the on-call group and immediately populate it with the engineers on rotation.

// Step 1: Create the group
{
  "operation": "userGroup/create",
  "name": "Platform On-Call",
  "handle": "platform-oncall",
  "description": "Current on-call rotation for the Platform team"
}
// Step 2: Add members (userGroup/addUsers)
// userGroupId: {{ $output.createGroup.userGroupId }}
// userIds: "U01ENG1,U01ENG2,U01ENG3"

Provision Department Group on New Hire Batch

When a new department is created in the HR system, provision a matching Slack group.

{
  "operation": "userGroup/create",
  "name": "{{ $input.departmentName }}",
  "handle": "{{ $input.departmentHandle }}",
  "description": "All members of the {{ $input.departmentName }} department"
}

Create Project Stakeholders Group

At project kickoff, create a stakeholders group and associate it with the project channel.

{
  "operation": "userGroup/create",
  "name": "{{ $input.projectName }} Stakeholders",
  "handle": "{{ $input.projectSlug }}-stakeholders",
  "description": "Stakeholders for project {{ $input.projectName }}",
  "channels": "{{ $input.projectChannelId }}"
}