# User Groups

Create, manage, and configure user groups for organizing team members and permissions. User groups (also called handles) allow you to create collections of users that can be easily mentioned and managed together.

## Capabilities

### Create User Group

Create a new user group with a name, handle, and optional configuration.

```typescript { .api }
/**
 * Create a User Group
 * @param options - User group configuration parameters
 * @returns Promise resolving to created user group details
 */
usergroups.create(options: UsergroupsCreateArguments): Promise<UsergroupsCreateResponse>;

interface UsergroupsCreateArguments extends TokenOverridable, OptionalTeamAssignable, UsergroupsIncludeCount {
  /** A name for the User Group (must be unique among User Groups) */
  name: string;
  /** Comma-separated string of encoded channel IDs for default channels */
  channels?: string;
  /** Short description of the User Group */
  description?: string;
  /** Mention handle (must be unique among channels, users and User Groups) */
  handle?: string;
}

interface UsergroupsIncludeCount {
  /** Include the number of users in each User Group */
  include_count?: boolean;
}

interface UsergroupsCreateResponse extends WebAPICallResult {
  /** The created user group object */
  usergroup?: Usergroup;
}
```

**Usage Examples:**

```typescript
import { WebClient } from "@slack/web-api";

const web = new WebClient(process.env.SLACK_BOT_TOKEN);

// Create a basic user group
const usergroup = await web.usergroups.create({
  name: "Engineering Team",
  handle: "engineering",
  description: "All engineering team members",
  include_count: true
});

// Create user group with default channels
await web.usergroups.create({
  name: "Marketing Team",
  handle: "marketing", 
  description: "Marketing department members",
  channels: "C1234567890,C0987654321" // Channel IDs
});
```

### List User Groups

Retrieve all user groups for the workspace.

```typescript { .api }
/**
 * List all User Groups for a team
 * @param options - Optional filtering parameters
 * @returns Promise resolving to list of user groups
 */
usergroups.list(options?: UsergroupsListArguments): Promise<UsergroupsListResponse>;

type UsergroupsListArguments = OptionalArgument<
  TokenOverridable &
  OptionalTeamAssignable &
  UsergroupsIncludeCount & {
    /** Include disabled User Groups */
    include_disabled?: boolean;
    /** Include the list of users for each User Group */
    include_users?: boolean;
  }
>;

interface UsergroupsListResponse extends WebAPICallResult {
  /** Array of user groups */
  usergroups?: Usergroup[];
}
```

**Usage Examples:**

```typescript
// Get all active user groups
const activeGroups = await web.usergroups.list({
  include_count: true
});

// Get all user groups including disabled ones
const allGroups = await web.usergroups.list({
  include_disabled: true,
  include_users: true,
  include_count: true
});

console.log(`Found ${allGroups.usergroups?.length} user groups`);
```

### Update User Group

Update an existing user group's properties.

```typescript { .api }
/**
 * Update an existing User Group
 * @param options - User group update parameters
 * @returns Promise resolving to updated user group details
 */
usergroups.update(options: UsergroupsUpdateArguments): Promise<UsergroupsUpdateResponse>;

interface UsergroupsUpdateArguments extends TokenOverridable, OptionalTeamAssignable, Partial<UsergroupsCreateArguments> {
  /** The encoded ID of the User Group to update */
  usergroup: string;
}

interface UsergroupsUpdateResponse extends WebAPICallResult {
  /** The updated user group object */
  usergroup?: Usergroup;
}
```

### Enable User Group

Enable a previously disabled user group.

```typescript { .api }
/**
 * Enable an existing User Group
 * @param options - User group enable parameters
 * @returns Promise resolving to enabled user group details
 */
usergroups.enable(options: UsergroupsEnableArguments): Promise<UsergroupsEnableResponse>;

interface UsergroupsEnableArguments extends TokenOverridable, OptionalTeamAssignable, UsergroupsIncludeCount {
  /** The encoded ID of the User Group to enable */
  usergroup: string;
}

interface UsergroupsEnableResponse extends WebAPICallResult {
  /** The enabled user group object */
  usergroup?: Usergroup;
}
```

### Disable User Group

Disable a user group (makes it inactive but preserves it).

```typescript { .api }
/**
 * Disable an existing User Group
 * @param options - User group disable parameters
 * @returns Promise resolving to disabled user group details
 */
usergroups.disable(options: UsergroupsDisableArguments): Promise<UsergroupsDisableResponse>;

interface UsergroupsDisableArguments extends TokenOverridable, OptionalTeamAssignable, UsergroupsIncludeCount {
  /** The encoded ID of the User Group to disable */
  usergroup: string;
}

interface UsergroupsDisableResponse extends WebAPICallResult {
  /** The disabled user group object */
  usergroup?: Usergroup;
}
```

### List Users in Group

List all users who are members of a specific user group.

```typescript { .api }
/**
 * List all users in a User Group
 * @param options - User group parameters
 * @returns Promise resolving to list of user IDs
 */
usergroups.users.list(options: UsergroupsUsersListArguments): Promise<UsergroupsUsersListResponse>;

interface UsergroupsUsersListArguments extends TokenOverridable, OptionalTeamAssignable {
  /** The encoded ID of the User Group to list users for */
  usergroup: string;
  /** Include disabled users */
  include_disabled?: boolean;
}

interface UsergroupsUsersListResponse extends WebAPICallResult {
  /** Array of user IDs in the group */
  users?: string[];
}
```

### Update Group Users

Update the list of users in a user group.

```typescript { .api }
/**
 * Update the list of users in a User Group
 * @param options - User group user update parameters
 * @returns Promise resolving to updated user group details
 */
usergroups.users.update(options: UsergroupsUsersUpdateArguments): Promise<UsergroupsUsersUpdateResponse>;

interface UsergroupsUsersUpdateArguments extends TokenOverridable, OptionalTeamAssignable, UsergroupsIncludeCount {
  /** The encoded ID of the User Group to update users for */
  usergroup: string;
  /** Comma-separated string of encoded user IDs */
  users: string;
}

interface UsergroupsUsersUpdateResponse extends WebAPICallResult {
  /** The updated user group object */
  usergroup?: Usergroup;
}
```

**Usage Examples:**

```typescript
// Update user group properties
await web.usergroups.update({
  usergroup: "S1234567890",
  name: "Senior Engineering Team",
  description: "Senior engineering team members",
  handle: "senior-eng"
});

// Enable/disable user groups
await web.usergroups.disable({
  usergroup: "S1234567890",
  include_count: true
});

await web.usergroups.enable({
  usergroup: "S1234567890", 
  include_count: true
});

// Manage user group membership
const currentUsers = await web.usergroups.users.list({
  usergroup: "S1234567890"
});

// Add new users to the group
await web.usergroups.users.update({
  usergroup: "S1234567890",
  users: "U1111111111,U2222222222,U3333333333"
});
```

## User Group Management Patterns

### Batch User Management

Efficiently manage user group membership:

```typescript
const addUsersToGroup = async (usergroupId: string, newUserIds: string[]) => {
  // Get current users
  const currentUsers = await web.usergroups.users.list({
    usergroup: usergroupId
  });
  
  // Combine current and new users
  const allUsers = [...(currentUsers.users || []), ...newUserIds];
  const uniqueUsers = [...new Set(allUsers)];
  
  // Update the group
  await web.usergroups.users.update({
    usergroup: usergroupId,
    users: uniqueUsers.join(',')
  });
};

const removeUsersFromGroup = async (usergroupId: string, removeUserIds: string[]) => {
  const currentUsers = await web.usergroups.users.list({
    usergroup: usergroupId
  });
  
  const remainingUsers = (currentUsers.users || [])
    .filter(userId => !removeUserIds.includes(userId));
  
  await web.usergroups.users.update({
    usergroup: usergroupId,
    users: remainingUsers.join(',')
  });
};
```

### Group Lifecycle Management

Complete user group lifecycle:

```typescript
const createManagedUserGroup = async (groupConfig: {
  name: string;
  handle: string; 
  description: string;
  initialUsers: string[];
  defaultChannels: string[];
}) => {
  // Create user group
  const result = await web.usergroups.create({
    name: groupConfig.name,
    handle: groupConfig.handle,
    description: groupConfig.description,
    channels: groupConfig.defaultChannels.join(','),
    include_count: true
  });
  
  const usergroupId = result.usergroup?.id;
  if (!usergroupId) throw new Error('Failed to create user group');
  
  // Add initial users
  if (groupConfig.initialUsers.length > 0) {
    await web.usergroups.users.update({
      usergroup: usergroupId,
      users: groupConfig.initialUsers.join(',')
    });
  }
  
  return result.usergroup;
};
```

## Core Types

```typescript { .api }
interface Usergroup {
  /** User group ID */
  id?: string;
  /** Team ID that owns the user group */
  team_id?: string;
  /** Whether the user group is active */
  is_external?: boolean;
  /** Timestamp when user group was created */
  date_create?: number;
  /** Timestamp when user group was last updated */
  date_update?: number;
  /** User ID who created the user group */
  created_by?: string;
  /** User ID who last updated the user group */
  updated_by?: string;
  /** User group name */
  name?: string;
  /** User group description */
  description?: string;
  /** User group handle (for mentions) */
  handle?: string;
  /** Whether user group is active */
  is_usergroup?: boolean;
  /** Whether user group can be mentioned */
  is_subteam?: boolean;
  /** Auto-provision settings */
  auto_provision?: boolean;
  /** Enterprise grid settings */
  enterprise_subteam_id?: string;
  /** Number of users in the group */
  user_count?: number;
  /** Array of user IDs in the group */
  users?: string[];
  /** Preferences object */
  prefs?: UsergroupPrefs;
}

interface UsergroupPrefs {
  /** Array of default channel IDs */
  channels?: string[];
  /** Array of default group IDs */
  groups?: string[];
}

interface OptionalTeamAssignable {
  /** Team ID for Enterprise Grid workspaces */
  team_id?: string;
}

interface TokenOverridable {
  /** Override the default token for this request */
  token?: string;
}
```