userGroup/addUsers

Set the membership of a Slack User Group by providing the complete list of user IDs. This operation replaces the entire membership list — it does not append to existing members.

REPLACE Semantics: The userIds field replaces the entire membership list. Passing only a single new user ID will remove all other existing members. To safely add one user without removing others: (1) call userGroup/getUsers to retrieve the current list, (2) append the new user ID, (3) call userGroup/addUsers with the full updated list.

When to Use

Sync on-call rotation membership with a scheduling tool (e.g. PagerDuty, OpsGenie) by replacing the group with the current rotation.
Update team membership after organizational changes — set the exact new composition of the group.
Set initial membership immediately after creating a new group with userGroup/create.
Replace a project team after a project handoff where the entire team changes.

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/create` or `userGroup/getMany`.
`userIds`	Required	Comma-separated list of Slack user IDs to set as the complete group membership (e.g. `U01ENG001,U01ENG002,U01ENG003`). This list replaces all existing members.

Sample Configuration

{
  "operation": "userGroup/addUsers",
  "connection": {
    "botToken": "{{ $credentials.slackBot.token }}"
  },
  "userGroupId": "S08ONCALL01",
  "userIds": "{{ $output.buildRotation.userIdsCsv }}"
}

Validation Errors

Error Code	Cause	Resolution
`no_such_subteam`	No user group with the given ID exists.	Verify the group ID using `userGroup/getMany`.
`user_not_found`	One or more of the user IDs in `userIds` does not exist in the workspace.	Validate all user IDs against `user/get` before building the membership list.
`missing_scope`	Token lacks `usergroups:write` scope.	Add `usergroups:write` under OAuth & Permissions and reinstall.
`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.
`updatedUserCount`	number	New total member count after the update.
`status`	string	`"success"` on successful membership update.
`errorCode`	string	Empty on success. Slack API error code on failure.
`payload`	object	Raw Slack API response with the updated group and member list.

Error Port

Activated when the group does not exist, a user ID is invalid, or the token lacks write permissions.

Sample Output

{
  "userGroupId": "S08ONCALL01",
  "updatedUserCount": 3,
  "status": "success",
  "errorCode": "",
  "payload": {
    "ok": true,
    "usergroup": {
      "id": "S08ONCALL01",
      "name": "Platform On-Call",
      "handle": "platform-oncall",
      "user_count": 3,
      "users": ["U01ENG001", "U01ENG002", "U01ENG003"]
    }
  }
}

Expression Reference

Expression	Result
`{{ $output.setGroupUsers.userGroupId }}`	Group ID for confirmation or downstream operations.
`{{ $output.setGroupUsers.updatedUserCount }}`	New member count for logging or notification messages.
`{{ $output.setGroupUsers.status }}`	Status string for conditional branching.
`{{ $output.setGroupUsers.payload.usergroup.users }}`	Confirmed member ID array in the API response.

Node Policies & GuardRails

Policy Area	Recommendation
Replace Semantics Awareness	This is the most critical guard for this operation. Always build the complete intended membership list before calling. Never pass only the new user IDs unless your intent is to replace all existing members.
Safe Append Pattern	To add a single user: call `userGroup/getUsers` → append new ID to `userIds` array → join as comma-separated string → call `userGroup/addUsers`. This is a two-step atomic pattern.
User Validation	Validate all user IDs before the call. A single invalid user ID in the list will cause the entire operation to fail. Run user IDs through `user/get` and filter out deactivated or invalid accounts.
Rotation Workflows	For automated on-call rotation, maintain the authoritative member list in your scheduling system. Always derive the Slack group membership from the scheduling tool rather than reading it back from Slack.
Empty List	Passing an empty `userIds` string will remove all members from the group. The group will remain enabled but have zero members — @mentions will not notify anyone.

Examples

Set On-Call Rotation from Scheduling System

Each Monday, replace the @platform-oncall group members with the current week's rotation from PagerDuty.

{
  "operation": "userGroup/addUsers",
  "userGroupId": "S08ONCALL01",
  "userIds": "{{ $output.getRotation.slackUserIdsCsv }}"
}

Safely Add One User Without Removing Others

Add a new engineer to the @reviewers group while keeping existing members.

// Step 1: Get current members
{
  "operation": "userGroup/getUsers",
  "userGroupId": "S08REVIEWS1"
}
// Step 2: Build updated list
// updatedIds = [...$output.getGroupUsers.userIds, $input.newUserId].join(',')
// Step 3: Set the complete updated membership
{
  "operation": "userGroup/addUsers",
  "userGroupId": "S08REVIEWS1",
  "userIds": "{{ updatedIds }}"
}

Initialize Group After Creation

Immediately after creating a new team group, populate it with the initial members.

{
  "operation": "userGroup/addUsers",
  "userGroupId": "{{ $output.createGroup.userGroupId }}",
  "userIds": "{{ $input.initialMemberIds }}"
}