0
# User Operations
1

2
Retrieve user information, manage user profiles, and handle user presence.
3

4
## Capabilities
5

6
### Get User Information
7

8
Retrieve detailed information about users in the workspace.
9

10
```typescript { .api }
11
/**
12
 * Get information about a user
13
 * @param options - User info parameters
14
 * @returns Promise resolving to user details
15
 */
16
users.info(options: UsersInfoArguments): Promise<UsersInfoResponse>;
17

18
interface UsersInfoArguments {
19
  /** User ID to get info about */
20
  user: string;
21
  /** Include locale information in the response */
22
  include_locale?: boolean;
23
}
24
```
25

26
**Usage Examples:**
27

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

31
const web = new WebClient(token);
32

33
// Get basic user info
34
const userInfo = await web.users.info({
35
  user: 'U1234567890'
36
});
37

38
console.log('User name:', userInfo.user.name);
39
console.log('Display name:', userInfo.user.profile.display_name);
40
console.log('Email:', userInfo.user.profile.email);
41

42
// Get user info with locale
43
const detailedInfo = await web.users.info({
44
  user: 'U1234567890',
45
  include_locale: true
46
});
47

48
console.log('User locale:', detailedInfo.user.locale);
49
```
50

51
### List Users
52

53
Retrieve lists of users in the workspace with pagination support.
54

55
```typescript { .api }
56
/**
57
 * List users in the workspace
58
 * @param options - List parameters
59
 * @returns Promise resolving to users list
60
 */
61
users.list(options?: UsersListArguments): Promise<UsersListResponse>;
62

63
interface UsersListArguments {
64
  /** Cursor for pagination */
65
  cursor?: string;
66
  /** Include deactivated users */
67
  include_locale?: boolean;
68
  /** Maximum number of users to return (1-1000, default: 0 for all) */
69
  limit?: number;
70
  /** Team ID (Enterprise Grid) */
71
  team_id?: string;
72
}
73
```
74

75
**Usage Examples:**
76

77
```typescript
78
// List all active users
79
const users = await web.users.list();
80

81
console.log(`Found ${users.members.length} users`);
82

83
// List users with pagination
84
const activeUsers = [];
85
for await (const page of web.paginate('users.list', { limit: 100 })) {
86
  const active = page.members.filter(user => !user.deleted && !user.is_bot);
87
  activeUsers.push(...active);
88
}
89

90
console.log(`Found ${activeUsers.length} active human users`);
91
```
92

93
### Lookup User by Email
94

95
Find users by their email address.
96

97
```typescript { .api }
98
/**
99
 * Look up a user by email address
100
 * @param options - Lookup parameters
101
 * @returns Promise resolving to user details
102
 */
103
users.lookupByEmail(options: UsersLookupByEmailArguments): Promise<UsersLookupByEmailResponse>;
104

105
interface UsersLookupByEmailArguments {
106
  /** Email address to look up */
107
  email: string;
108
}
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
// Find user by email
115
const user = await web.users.lookupByEmail({
116
  email: 'john.doe@company.com'
117
});
118

119
console.log('Found user:', user.user.id);
120
console.log('Display name:', user.user.profile.display_name);
121
```
122

123
### User Profile Management
124

125
Get and update user profile information.
126

127
```typescript { .api }
128
/**
129
 * Get a user's profile information
130
 * @param options - Profile get parameters
131
 * @returns Promise resolving to profile details
132
 */
133
users.profile.get(options?: UsersProfileGetArguments): Promise<UsersProfileGetResponse>;
134

135
/**
136
 * Set a user's profile information
137
 * @param options - Profile set parameters
138
 * @returns Promise resolving to updated profile
139
 */
140
users.profile.set(options: UsersProfileSetArguments): Promise<UsersProfileSetResponse>;
141

142
interface UsersProfileGetArguments {
143
  /** Include labels for each ID in custom profile fields */
144
  include_labels?: boolean;
145
  /** User ID to get profile for (defaults to authed user) */
146
  user?: string;
147
}
148

149
interface UsersProfileSetArguments {
150
  /** Name of the profile field to set */
151
  name?: string;
152
  /** JSON-encoded profile object to update */
153
  profile?: string;
154
  /** User ID to set profile for (admins only) */
155
  user?: string;
156
  /** Value to set for the profile field */
157
  value?: string;
158
}
159
```
160

161
**Usage Examples:**
162

163
```typescript
164
// Get current user's profile
165
const profile = await web.users.profile.get();
166

167
console.log('Current status:', profile.profile.status_text);
168
console.log('Phone:', profile.profile.phone);
169

170
// Get another user's profile
171
const otherProfile = await web.users.profile.get({
172
  user: 'U1234567890',
173
  include_labels: true
174
});
175

176
// Update current user's status
177
await web.users.profile.set({
178
  profile: JSON.stringify({
179
    status_text: 'In a meeting',
180
    status_emoji: ':calendar:'
181
  })
182
});
183

184
// Update specific profile field
185
await web.users.profile.set({
186
  name: 'phone', 
187
  value: '+1-555-123-4567'
188
});
189
```
190

191
### User Presence
192

193
Manage and retrieve user presence information.
194

195
```typescript { .api }
196
/**
197
 * Get a user's presence status
198
 * @param options - Presence parameters
199
 * @returns Promise resolving to presence info
200
 */
201
users.getPresence(options: UsersGetPresenceArguments): Promise<UsersGetPresenceResponse>;
202

203
/**
204
 * Set the current user's presence
205
 * @param options - Presence set parameters
206
 * @returns Promise resolving to presence update result
207
 */
208
users.setPresence(options: UsersSetPresenceArguments): Promise<UsersSetPresenceResponse>;
209

210
interface UsersGetPresenceArguments {
211
  /** User ID to get presence for */
212
  user: string;
213
}
214

215
interface UsersSetPresenceArguments {
216
  /** Presence to set ('auto' or 'away') */
217
  presence: 'auto' | 'away';
218
}
219
```
220

221
**Usage Examples:**
222

223
```typescript
224
// Get user's presence
225
const presence = await web.users.getPresence({
226
  user: 'U1234567890'
227
});
228

229
console.log('User presence:', presence.presence); // 'active' or 'away'
230
console.log('Online status:', presence.online); // true or false
231

232
// Set current user to away
233
await web.users.setPresence({
234
  presence: 'away'
235
});
236

237
// Set current user to auto (active when using Slack)
238
await web.users.setPresence({
239
  presence: 'auto'
240
});
241
```
242

243
### User Photo Management
244

245
Upload and manage user profile photos.
246

247
```typescript { .api }
248
/**
249
 * Set a user's profile photo
250
 * @param options - Photo set parameters
251
 * @returns Promise resolving to photo update result
252
 */
253
users.setPhoto(options: UsersSetPhotoArguments): Promise<UsersSetPhotoResponse>;
254

255
/**
256
 * Delete a user's profile photo
257
 * @param options - Photo delete parameters
258
 * @returns Promise resolving to deletion result
259
 */
260
users.deletePhoto(options?: UsersDeletePhotoArguments): Promise<UsersDeletePhotoResponse>;
261

262
interface UsersSetPhotoArguments {
263
  /** Height of crop box (default: full image height) */
264
  crop_h?: number;
265
  /** Width of crop box (default: full image width) */
266
  crop_w?: number;
267
  /** X coordinate of top-left corner of crop box */
268
  crop_x?: number;
269
  /** Y coordinate of top-left corner of crop box */
270
  crop_y?: number;
271
  /** Image data as multipart/form-data */
272
  image?: Buffer | NodeJS.ReadableStream;
273
}
274

275
interface UsersDeletePhotoArguments {
276
  /** Token for the user whose photo will be deleted */
277
  token?: string;
278
}
279
```
280

281
**Usage Examples:**
282

283
```typescript
284
import { createReadStream } from 'fs';
285

286
// Set profile photo from file
287
await web.users.setPhoto({
288
  image: createReadStream('./profile-photo.jpg'),
289
  crop_x: 10,
290
  crop_y: 10,
291
  crop_w: 200,
292
  crop_h: 200
293
});
294

295
// Delete current profile photo
296
await web.users.deletePhoto();
297
```
298

299
### User Identity
300

301
Get identity information for the authenticated user (for OAuth apps).
302

303
```typescript { .api }
304
/**
305
 * Get identity information about the current user
306
 * @param options - Identity parameters
307
 * @returns Promise resolving to identity details
308
 */
309
users.identity(options?: UsersIdentityArguments): Promise<UsersIdentityResponse>;
310

311
interface UsersIdentityArguments {
312
  /** Token for the user */
313
  token?: string;
314
}
315
```
316

317
**Usage Examples:**
318

319
```typescript
320
// Get current user identity (useful for OAuth apps)
321
const identity = await web.users.identity();
322

323
console.log('User ID:', identity.user.id);
324
console.log('Team ID:', identity.team.id);
325
console.log('User name:', identity.user.name);
326
```
327

328
### User Conversations
329

330
List conversations that a user is a member of.
331

332
```typescript { .api }
333
/**
334
 * List conversations the user is a member of
335
 * @param options - Conversations parameters
336
 * @returns Promise resolving to conversations list
337
 */
338
users.conversations(options?: UsersConversationsArguments): Promise<UsersConversationsResponse>;
339

340
interface UsersConversationsArguments {
341
  /** Cursor for pagination */
342
  cursor?: string;
343
  /** Set to true to exclude archived channels from the list */
344
  exclude_archived?: boolean;
345
  /** Maximum number of conversations to return */
346
  limit?: number;
347
  /** Team ID (Enterprise Grid) */
348
  team_id?: string;
349
  /** Mix and match conversation types to return */
350
  types?: string;
351
  /** Browse conversations by a specific user ID's membership */
352
  user?: string;
353
}
354
```
355

356
**Usage Examples:**
357

358
```typescript
359
// List current user's conversations
360
const myConversations = await web.users.conversations({
361
  exclude_archived: true,
362
  types: 'public_channel,private_channel,mpim,im'
363
});
364

365
console.log(`User is in ${myConversations.channels.length} conversations`);
366

367
// List another user's public channels
368
const userChannels = await web.users.conversations({
369
  user: 'U1234567890',
370
  types: 'public_channel',
371
  limit: 100
372
});
373
```
374

375
### Discoverable Contacts
376

377
Look up users who can be contacted outside the workspace.
378

379
```typescript { .api }
380
/**
381
 * Look up discoverable contacts
382
 * @param options - Lookup parameters
383
 * @returns Promise resolving to contact details
384
 */
385
users.discoverableContacts.lookup(options: UsersDiscoverableContactsLookupArguments): Promise<UsersDiscoverableContactsLookupResponse>;
386

387
interface UsersDiscoverableContactsLookupArguments {
388
  /** Email address to look up */
389
  email: string;
390
}
391
```
392

393
**Usage Examples:**
394

395
```typescript
396
// Look up external contact
397
const contact = await web.users.discoverableContacts.lookup({
398
  email: 'external.contact@otherdomain.com'
399
});
400

401
if (contact.ok) {
402
  console.log('Contact found:', contact.user.name);
403
}
404
```
405

406
## Types
407

408
```typescript { .api }
409
interface UsersInfoResponse extends WebAPICallResult {
410
  user: {
411
    id: string;
412
    team_id: string;
413
    name: string;
414
    deleted: boolean;
415
    color: string;
416
    real_name: string;
417
    tz: string;
418
    tz_label: string;
419
    tz_offset: number;
420
    profile: UserProfile;
421
    is_admin: boolean;
422
    is_owner: boolean;
423
    is_primary_owner: boolean;
424
    is_restricted: boolean;
425
    is_ultra_restricted: boolean;
426
    is_bot: boolean;
427
    is_app_user: boolean;
428
    updated: number;
429
    is_email_confirmed: boolean;
430
    who_can_share_contact_card: string;
431
    locale?: string;
432
  };
433
}
434

435
interface UserProfile {
436
  title: string;
437
  phone: string;
438
  skype: string;
439
  real_name: string;
440
  real_name_normalized: string;
441
  display_name: string;
442
  display_name_normalized: string;
443
  fields: { [key: string]: UserProfileField };
444
  status_text: string;
445
  status_emoji: string;
446
  status_expiration: number;
447
  avatar_hash: string;
448
  email: string;
449
  first_name: string;
450
  last_name: string;
451
  image_24: string;
452
  image_32: string;
453
  image_48: string;
454
  image_72: string;
455
  image_192: string;
456
  image_512: string;
457
  status_text_canonical: string;
458
  team: string;
459
}
460

461
interface UserProfileField {
462
  value: string;
463
  alt: string;
464
  label?: string;
465
}
466

467
interface UsersListResponse extends WebAPICallResult {
468
  members: UsersInfoResponse['user'][];
469
  cache_ts: number;
470
  response_metadata?: {
471
    next_cursor?: string;
472
  };
473
}
474

475
interface UsersGetPresenceResponse extends WebAPICallResult {
476
  presence: 'active' | 'away';
477
  online: boolean;
478
  auto_away?: boolean;
479
  manual_away?: boolean;
480
  connection_count?: number;
481
  last_activity?: number;
482
}
483
```