0
# File Operations
1

2
Upload files, manage file permissions, and interact with Slack's file storage system.
3

4
## Capabilities
5

6
### File Upload V2 (Recommended)
7

8
Modern file upload implementation using Slack's external upload flow for better performance and reliability.
9

10
```typescript { .api }
11
/**
12
 * Upload files using the v2 external upload method
13
 * @param options - File upload configuration
14
 * @returns Promise resolving to upload results with file details
15
 */
16
files.uploadV2(options: FilesUploadV2Arguments): Promise<WebAPICallResult & {
17
  files: FilesCompleteUploadExternalResponse[];
18
}>;
19

20
interface FilesUploadV2Arguments {
21
  /** Channel ID where the file will be shared */
22
  channel_id?: string;
23
  /** Channel names where the file will be shared (comma-separated) */
24
  channels?: string;
25
  /** Title of the file */
26
  title?: string;
27
  /** File content as Buffer, Stream, or string */
28
  file?: Buffer | NodeJS.ReadableStream | string;
29
  /** Filename for the uploaded file */
30
  filename?: string;
31
  /** File type/extension */
32
  filetype?: string;
33
  /** Alternative file content (for text files) */
34
  content?: string;
35
  /** Initial comment to add with the file */
36
  initial_comment?: string;
37
  /** Thread timestamp to upload file to a specific thread */
38
  thread_ts?: string;
39
  /** Alt text for accessibility */
40
  alt_text?: string;
41
  /** Snippet type for code files */
42
  snippet_type?: string;
43
}
44
```
45

46
**Usage Examples:**
47

48
```typescript
49
import { WebClient } from "@slack/web-api";
50
import { createReadStream } from "fs";
51

52
const web = new WebClient(token);
53

54
// Upload file from filesystem
55
const result = await web.files.uploadV2({
56
  channels: '#general',
57
  file: createReadStream('./report.pdf'),
58
  filename: 'monthly-report.pdf',
59
  title: 'Monthly Sales Report',
60
  initial_comment: 'Here is this month\'s sales report with key metrics.'
61
});
62

63
console.log('Uploaded files:', result.files.map(f => f.id));
64

65
// Upload text content as a file
66
await web.files.uploadV2({
67
  channels: 'D1234567890', // Direct message
68
  content: JSON.stringify({ data: 'example' }, null, 2),
69
  filename: 'data.json',
70
  filetype: 'json',
71
  title: 'Sample Data'
72
});
73

74
// Upload to specific thread with alt text
75
await web.files.uploadV2({
76
  channel_id: 'C1234567890',
77
  file: Buffer.from('Debug info:\n\nError occurred at line 42'),
78
  filename: 'debug.log',
79
  thread_ts: '1234567890.123456',
80
  alt_text: 'Debug log file showing error details'
81
});
82

83
// Upload code snippet
84
await web.files.uploadV2({
85
  channels: '#dev-team',
86
  content: `
87
function greet(name) {
88
  return \`Hello, \${name}!\`;
89
}
90
  `.trim(),
91
  filename: 'greeting.js',
92
  snippet_type: 'javascript',
93
  title: 'Greeting Function'
94
});
95
```
96

97
### File Information
98

99
Retrieve detailed information about uploaded files.
100

101
```typescript { .api }
102
/**
103
 * Get information about a file
104
 * @param options - File info parameters
105
 * @returns Promise resolving to file details
106
 */
107
files.info(options: FilesInfoArguments): Promise<FilesInfoResponse>;
108

109
interface FilesInfoArguments {
110
  /** File ID to get info about */
111
  file: string;
112
  /** Number of items to return per page for comments */
113
  count?: number;
114
  /** Page number of comments to return */
115
  page?: number;
116
}
117
```
118

119
**Usage Examples:**
120

121
```typescript
122
// Get basic file information
123
const fileInfo = await web.files.info({
124
  file: 'F1234567890'
125
});
126

127
console.log('File name:', fileInfo.file.name);
128
console.log('File size:', fileInfo.file.size, 'bytes');
129
console.log('File type:', fileInfo.file.pretty_type);
130
console.log('Created by:', fileInfo.file.user);
131

132
// Get file info with comments
133
const fileWithComments = await web.files.info({
134
  file: 'F1234567890',
135
  count: 50,
136
  page: 1
137
});
138

139
console.log('Comments:', fileWithComments.comments);
140
```
141

142
### List Files
143

144
Retrieve lists of files with filtering and pagination.
145

146
```typescript { .api }
147
/**
148
 * List files uploaded to the workspace
149
 * @param options - List parameters
150
 * @returns Promise resolving to files list
151
 */
152
files.list(options?: FilesListArguments): Promise<FilesListResponse>;
153

154
interface FilesListArguments {
155
  /** Filter files by user ID */
156
  user?: string;
157
  /** Filter files by channel ID */
158
  channel?: string;
159
  /** Filter by file type (e.g., 'images', 'pdfs', 'zips') */
160
  types?: string;
161
  /** End of time range of files to include */
162
  ts_to?: number;
163
  /** Start of time range of files to include */
164
  ts_from?: number;
165
  /** Number of items to return per page */
166
  count?: number;
167
  /** Page number to return */
168
  page?: number;
169
  /** Show files hidden by limit */
170
  show_files_hidden_by_limit?: boolean;
171
}
172
```
173

174
**Usage Examples:**
175

176
```typescript
177
// List recent files
178
const recentFiles = await web.files.list({
179
  count: 20,
180
  page: 1
181
});
182

183
console.log(`Found ${recentFiles.files.length} files`);
184

185
// List files by specific user
186
const userFiles = await web.files.list({
187
  user: 'U1234567890',
188
  count: 50
189
});
190

191
// List files in specific channel
192
const channelFiles = await web.files.list({
193
  channel: 'C1234567890',
194
  count: 100
195
});
196

197
// List files by type and date range
198
const lastWeek = Math.floor((Date.now() - 7 * 24 * 60 * 60 * 1000) / 1000);
199
const imageFiles = await web.files.list({
200
  types: 'images',
201
  ts_from: lastWeek,
202
  count: 30
203
});
204
```
205

206
### Delete Files
207

208
Remove files from the workspace.
209

210
```typescript { .api }
211
/**
212
 * Delete a file
213
 * @param options - Delete parameters
214
 * @returns Promise resolving to deletion confirmation
215
 */
216
files.delete(options: FilesDeleteArguments): Promise<FilesDeleteResponse>;
217

218
interface FilesDeleteArguments {
219
  /** File ID to delete */
220
  file: string;
221
}
222
```
223

224
**Usage Examples:**
225

226
```typescript
227
// Delete a file
228
const result = await web.files.delete({
229
  file: 'F1234567890'
230
});
231

232
if (result.ok) {
233
  console.log('File deleted successfully');
234
}
235

236
// Delete multiple files
237
const filesToDelete = ['F1111111111', 'F2222222222', 'F3333333333'];
238

239
for (const fileId of filesToDelete) {
240
  try {
241
    await web.files.delete({ file: fileId });
242
    console.log(`Deleted file: ${fileId}`);
243
  } catch (error) {
244
    console.error(`Failed to delete file ${fileId}:`, error.message);
245
  }
246
}
247
```
248

249
### Public URL Management
250

251
Manage public sharing URLs for files.
252

253
```typescript { .api }
254
/**
255
 * Enable public sharing for a file and get the URL
256
 * @param options - Share parameters
257
 * @returns Promise resolving to public URL details
258
 */
259
files.sharedPublicURL(options: FilesSharedPublicURLArguments): Promise<FilesSharedPublicURLResponse>;
260

261
/**
262
 * Revoke public sharing for a file
263
 * @param options - Revoke parameters
264
 * @returns Promise resolving to revocation confirmation
265
 */
266
files.revokePublicURL(options: FilesRevokePublicURLArguments): Promise<FilesRevokePublicURLResponse>;
267

268
interface FilesSharedPublicURLArguments {
269
  /** File ID to enable public sharing for */
270
  file: string;
271
}
272

273
interface FilesRevokePublicURLArguments {
274
  /** File ID to revoke public sharing for */
275
  file: string;
276
}
277
```
278

279
**Usage Examples:**
280

281
```typescript
282
// Enable public sharing
283
const publicURL = await web.files.sharedPublicURL({
284
  file: 'F1234567890'
285
});
286

287
console.log('Public URL:', publicURL.file.permalink_public);
288

289
// Revoke public sharing
290
await web.files.revokePublicURL({
291
  file: 'F1234567890'
292
});
293

294
console.log('Public sharing revoked');
295
```
296

297
### Legacy File Upload
298

299
Legacy file upload method (use uploadV2 for new applications).
300

301
```typescript { .api }
302
/**
303
 * Upload a file (legacy method - use uploadV2 instead)
304
 * @param options - Upload parameters
305
 * @returns Promise resolving to upload result
306
 */
307
files.upload(options: FilesUploadArguments): Promise<FilesUploadResponse>;
308

309
interface FilesUploadArguments {
310
  /** File contents as string, Buffer, or Stream */
311
  file?: string | Buffer | NodeJS.ReadableStream;
312
  /** File contents (alternative to file parameter) */
313
  content?: string;
314
  /** Filename of file */
315
  filename?: string;
316
  /** Title of file */
317
  title?: string;
318
  /** Initial comment to add to file */
319
  initial_comment?: string;
320
  /** Comma-separated list of channel names or IDs */
321
  channels?: string;
322
  /** A file type identifier */
323
  filetype?: string;
324
  /** Syntax type of the snippet being uploaded */
325
  snippet_type?: string;
326
  /** Thread timestamp to upload to a thread */
327
  thread_ts?: string;
328
}
329
```
330

331
**Usage Examples:**
332

333
```typescript
334
// Legacy upload (prefer uploadV2)
335
const legacyUpload = await web.files.upload({
336
  channels: '#general',
337
  content: 'Hello, world!',
338
  filename: 'hello.txt',
339
  title: 'Greeting File'
340
});
341

342
console.log('Legacy upload result:', legacyUpload.file.id);
343
```
344

345
### File Comments
346

347
Manage comments on files.
348

349
```typescript { .api }
350
/**
351
 * Delete a comment on a file
352
 * @param options - Delete comment parameters
353
 * @returns Promise resolving to deletion result
354
 */
355
files.comments.delete(options: FilesCommentsDeleteArguments): Promise<FilesCommentsDeleteResponse>;
356

357
interface FilesCommentsDeleteArguments {
358
  /** File to delete comment from */
359
  file: string;
360
  /** ID of the comment to delete */
361
  id: string;
362
}
363
```
364

365
**Usage Examples:**
366

367
```typescript
368
// Delete a file comment
369
await web.files.comments.delete({
370
  file: 'F1234567890',
371
  id: 'Fc1234567890'
372
});
373

374
console.log('Comment deleted');
375
```
376

377
### Remote Files
378

379
Manage external files stored outside of Slack.
380

381
```typescript { .api }
382
/**
383
 * Add a remote file
384
 * @param options - Add remote file parameters
385
 * @returns Promise resolving to remote file details
386
 */
387
files.remote.add(options: FilesRemoteAddArguments): Promise<FilesRemoteAddResponse>;
388

389
/**
390
 * Get information about a remote file
391
 * @param options - Remote file info parameters
392
 * @returns Promise resolving to remote file details
393
 */
394
files.remote.info(options: FilesRemoteInfoArguments): Promise<FilesRemoteInfoResponse>;
395

396
/**
397
 * Remove a remote file
398
 * @param options - Remove parameters
399
 * @returns Promise resolving to removal confirmation
400
 */
401
files.remote.remove(options: FilesRemoteRemoveArguments): Promise<FilesRemoteRemoveResponse>;
402

403
interface FilesRemoteAddArguments {
404
  /** Creator defined GUID for the file */
405
  external_id: string;
406
  /** URL of the remote file */
407
  external_url: string;
408
  /** Title of the file */
409
  title: string;
410
  /** Type of file */
411
  filetype?: string;
412
  /** File size in bytes */
413
  indexable_file_contents?: string;  
414
  /** Preview of the document */
415
  preview_image?: string;
416
}
417
```
418

419
**Usage Examples:**
420

421
```typescript
422
// Add remote file
423
const remoteFile = await web.files.remote.add({
424
  external_id: 'gdrive-doc-123',
425
  external_url: 'https://docs.google.com/document/d/abc123',
426
  title: 'Project Specification',
427
  filetype: 'gdoc'
428
});
429

430
// Get remote file info
431
const remoteInfo = await web.files.remote.info({
432
  file: remoteFile.file.id
433
});
434

435
// Remove remote file
436
await web.files.remote.remove({
437
  file: remoteFile.file.id
438
});
439
```
440

441
## Types
442

443
```typescript { .api }
444
interface FilesCompleteUploadExternalResponse {
445
  id: string;
446
  created: number;
447
  timestamp: number;
448
  name: string;
449
  title: string;
450
  mimetype: string;
451
  filetype: string;
452
  pretty_type: string;
453
  user: string;
454
  size: number;
455
  mode: string;
456
  is_external: boolean;
457
  external_type: string;
458
  is_public: boolean;
459
  public_url_shared: boolean;
460
  display_as_bot: boolean;
461
  username: string;
462
  url_private: string;
463
  url_private_download: string;
464
  permalink: string;
465
  permalink_public?: string;
466
  thumb_64?: string;
467
  thumb_80?: string;
468
  thumb_360?: string;
469
  thumb_360_w?: number;
470
  thumb_360_h?: number;
471
  thumb_480?: string;
472
  thumb_480_w?: number;
473
  thumb_480_h?: number;
474
  thumb_160?: string;
475
  thumb_720?: string;
476
  thumb_720_w?: number;
477
  thumb_720_h?: number;
478
  thumb_800?: string;
479
  thumb_800_w?: number;
480
  thumb_800_h?: number;
481
  thumb_960?: string;
482
  thumb_960_w?: number;
483
  thumb_960_h?: number;
484
  thumb_1024?: string;
485
  thumb_1024_w?: number;
486
  thumb_1024_h?: number;
487
  original_w?: number;
488
  original_h?: number;
489
  thumb_tiny?: string;
490
}
491

492
interface FilesInfoResponse extends WebAPICallResult {
493
  file: {
494
    id: string;
495
    created: number;
496
    timestamp: number;
497
    name: string;
498
    title: string;
499
    mimetype: string;
500
    filetype: string;
501
    pretty_type: string;
502
    user: string;
503
    size: number;
504
    url_private: string;
505
    url_private_download: string;
506
    permalink: string;
507
    permalink_public?: string;
508
    channels: string[];
509
    groups: string[];
510
    ims: string[];
511
    comments_count?: number;
512
  };
513
  comments?: FileComment[];
514
  paging?: {
515
    count: number;
516
    total: number;
517
    page: number;
518
    pages: number;
519
  };
520
}
521

522
interface FileComment {
523
  id: string;
524
  created: number;
525
  timestamp: number;
526
  user: string;
527
  comment: string;
528
}
529

530
interface FilesListResponse extends WebAPICallResult {
531
  files: FilesInfoResponse['file'][];
532
  paging: {
533
    count: number;
534
    total: number;
535
    page: number;
536
    pages: number;
537
  };
538
}
539
```