0
# User Groups
1

2
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.
3

4
## Capabilities
5

6
### Create User Group
7

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

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

18
interface UsergroupsCreateArguments extends TokenOverridable, OptionalTeamAssignable, UsergroupsIncludeCount {
19
  /** A name for the User Group (must be unique among User Groups) */
20
  name: string;
21
  /** Comma-separated string of encoded channel IDs for default channels */
22
  channels?: string;
23
  /** Short description of the User Group */
24
  description?: string;
25
  /** Mention handle (must be unique among channels, users and User Groups) */
26
  handle?: string;
27
}
28

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

34
interface UsergroupsCreateResponse extends WebAPICallResult {
35
  /** The created user group object */
36
  usergroup?: Usergroup;
37
}
38
```
39

40
**Usage Examples:**
41

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

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

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

55
// Create user group with default channels
56
await web.usergroups.create({
57
  name: "Marketing Team",
58
  handle: "marketing", 
59
  description: "Marketing department members",
60
  channels: "C1234567890,C0987654321" // Channel IDs
61
});
62
```
63

64
### List User Groups
65

66
Retrieve all user groups for the workspace.
67

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

76
type UsergroupsListArguments = OptionalArgument<
77
  TokenOverridable &
78
  OptionalTeamAssignable &
79
  UsergroupsIncludeCount & {
80
    /** Include disabled User Groups */
81
    include_disabled?: boolean;
82
    /** Include the list of users for each User Group */
83
    include_users?: boolean;
84
  }
85
>;
86

87
interface UsergroupsListResponse extends WebAPICallResult {
88
  /** Array of user groups */
89
  usergroups?: Usergroup[];
90
}
91
```
92

93
**Usage Examples:**
94

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

101
// Get all user groups including disabled ones
102
const allGroups = await web.usergroups.list({
103
  include_disabled: true,
104
  include_users: true,
105
  include_count: true
106
});
107

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

111
### Update User Group
112

113
Update an existing user group's properties.
114

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

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

128
interface UsergroupsUpdateResponse extends WebAPICallResult {
129
  /** The updated user group object */
130
  usergroup?: Usergroup;
131
}
132
```
133

134
### Enable User Group
135

136
Enable a previously disabled user group.
137

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

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

151
interface UsergroupsEnableResponse extends WebAPICallResult {
152
  /** The enabled user group object */
153
  usergroup?: Usergroup;
154
}
155
```
156

157
### Disable User Group
158

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

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

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

174
interface UsergroupsDisableResponse extends WebAPICallResult {
175
  /** The disabled user group object */
176
  usergroup?: Usergroup;
177
}
178
```
179

180
### List Users in Group
181

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

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

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

199
interface UsergroupsUsersListResponse extends WebAPICallResult {
200
  /** Array of user IDs in the group */
201
  users?: string[];
202
}
203
```
204

205
### Update Group Users
206

207
Update the list of users in a user group.
208

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

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

224
interface UsergroupsUsersUpdateResponse extends WebAPICallResult {
225
  /** The updated user group object */
226
  usergroup?: Usergroup;
227
}
228
```
229

230
**Usage Examples:**
231

232
```typescript
233
// Update user group properties
234
await web.usergroups.update({
235
  usergroup: "S1234567890",
236
  name: "Senior Engineering Team",
237
  description: "Senior engineering team members",
238
  handle: "senior-eng"
239
});
240

241
// Enable/disable user groups
242
await web.usergroups.disable({
243
  usergroup: "S1234567890",
244
  include_count: true
245
});
246

247
await web.usergroups.enable({
248
  usergroup: "S1234567890", 
249
  include_count: true
250
});
251

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

257
// Add new users to the group
258
await web.usergroups.users.update({
259
  usergroup: "S1234567890",
260
  users: "U1111111111,U2222222222,U3333333333"
261
});
262
```
263

264
## User Group Management Patterns
265

266
### Batch User Management
267

268
Efficiently manage user group membership:
269

270
```typescript
271
const addUsersToGroup = async (usergroupId: string, newUserIds: string[]) => {
272
  // Get current users
273
  const currentUsers = await web.usergroups.users.list({
274
    usergroup: usergroupId
275
  });
276
  
277
  // Combine current and new users
278
  const allUsers = [...(currentUsers.users || []), ...newUserIds];
279
  const uniqueUsers = [...new Set(allUsers)];
280
  
281
  // Update the group
282
  await web.usergroups.users.update({
283
    usergroup: usergroupId,
284
    users: uniqueUsers.join(',')
285
  });
286
};
287

288
const removeUsersFromGroup = async (usergroupId: string, removeUserIds: string[]) => {
289
  const currentUsers = await web.usergroups.users.list({
290
    usergroup: usergroupId
291
  });
292
  
293
  const remainingUsers = (currentUsers.users || [])
294
    .filter(userId => !removeUserIds.includes(userId));
295
  
296
  await web.usergroups.users.update({
297
    usergroup: usergroupId,
298
    users: remainingUsers.join(',')
299
  });
300
};
301
```
302

303
### Group Lifecycle Management
304

305
Complete user group lifecycle:
306

307
```typescript
308
const createManagedUserGroup = async (groupConfig: {
309
  name: string;
310
  handle: string; 
311
  description: string;
312
  initialUsers: string[];
313
  defaultChannels: string[];
314
}) => {
315
  // Create user group
316
  const result = await web.usergroups.create({
317
    name: groupConfig.name,
318
    handle: groupConfig.handle,
319
    description: groupConfig.description,
320
    channels: groupConfig.defaultChannels.join(','),
321
    include_count: true
322
  });
323
  
324
  const usergroupId = result.usergroup?.id;
325
  if (!usergroupId) throw new Error('Failed to create user group');
326
  
327
  // Add initial users
328
  if (groupConfig.initialUsers.length > 0) {
329
    await web.usergroups.users.update({
330
      usergroup: usergroupId,
331
      users: groupConfig.initialUsers.join(',')
332
    });
333
  }
334
  
335
  return result.usergroup;
336
};
337
```
338

339
## Core Types
340

341
```typescript { .api }
342
interface Usergroup {
343
  /** User group ID */
344
  id?: string;
345
  /** Team ID that owns the user group */
346
  team_id?: string;
347
  /** Whether the user group is active */
348
  is_external?: boolean;
349
  /** Timestamp when user group was created */
350
  date_create?: number;
351
  /** Timestamp when user group was last updated */
352
  date_update?: number;
353
  /** User ID who created the user group */
354
  created_by?: string;
355
  /** User ID who last updated the user group */
356
  updated_by?: string;
357
  /** User group name */
358
  name?: string;
359
  /** User group description */
360
  description?: string;
361
  /** User group handle (for mentions) */
362
  handle?: string;
363
  /** Whether user group is active */
364
  is_usergroup?: boolean;
365
  /** Whether user group can be mentioned */
366
  is_subteam?: boolean;
367
  /** Auto-provision settings */
368
  auto_provision?: boolean;
369
  /** Enterprise grid settings */
370
  enterprise_subteam_id?: string;
371
  /** Number of users in the group */
372
  user_count?: number;
373
  /** Array of user IDs in the group */
374
  users?: string[];
375
  /** Preferences object */
376
  prefs?: UsergroupPrefs;
377
}
378

379
interface UsergroupPrefs {
380
  /** Array of default channel IDs */
381
  channels?: string[];
382
  /** Array of default group IDs */
383
  groups?: string[];
384
}
385

386
interface OptionalTeamAssignable {
387
  /** Team ID for Enterprise Grid workspaces */
388
  team_id?: string;
389
}
390

391
interface TokenOverridable {
392
  /** Override the default token for this request */
393
  token?: string;
394
}
395
```