userGroup/update

Update the display metadata of a Slack User Group — its name, @handle, or description. Membership is managed separately via userGroup/addUsers.

When to Use

Rename a group after a team is renamed in the org chart (e.g. "Platform Team" → "Infrastructure Team").
Update the @handle to reflect a rebranded team name across Slack.
Update the description to reflect a change in the team's scope or responsibilities.
Fix typos or inconsistencies in group names discovered during a workspace audit.

Partial Updates: All metadata fields are optional. Omit fields you do not intend to change — only supplied fields are updated. Membership is not affected by this operation; use userGroup/addUsers to change the member list.

Configuration

Connection

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

Operation Fields

Field	Required	Description
`userGroupId`	Required	The Slack user group identifier (starts with `S`). Obtain from `userGroup/getMany` or stored from `userGroup/create`.
`name`	Optional	New display name for the group. Omit to leave unchanged.
`handle`	Optional	New @handle for the group (without @). Must be unique in the workspace. Omit to leave unchanged.
`description`	Optional	New description for the group. Omit to leave unchanged.

Sample Configuration

{
  "operation": "userGroup/update",
  "connection": {
    "botToken": "{{ $credentials.slackBot.token }}"
  },
  "userGroupId": "S08FRONTEND",
  "name": "Infrastructure Team",
  "handle": "infra-team",
  "description": "All infrastructure and platform engineers"
}

Validation Errors

Error Code	Cause	Resolution
`no_such_subteam`	No user group with the given ID exists in the workspace.	Verify the group ID using `userGroup/getMany`.
`name_already_exists`	The new handle is already in use by another group (including disabled groups).	Choose a different handle. Check existing handles with `userGroup/getMany`.
`invalid_handle`	The handle contains invalid characters or exceeds the maximum length.	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_auth`	Bot token is invalid or revoked.	Regenerate the token and update the credential store.

Output

Success Port

Field	Type	Description
`userGroupId`	string	ID of the updated group (unchanged).
`name`	string	Updated display name.
`handle`	string	Updated @handle (without @).
`description`	string	Updated description.
`status`	string	`"success"` on successful update.
`errorCode`	string	Empty on success. Slack API error code on failure.
`payload`	object	Raw Slack API response with the full updated group object.

Error Port

Activated when the group does not exist, the handle is already taken, or the token lacks write permissions.

Sample Output

{
  "userGroupId": "S08FRONTEND",
  "name": "Infrastructure Team",
  "handle": "infra-team",
  "description": "All infrastructure and platform engineers",
  "status": "success",
  "errorCode": "",
  "payload": {
    "ok": true,
    "usergroup": {
      "id": "S08FRONTEND",
      "name": "Infrastructure Team",
      "handle": "infra-team",
      "description": "All infrastructure and platform engineers",
      "user_count": 8
    }
  }
}

Expression Reference

Expression	Result
`{{ $output.updateGroup.userGroupId }}`	Group ID — unchanged after update, use for downstream operations.
`{{ $output.updateGroup.name }}`	Confirmed new display name from the API response.
`{{ $output.updateGroup.handle }}`	Confirmed new @handle — update any stored references to the old handle.
`{{ $output.updateGroup.description }}`	Confirmed new description from the API response.

Node Policies & GuardRails

Policy Area	Recommendation
Handle Change Impact	Changing a group's @handle will break any existing references to the old handle in Slack messages, bookmarks, or external systems. Audit usage of the old handle before renaming.
Partial Update Semantics	Only provide fields you intend to change. Omitting a field leaves it unchanged — this operation does not require you to resend the full current state.
Handle Uniqueness	Check for handle conflicts using `userGroup/getMany` before attempting a handle rename. Conflicts include disabled groups, which retain their handles.
Audit Trail	Log the old and new group metadata alongside the update timestamp when running automated renaming workflows, so rollback is possible if needed.
Membership Unchanged	This operation only updates name, handle, and description. To change members, use `userGroup/addUsers` separately. Both operations can be chained in the same workflow.

Examples

Rename Group After Team Rename

After an org restructure renames the "Frontend Team" to "UI Engineering", update the Slack group to match.

{
  "operation": "userGroup/update",
  "userGroupId": "S08FRONTEND",
  "name": "UI Engineering",
  "handle": "ui-engineering",
  "description": "All user interface and design engineers"
}

Update Description Only

After a team's scope changes, update only the description without changing the name or handle.

{
  "operation": "userGroup/update",
  "userGroupId": "{{ $input.groupId }}",
  "description": "{{ $input.newDescription }}"
}

Bulk Rename Groups from HR System

During a company rebranding, iterate over a list of group renames and apply them to Slack.

{
  "operation": "userGroup/update",
  "userGroupId": "{{ $loop.item.slackGroupId }}",
  "name": "{{ $loop.item.newName }}",
  "handle": "{{ $loop.item.newHandle }}"
}