0
# Conversation Management
1

2
Create, manage, and interact with Slack channels, groups, and direct messages.
3

4
## Capabilities
5

6
### Create Conversations
7

8
Create new channels or groups with specific settings and permissions.
9

10
```typescript { .api }
11
/**
12
 * Create a new conversation (channel or group)
13
 * @param options - Creation parameters
14
 * @returns Promise resolving to new conversation details
15
 */
16
conversations.create(options: ConversationsCreateArguments): Promise<ConversationsCreateResponse>;
17

18
interface ConversationsCreateArguments {
19
  /** Name of the conversation to create */
20
  name: string;
21
  /** Whether the conversation should be private */
22
  is_private?: boolean;
23
  /** Team ID to create the conversation in (Enterprise Grid) */
24
  team_id?: string;
25
}
26
```
27

28
**Usage Examples:**
29

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

33
const web = new WebClient(token);
34

35
// Create public channel
36
const publicChannel = await web.conversations.create({
37
  name: 'project-alpha',
38
  is_private: false
39
});
40

41
// Create private channel  
42
const privateChannel = await web.conversations.create({
43
  name: 'confidential-planning',
44
  is_private: true
45
});
46

47
console.log('Created channel:', publicChannel.channel.id);
48
```
49

50
### List Conversations
51

52
Retrieve lists of channels, groups, and direct messages.
53

54
```typescript { .api }
55
/**
56
 * List conversations the user has access to
57
 * @param options - List parameters
58
 * @returns Promise resolving to conversations list
59
 */
60
conversations.list(options?: ConversationsListArguments): Promise<ConversationsListResponse>;
61

62
interface ConversationsListArguments {
63
  /** Paginate through collections of data by cursor */
64
  cursor?: string;
65
  /** Set to true to exclude archived channels */
66
  exclude_archived?: boolean;
67
  /** Maximum number of conversations to return (1-1000, default: 100) */
68
  limit?: number;
69
  /** Mix and match conversation types (public_channel, private_channel, mpim, im) */
70
  types?: string;
71
  /** Team ID (Enterprise Grid) */
72
  team_id?: string;
73
}
74
```
75

76
**Usage Examples:**
77

78
```typescript
79
// List all public channels
80
const publicChannels = await web.conversations.list({
81
  types: 'public_channel',
82
  exclude_archived: true,
83
  limit: 200
84
});
85

86
// List all conversation types
87
const allConversations = await web.conversations.list({
88
  types: 'public_channel,private_channel,mpim,im'
89
});
90

91
// Paginate through all channels
92
let cursor;
93
const allChannels = [];
94
do {
95
  const result = await web.conversations.list({
96
    types: 'public_channel,private_channel',
97
    cursor,
98
    limit: 100
99
  });
100
  
101
  allChannels.push(...result.channels);
102
  cursor = result.response_metadata?.next_cursor;
103
} while (cursor);
104
```
105

106
### Get Conversation Info
107

108
Retrieve detailed information about specific conversations.
109

110
```typescript { .api }
111
/**
112
 * Get information about a conversation
113
 * @param options - Info parameters
114
 * @returns Promise resolving to conversation details
115
 */
116
conversations.info(options: ConversationsInfoArguments): Promise<ConversationsInfoResponse>;
117

118
interface ConversationsInfoArguments {
119
  /** Conversation ID to get info about */
120
  channel: string;
121
  /** Include number of members in the response */
122
  include_num_members?: boolean;
123
  /** Include locale information */
124
  include_locale?: boolean;
125
}
126
```
127

128
**Usage Examples:**
129

130
```typescript
131
// Get basic channel info
132
const channelInfo = await web.conversations.info({
133
  channel: 'C1234567890'
134
});
135

136
console.log('Channel name:', channelInfo.channel.name);
137
console.log('Is archived:', channelInfo.channel.is_archived);
138

139
// Get channel info with member count
140
const detailedInfo = await web.conversations.info({
141
  channel: 'C1234567890',
142
  include_num_members: true
143
});
144

145
console.log('Member count:', detailedInfo.channel.num_members);
146
```
147

148
### Manage Conversation Members
149

150
Add, remove, and list members in conversations.
151

152
```typescript { .api }
153
/**
154
 * Invite users to a conversation
155
 * @param options - Invitation parameters
156
 * @returns Promise resolving to invitation result
157
 */
158
conversations.invite(options: ConversationsInviteArguments): Promise<ConversationsInviteResponse>;
159

160
/**
161
 * Remove a user from a conversation
162
 * @param options - Removal parameters
163
 * @returns Promise resolving to removal result
164
 */
165
conversations.kick(options: ConversationsKickArguments): Promise<ConversationsKickResponse>;
166

167
/**
168
 * List members of a conversation
169
 * @param options - List parameters
170
 * @returns Promise resolving to members list
171
 */
172
conversations.members(options: ConversationsMembersArguments): Promise<ConversationsMembersResponse>;
173

174
interface ConversationsInviteArguments {
175
  /** Conversation to invite users to */
176
  channel: string;
177
  /** Comma-separated list of user IDs */
178
  users: string;
179
}
180

181
interface ConversationsKickArguments {
182
  /** Conversation to remove user from */
183
  channel: string;
184
  /** User ID to remove */
185
  user: string;
186
}
187

188
interface ConversationsMembersArguments {
189
  /** Conversation to list members for */
190
  channel: string;
191
  /** Cursor for pagination */
192
  cursor?: string;
193
  /** Maximum number of members to return */
194
  limit?: number;
195
}
196
```
197

198
**Usage Examples:**
199

200
```typescript
201
// Invite users to channel
202
await web.conversations.invite({
203
  channel: 'C1234567890',
204
  users: 'U1111111111,U2222222222,U3333333333'
205
});
206

207
// Remove user from channel
208
await web.conversations.kick({
209
  channel: 'C1234567890',
210
  user: 'U1111111111'
211
});
212

213
// List all channel members
214
const members = [];
215
for await (const page of web.paginate('conversations.members', {
216
  channel: 'C1234567890'
217
})) {
218
  members.push(...page.members);
219
}
220

221
console.log(`Channel has ${members.length} members`);
222
```
223

224
### Join and Leave Conversations
225

226
Join conversations or leave them.
227

228
```typescript { .api }
229
/**
230
 * Join an existing conversation
231
 * @param options - Join parameters
232
 * @returns Promise resolving to join result
233
 */
234
conversations.join(options: ConversationsJoinArguments): Promise<ConversationsJoinResponse>;
235

236
/**
237
 * Leave a conversation
238
 * @param options - Leave parameters
239
 * @returns Promise resolving to leave result
240
 */
241
conversations.leave(options: ConversationsLeaveArguments): Promise<ConversationsLeaveResponse>;
242

243
interface ConversationsJoinArguments {
244
  /** Conversation to join */
245
  channel: string;
246
}
247

248
interface ConversationsLeaveArguments {
249
  /** Conversation to leave */
250
  channel: string;
251
}
252
```
253

254
**Usage Examples:**
255

256
```typescript
257
// Join a public channel
258
await web.conversations.join({
259
  channel: 'C1234567890'
260
});
261

262
// Leave a conversation
263
await web.conversations.leave({
264
  channel: 'C1234567890'
265
});
266
```
267

268
### Archive and Unarchive
269

270
Archive or unarchive conversations.
271

272
```typescript { .api }
273
/**
274
 * Archive a conversation
275
 * @param options - Archive parameters
276
 * @returns Promise resolving to archive result
277
 */
278
conversations.archive(options: ConversationsArchiveArguments): Promise<ConversationsArchiveResponse>;
279

280
/**
281
 * Unarchive a conversation
282
 * @param options - Unarchive parameters
283
 * @returns Promise resolving to unarchive result  
284
 */
285
conversations.unarchive(options: ConversationsUnarchiveArguments): Promise<ConversationsUnarchiveResponse>;
286

287
interface ConversationsArchiveArguments {
288
  /** Conversation to archive */
289
  channel: string;
290
}
291

292
interface ConversationsUnarchiveArguments {
293
  /** Conversation to unarchive */
294
  channel: string;
295
}
296
```
297

298
**Usage Examples:**
299

300
```typescript
301
// Archive a channel
302
await web.conversations.archive({
303
  channel: 'C1234567890'
304
});
305

306
// Unarchive a channel
307
await web.conversations.unarchive({
308
  channel: 'C1234567890'
309
});
310
```
311

312
### Set Channel Properties
313

314
Update channel topic, purpose, and name.
315

316
```typescript { .api }
317
/**
318
 * Set the topic of a conversation
319
 * @param options - Topic parameters
320
 * @returns Promise resolving to topic update result
321
 */
322
conversations.setTopic(options: ConversationsSetTopicArguments): Promise<ConversationsSetTopicResponse>;
323

324
/**
325
 * Set the purpose of a conversation
326
 * @param options - Purpose parameters
327
 * @returns Promise resolving to purpose update result
328
 */
329
conversations.setPurpose(options: ConversationsSetPurposeArguments): Promise<ConversationsSetPurposeResponse>;
330

331
/**
332
 * Rename a conversation
333
 * @param options - Rename parameters
334
 * @returns Promise resolving to rename result
335
 */
336
conversations.rename(options: ConversationsRenameArguments): Promise<ConversationsRenameResponse>;
337

338
interface ConversationsSetTopicArguments {
339
  /** Conversation to set topic for */
340
  channel: string;
341
  /** New topic text */
342
  topic: string;
343
}
344

345
interface ConversationsSetPurposeArguments {
346
  /** Conversation to set purpose for */
347
  channel: string;
348
  /** New purpose text */
349
  purpose: string;
350
}
351

352
interface ConversationsRenameArguments {
353
  /** Conversation to rename */
354
  channel: string;
355
  /** New name for conversation */
356
  name: string;
357
}
358
```
359

360
**Usage Examples:**
361

362
```typescript
363
// Set channel topic
364
await web.conversations.setTopic({
365
  channel: 'C1234567890',
366
  topic: 'Weekly team updates and announcements'
367
});
368

369
// Set channel purpose
370
await web.conversations.setPurpose({
371
  channel: 'C1234567890',
372
  purpose: 'Discuss project alpha development progress'
373
});
374

375
// Rename channel
376
await web.conversations.rename({
377
  channel: 'C1234567890',
378
  name: 'project-alpha-v2'
379
});
380
```
381

382
### Conversation History
383

384
Retrieve message history from conversations.
385

386
```typescript { .api }
387
/**
388
 * Get conversation history
389
 * @param options - History parameters
390
 * @returns Promise resolving to message history
391
 */
392
conversations.history(options: ConversationsHistoryArguments): Promise<ConversationsHistoryResponse>;
393

394
/**
395
 * Get replies to a message
396
 * @param options - Replies parameters
397
 * @returns Promise resolving to thread replies
398
 */
399
conversations.replies(options: ConversationsRepliesArguments): Promise<ConversationsRepliesResponse>;
400

401
interface ConversationsHistoryArguments {
402
  /** Conversation to fetch history for */
403
  channel: string;
404
  /** Cursor for pagination */
405
  cursor?: string;
406
  /** Include all metadata associated with this channel */
407
  include_all_metadata?: boolean;
408
  /** Return messages with oldest timestamp in list (default: false) */
409
  inclusive?: boolean;
410
  /** End of time range of messages to include */
411
  latest?: string;
412
  /** Maximum number of messages to return (1-1000, default: 100) */
413
  limit?: number;
414
  /** Start of time range of messages to include */
415
  oldest?: string;
416
}
417

418
interface ConversationsRepliesArguments {
419
  /** Conversation to fetch thread from */
420
  channel: string;
421
  /** Thread timestamp */
422
  ts: string;
423
  /** Cursor for pagination */
424
  cursor?: string;
425
  /** Return messages with oldest timestamp in list */
426
  inclusive?: boolean;
427
  /** End of time range */
428
  latest?: string;
429
  /** Maximum number of messages to return */
430
  limit?: number;
431
  /** Start of time range */
432
  oldest?: string;
433
}
434
```
435

436
**Usage Examples:**
437

438
```typescript
439
// Get recent messages
440
const history = await web.conversations.history({
441
  channel: 'C1234567890',
442
  limit: 50
443
});
444

445
console.log(`Retrieved ${history.messages.length} messages`);
446

447
// Get messages from specific time range
448
const todayStart = Math.floor(new Date().setHours(0, 0, 0, 0) / 1000);
449
const todayMessages = await web.conversations.history({
450
  channel: 'C1234567890',
451
  oldest: todayStart.toString(),
452
  limit: 1000
453
});
454

455
// Get thread replies
456
const threadReplies = await web.conversations.replies({
457
  channel: 'C1234567890',
458
  ts: '1234567890.123456'
459
});
460

461
console.log(`Thread has ${threadReplies.messages.length} replies`);
462
```
463

464
### Direct Messages
465

466
Open and manage direct message conversations.
467

468
```typescript { .api }
469
/**
470
 * Open a direct message conversation
471
 * @param options - Open parameters
472
 * @returns Promise resolving to DM channel info
473
 */
474
conversations.open(options: ConversationsOpenArguments): Promise<ConversationsOpenResponse>;
475

476
/**
477
 * Close a direct message conversation
478
 * @param options - Close parameters
479
 * @returns Promise resolving to close result
480
 */
481
conversations.close(options: ConversationsCloseArguments): Promise<ConversationsCloseResponse>;
482

483
interface ConversationsOpenArguments {
484
  /** User ID to open DM with */
485
  users?: string;
486
  /** Conversation ID to reopen */
487
  channel?: string;
488
  /** Set to true to prevent creating a new conversation */
489
  prevent_creation?: boolean;
490
  /** Set to true to return existing conversation */
491
  return_im?: boolean;
492
}
493

494
interface ConversationsCloseArguments {
495
  /** Conversation to close */
496
  channel: string;
497
}
498
```
499

500
**Usage Examples:**
501

502
```typescript
503
// Open DM with single user
504
const dm = await web.conversations.open({
505
  users: 'U1234567890'
506
});
507

508
console.log('DM channel ID:', dm.channel.id);
509

510
// Open group DM with multiple users
511
const groupDM = await web.conversations.open({
512
  users: 'U1234567890,U2222222222,U3333333333'
513
});
514

515
// Close a DM
516
await web.conversations.close({
517
  channel: 'D1234567890'
518
});
519
```
520

521
## Types
522

523
```typescript { .api }
524
interface ConversationsCreateResponse extends WebAPICallResult {
525
  channel: {
526
    id: string;
527
    name: string;
528
    is_channel: boolean;
529
    is_group: boolean;
530
    is_im: boolean;
531
    is_mpim: boolean;
532
    is_private: boolean;
533
    created: number;
534
    creator: string;
535
    is_archived: boolean;
536
    is_general: boolean;
537
    unlinked: number;
538
    name_normalized: string;
539
    is_shared: boolean;
540
    is_org_shared: boolean;
541
    context_team_id: string;
542
    updated: number;
543
    parent_conversation?: string;
544
    pending_shared?: string[];
545
    pending_connected_team_ids?: string[];
546
    is_pending_ext_shared?: boolean;
547
  };
548
}
549

550
interface ConversationsListResponse extends WebAPICallResult {
551
  channels: Conversation[];
552
  response_metadata?: {
553
    next_cursor?: string;
554
  };
555
}
556

557
interface Conversation {
558
  id: string;
559
  name?: string;
560
  is_channel: boolean;
561
  is_group: boolean;
562
  is_im: boolean;
563
  is_mpim: boolean;
564
  is_private: boolean;
565
  created: number;
566
  creator?: string;
567
  is_archived: boolean;
568
  is_general?: boolean;
569
  unlinked?: number;
570
  name_normalized?: string;
571
  is_shared: boolean;
572
  is_org_shared: boolean;
573
  context_team_id?: string;
574
  updated: number;
575
  topic?: {
576
    value: string;
577
    creator: string;
578
    last_set: number;
579
  };
580
  purpose?: {
581
    value: string;
582
    creator: string;
583
    last_set: number;
584
  };
585
  num_members?: number;
586
}
587
```