Create a User Group.

Required Params

• name - A name for the User Group. Must be unique among User Groups. ex: My Test Team

Optional Params

• additional_channels - A comma separated string of encoded channel IDs for which the User Group can custom add usergroup members too.
• channels - A comma separated string of encoded channel IDs for which the User Group uses as a default.
• description - A short description of the User Group.
• enable_section - Configure this user group to show as a sidebar section for all group members. Note: Only relevant if group has 1 or more default channels added. ex: true
• handle - A mention handle. Must be unique among channels, users and User Groups.
• include_count - Include the number of users in each User Group. ex: true
• team_id - Encoded team id where the user group has to be created, required if org token is used.

Errors the API can return:

• bad_handle - Handle is invalid
• description_too_long - Given usergroup description is too long
• forbidden_handle - Handle is invalid
• handle_already_exists - Handle is already in use on this workspace
• invalid_channel_provided - An invalid channel ID was provided
• invalid_group_provided - An invalid group ID was provided
• missing_argument - A required argument is missing.
• missing_subteam_name - Subteam name is required
• name_already_exists - Name is already in use on this workspace
• name_too_long - Name too long.
• paid_teams_only - Usergroups can only be used on paid Slack teams
• permission_denied - The user does not have permission to create a User Group.
• plan_upgrade_required - This workspace does not have access to User Groups, as that feature is only available on Standard and above plans.
• target_team_must_be_specified_in_org_context - No target team was specified but the team in context is an org
• target_team_not_on_org - Target team specified is not on the org in context

See the Common Errors guide for errors returned by every Web API method.

Disable an existing User Group.

Required Params

• usergroup - The encoded ID of the User Group to disable. ex: S0604QSJC

Optional Params

• include_count - Include the number of users in the User Group. ex: true
• team_id - Encoded target team id where the user group is, required if org token is used.

Errors the API can return:

• missing_argument - A required argument is missing.
• permission_denied - The user does not have permission to disable the User Group.
• plan_upgrade_required - This workspace does not have access to User Groups, as that feature is only available on Standard and above plans.
• target_team_must_be_specified_in_org_context - No target team was specified but the team in context is an org
• target_team_not_on_org - Target team specified is not on the org in context

See the Common Errors guide for errors returned by every Web API method.

Enable a User Group.

Required Params

• usergroup - The encoded ID of the User Group to enable. ex: S0604QSJC

Optional Params

• include_count - Include the number of users in the User Group. ex: true
• team_id - Encoded team id where the user group is, required if org token is used.

Errors the API can return:

• missing_argument - A required argument is missing.
• permission_denied - The user does not have permission to enables the User Group.
• plan_upgrade_required - This workspace does not have access to User Groups, as that feature is only available on Standard and above plans.

See the Common Errors guide for errors returned by every Web API method.

List all User Groups for a team.

Optional Params

• include_count - Include the number of users in each User Group. ex: true
• include_disabled - Include results for disabled User Groups. ex: true
• include_users - Include the list of users for each User Group. ex: true
• team_id - The user group's encoded team ID. Required if org token is used.

Errors the API can return:

• invalid_cursor - Value passed for cursor was not valid or is no longer valid.
• invalid_team - Cannot find subteam team.
• missing_argument - A required argument is missing.
• plan_upgrade_required - This workspace does not have access to User Groups, as that feature is only available on Standard and above plans.
• users_not_found - Cannot find users on subteam.

See the Common Errors guide for errors returned by every Web API method.

Update an existing User Group.

Required Params

• usergroup - The encoded ID of the User Group to update. ex: S0604QSJC

Optional Params

• additional_channels - A comma separated string of encoded channel IDs for which the User Group can custom add usergroup members too.
• channels - A comma separated string of encoded channel IDs for which the User Group uses as a default.
• description - A short description of the User Group.
• enable_section - Configure this user group to show as a sidebar section for all group members. Note: Only relevant if group has 1 or more default channels added. ex: true
• handle - A mention handle. Must be unique among channels, users and User Groups.
• include_count - Include the number of users in the User Group. ex: true
• name - A name for the User Group. Must be unique among User Groups. ex: My Test Team
• team_id - encoded team id where the user group exists, required if org token is used

Errors the API can return:

• missing_argument - A required argument is missing.
• paid_teams_only - This workspace does not have access to User Groups, as that feature is only available on Standard and above plans.
• permission_denied - The user does not have permission to update the User Group.
• too_many_linked_channels - This request exceeds the number of channels we supporting linking to a single usergroup.

See the Common Errors guide for errors returned by every Web API method.