0
# Media and File Operations
1

2
Comprehensive media handling including photos, videos, audio, documents, stickers, and voice messages with upload, download, and streaming capabilities.
3

4
## Capabilities
5

6
### Photo Operations
7

8
Methods for sending and handling photo messages with various format support.
9

10
```javascript { .api }
11
/**
12
 * Send photo to chat
13
 * @param {number|string} chatId - Chat identifier
14
 * @param {string|Buffer|stream.Readable} photo - Photo to send
15
 * @param {object} [options] - Additional options
16
 * @param {object} [fileOptions] - File upload options
17
 * @returns {Promise<Message>}
18
 */
19
sendPhoto(chatId, photo, options, fileOptions): Promise<Message>;
20
```
21

22
**Usage Example:**
23

24
```javascript
25
// Send photo from file path
26
await bot.sendPhoto(chatId, './photo.jpg', {
27
  caption: 'Beautiful sunset 🌅',
28
  parse_mode: 'HTML'
29
});
30

31
// Send photo from URL
32
await bot.sendPhoto(chatId, 'https://example.com/photo.jpg', {
33
  caption: 'Photo from URL'
34
});
35

36
// Send photo from Buffer
37
const fs = require('fs');
38
const photoBuffer = fs.readFileSync('./photo.jpg');
39
await bot.sendPhoto(chatId, photoBuffer, {
40
  caption: 'Photo from buffer',
41
  reply_to_message_id: messageId
42
});
43

44
// Send photo with custom filename
45
await bot.sendPhoto(chatId, fs.createReadStream('./photo.jpg'), {
46
  caption: 'Custom filename photo'
47
}, {
48
  filename: 'custom-name.jpg',
49
  contentType: 'image/jpeg'
50
});
51

52
// Send photo with spoiler
53
await bot.sendPhoto(chatId, './photo.jpg', {
54
  has_spoiler: true,
55
  caption: 'Spoiler photo - click to reveal'
56
});
57
```
58

59
### Video Operations
60

61
Methods for sending video content including regular videos and animations.
62

63
```javascript { .api }
64
/**
65
 * Send video to chat
66
 * @param {number|string} chatId - Chat identifier
67
 * @param {string|Buffer|stream.Readable} video - Video to send
68
 * @param {object} [options] - Additional options
69
 * @param {object} [fileOptions] - File upload options
70
 * @returns {Promise<Message>}
71
 */
72
sendVideo(chatId, video, options, fileOptions): Promise<Message>;
73

74
/**
75
 * Send animation (GIF or H.264/MPEG-4 AVC) to chat
76
 * @param {number|string} chatId - Chat identifier
77
 * @param {string|Buffer|stream.Readable} animation - Animation to send
78
 * @param {object} [options] - Additional options
79
 * @param {object} [fileOptions] - File upload options
80
 * @returns {Promise<Message>}
81
 */
82
sendAnimation(chatId, animation, options, fileOptions): Promise<Message>;
83

84
/**
85
 * Send video note (circular video message) to chat
86
 * @param {number|string} chatId - Chat identifier
87
 * @param {string|Buffer|stream.Readable} videoNote - Video note to send
88
 * @param {object} [options] - Additional options
89
 * @param {object} [fileOptions] - File upload options
90
 * @returns {Promise<Message>}
91
 */
92
sendVideoNote(chatId, videoNote, options, fileOptions): Promise<Message>;
93
```
94

95
**Usage Example:**
96

97
```javascript
98
// Send video with duration and dimensions
99
await bot.sendVideo(chatId, './video.mp4', {
100
  duration: 60,
101
  width: 1920,
102
  height: 1080,
103
  caption: 'Sample video',
104
  supports_streaming: true
105
});
106

107
// Send animation/GIF
108
await bot.sendAnimation(chatId, './animation.gif', {
109
  duration: 5,
110
  width: 320,
111
  height: 240,
112
  caption: 'Funny animation 😄'
113
});
114

115
// Send video note (round video)
116
await bot.sendVideoNote(chatId, './video-note.mp4', {
117
  duration: 10,
118
  length: 240  // diameter of video circle
119
});
120

121
// Send video with thumbnail
122
await bot.sendVideo(chatId, './video.mp4', {
123
  thumbnail: './thumbnail.jpg',
124
  caption: 'Video with custom thumbnail'
125
});
126
```
127

128
### Audio Operations
129

130
Methods for sending audio files and voice messages.
131

132
```javascript { .api }
133
/**
134
 * Send audio file to chat
135
 * @param {number|string} chatId - Chat identifier
136
 * @param {string|Buffer|stream.Readable} audio - Audio to send
137
 * @param {object} [options] - Additional options
138
 * @param {object} [fileOptions] - File upload options
139
 * @returns {Promise<Message>}
140
 */
141
sendAudio(chatId, audio, options, fileOptions): Promise<Message>;
142

143
/**
144
 * Send voice message to chat
145
 * @param {number|string} chatId - Chat identifier
146
 * @param {string|Buffer|stream.Readable} voice - Voice to send
147
 * @param {object} [options] - Additional options
148
 * @param {object} [fileOptions] - File upload options
149
 * @returns {Promise<Message>}
150
 */
151
sendVoice(chatId, voice, options, fileOptions): Promise<Message>;
152
```
153

154
**Usage Example:**
155

156
```javascript
157
// Send audio file with metadata
158
await bot.sendAudio(chatId, './song.mp3', {
159
  duration: 180,
160
  performer: 'Artist Name',
161
  title: 'Song Title',
162
  caption: 'Great song! 🎵'
163
});
164

165
// Send voice message
166
await bot.sendVoice(chatId, './voice-note.ogg', {
167
  duration: 15,
168
  caption: 'Voice message'
169
});
170

171
// Send audio with thumbnail
172
await bot.sendAudio(chatId, './song.mp3', {
173
  thumbnail: './album-cover.jpg',
174
  performer: 'Artist',
175
  title: 'Song'
176
});
177
```
178

179
### Document Operations
180

181
Methods for sending various document types and files.
182

183
```javascript { .api }
184
/**
185
 * Send document to chat
186
 * @param {number|string} chatId - Chat identifier
187
 * @param {string|Buffer|stream.Readable} doc - Document to send
188
 * @param {object} [options] - Additional options
189
 * @param {object} [fileOptions] - File upload options
190
 * @returns {Promise<Message>}
191
 */
192
sendDocument(chatId, doc, options, fileOptions): Promise<Message>;
193
```
194

195
**Usage Example:**
196

197
```javascript
198
// Send document
199
await bot.sendDocument(chatId, './document.pdf', {
200
  caption: 'Important document 📄',
201
  parse_mode: 'HTML'
202
});
203

204
// Send document as file attachment (not thumbnail)
205
await bot.sendDocument(chatId, './spreadsheet.xlsx', {
206
  disable_content_type_detection: true,
207
  caption: 'Financial report'
208
});
209

210
// Send document with custom thumbnail
211
await bot.sendDocument(chatId, './presentation.pptx', {
212
  thumbnail: './presentation-thumb.jpg',
213
  caption: 'Quarterly presentation'
214
});
215
```
216

217
### Sticker Operations
218

219
Methods for sending stickers and managing sticker sets.
220

221
```javascript { .api }
222
/**
223
 * Send sticker to chat
224
 * @param {number|string} chatId - Chat identifier
225
 * @param {string|Buffer|stream.Readable} sticker - Sticker to send
226
 * @param {object} [options] - Additional options
227
 * @param {object} [fileOptions] - File upload options
228
 * @returns {Promise<Message>}
229
 */
230
sendSticker(chatId, sticker, options, fileOptions): Promise<Message>;
231

232
/**
233
 * Get sticker set information
234
 * @param {string} name - Sticker set name
235
 * @param {object} [options] - Additional options
236
 * @returns {Promise<StickerSet>}
237
 */
238
getStickerSet(name, options): Promise<StickerSet>;
239

240
/**
241
 * Get custom emoji stickers
242
 * @param {string[]} customEmojiIds - Array of custom emoji identifiers
243
 * @param {object} [options] - Additional options
244
 * @returns {Promise<Sticker[]>}
245
 */
246
getCustomEmojiStickers(customEmojiIds, options): Promise<Sticker[]>;
247
```
248

249
**Usage Example:**
250

251
```javascript
252
// Send sticker by file_id
253
await bot.sendSticker(chatId, 'CAACAgIAAxkBAAIC...');
254

255
// Send sticker from file
256
await bot.sendSticker(chatId, './sticker.webp');
257

258
// Get sticker set information
259
const stickerSet = await bot.getStickerSet('animals_by_bot');
260
console.log(`Sticker set "${stickerSet.title}" has ${stickerSet.stickers.length} stickers`);
261

262
// Get custom emoji stickers
263
const customEmojis = await bot.getCustomEmojiStickers([
264
  '5789...',
265
  '5790...'
266
]);
267
```
268

269
### Media Groups
270

271
Method for sending multiple media items as an album.
272

273
```javascript { .api }
274
/**
275
 * Send group of photos/videos as album
276
 * @param {number|string} chatId - Chat identifier
277
 * @param {object[]} media - Array of media objects
278
 * @param {object} [options] - Additional options
279
 * @returns {Promise<Message[]>}
280
 */
281
sendMediaGroup(chatId, media, options): Promise<Message[]>;
282
```
283

284
**Usage Example:**
285

286
```javascript
287
// Send photo album
288
const photoAlbum = [
289
  {
290
    type: 'photo',
291
    media: './photo1.jpg',
292
    caption: 'First photo'
293
  },
294
  {
295
    type: 'photo',
296
    media: './photo2.jpg',
297
    caption: 'Second photo'
298
  },
299
  {
300
    type: 'photo',
301
    media: './photo3.jpg'
302
  }
303
];
304

305
const messages = await bot.sendMediaGroup(chatId, photoAlbum);
306
console.log(`Sent album with ${messages.length} photos`);
307

308
// Send mixed media album
309
const mixedAlbum = [
310
  {
311
    type: 'photo',
312
    media: './photo.jpg',
313
    caption: 'Photo in album'
314
  },
315
  {
316
    type: 'video',
317
    media: './video.mp4',
318
    caption: 'Video in album'
319
  }
320
];
321

322
await bot.sendMediaGroup(chatId, mixedAlbum, {
323
  disable_notification: true
324
});
325
```
326

327
### File Download and Access
328

329
Methods for accessing, downloading, and streaming files from Telegram servers.
330

331
```javascript { .api }
332
/**
333
 * Get file information
334
 * @param {string} fileId - File identifier
335
 * @param {object} [options] - Additional options
336
 * @returns {Promise<File>}
337
 */
338
getFile(fileId, options): Promise<File>;
339

340
/**
341
 * Get download link for file (valid for 1 hour)
342
 * @param {string} fileId - File identifier
343
 * @param {object} [options] - Additional options
344
 * @returns {Promise<string>}
345
 */
346
getFileLink(fileId, options): Promise<string>;
347

348
/**
349
 * Get readable stream for file
350
 * @param {string} fileId - File identifier
351
 * @param {object} [options] - Additional options
352
 * @returns {stream.Readable}
353
 */
354
getFileStream(fileId, options): stream.Readable;
355

356
/**
357
 * Download file to specified directory
358
 * @param {string} fileId - File identifier
359
 * @param {string} downloadDir - Directory to download to
360
 * @param {object} [options] - Additional options
361
 * @returns {Promise<string>} Downloaded file path
362
 */
363
downloadFile(fileId, downloadDir, options): Promise<string>;
364
```
365

366
**Usage Example:**
367

368
```javascript
369
// Handle document message and download
370
bot.on('document', async (msg) => {
371
  const document = msg.document;
372
  
373
  // Get file information
374
  const file = await bot.getFile(document.file_id);
375
  console.log(`File size: ${file.file_size} bytes`);
376
  console.log(`File path: ${file.file_path}`);
377
  
378
  // Get download link
379
  const fileLink = await bot.getFileLink(document.file_id);
380
  console.log(`Download link: ${fileLink}`);
381
  
382
  // Download file
383
  const downloadPath = await bot.downloadFile(document.file_id, './downloads/');
384
  console.log(`File downloaded to: ${downloadPath}`);
385
  
386
  // Stream file
387
  const fileStream = bot.getFileStream(document.file_id);
388
  fileStream.pipe(require('fs').createWriteStream(`./stream-${document.file_name}`));
389
});
390

391
// Handle photo and get largest size
392
bot.on('photo', async (msg) => {
393
  const photos = msg.photo;
394
  const largestPhoto = photos[photos.length - 1]; // Last photo is largest
395
  
396
  const filePath = await bot.downloadFile(largestPhoto.file_id, './photos/');
397
  console.log(`Downloaded photo: ${filePath}`);
398
});
399
```
400

401
### User Profile Photos
402

403
Method for retrieving user profile photos.
404

405
```javascript { .api }
406
/**
407
 * Get user's profile photos
408
 * @param {number} userId - User identifier
409
 * @param {object} [options] - Additional options
410
 * @returns {Promise<UserProfilePhotos>}
411
 */
412
getUserProfilePhotos(userId, options): Promise<UserProfilePhotos>;
413
```
414

415
**Usage Example:**
416

417
```javascript
418
// Get user profile photos
419
const userPhotos = await bot.getUserProfilePhotos(userId, {
420
  offset: 0,
421
  limit: 10
422
});
423

424
console.log(`User has ${userPhotos.total_count} profile photos`);
425

426
// Download first profile photo
427
if (userPhotos.photos.length > 0) {
428
  const firstPhoto = userPhotos.photos[0];
429
  const largestSize = firstPhoto[firstPhoto.length - 1];
430
  
431
  const photoPath = await bot.downloadFile(largestSize.file_id, './profiles/');
432
  console.log(`Downloaded profile photo: ${photoPath}`);
433
}
434
```
435

436
## Types
437

438
```javascript { .api }
439
interface File {
440
  file_id: string;
441
  file_unique_id: string;
442
  file_size?: number;
443
  file_path?: string;
444
}
445

446
interface PhotoSize {
447
  file_id: string;
448
  file_unique_id: string;
449
  width: number;
450
  height: number;
451
  file_size?: number;
452
}
453

454
interface Audio {
455
  file_id: string;
456
  file_unique_id: string;
457
  duration: number;
458
  performer?: string;
459
  title?: string;
460
  file_name?: string;
461
  mime_type?: string;
462
  file_size?: number;
463
  thumbnail?: PhotoSize;
464
}
465

466
interface Document {
467
  file_id: string;
468
  file_unique_id: string;
469
  thumbnail?: PhotoSize;
470
  file_name?: string;
471
  mime_type?: string;
472
  file_size?: number;
473
}
474

475
interface Video {
476
  file_id: string;
477
  file_unique_id: string;
478
  width: number;
479
  height: number;
480
  duration: number;
481
  thumbnail?: PhotoSize;
482
  file_name?: string;
483
  mime_type?: string;
484
  file_size?: number;
485
}
486

487
interface Animation {
488
  file_id: string;
489
  file_unique_id: string;
490
  width: number;
491
  height: number;
492
  duration: number;
493
  thumbnail?: PhotoSize;
494
  file_name?: string;
495
  mime_type?: string;
496
  file_size?: number;
497
}
498

499
interface Voice {
500
  file_id: string;
501
  file_unique_id: string;
502
  duration: number;
503
  mime_type?: string;
504
  file_size?: number;
505
}
506

507
interface VideoNote {
508
  file_id: string;
509
  file_unique_id: string;
510
  length: number;
511
  duration: number;
512
  thumbnail?: PhotoSize;
513
  file_size?: number;
514
}
515

516
interface Sticker {
517
  file_id: string;
518
  file_unique_id: string;
519
  type: 'regular' | 'mask' | 'custom_emoji';
520
  width: number;
521
  height: number;
522
  is_animated: boolean;
523
  is_video: boolean;
524
  thumbnail?: PhotoSize;
525
  emoji?: string;
526
  set_name?: string;
527
  premium_animation?: File;
528
  mask_position?: MaskPosition;
529
  custom_emoji_id?: string;
530
  needs_repainting?: boolean;
531
  file_size?: number;
532
}
533

534
interface StickerSet {
535
  name: string;
536
  title: string;
537
  sticker_type: 'regular' | 'mask' | 'custom_emoji';
538
  is_animated: boolean;
539
  is_video: boolean;
540
  stickers: Sticker[];
541
  thumbnail?: PhotoSize;
542
}
543

544
interface UserProfilePhotos {
545
  total_count: number;
546
  photos: PhotoSize[][];
547
}
548

549
interface InputMedia {
550
  type: 'photo' | 'video' | 'animation' | 'audio' | 'document';
551
  media: string;
552
  caption?: string;
553
  parse_mode?: 'HTML' | 'Markdown' | 'MarkdownV2';
554
  caption_entities?: MessageEntity[];
555
}
556

557
interface InputMediaPhoto extends InputMedia {
558
  type: 'photo';
559
  has_spoiler?: boolean;
560
}
561

562
interface InputMediaVideo extends InputMedia {
563
  type: 'video';
564
  thumbnail?: string;
565
  width?: number;
566
  height?: number;
567
  duration?: number;
568
  supports_streaming?: boolean;
569
  has_spoiler?: boolean;
570
}
571

572
interface InputMediaAnimation extends InputMedia {
573
  type: 'animation';
574
  thumbnail?: string;
575
  width?: number;
576
  height?: number;
577
  duration?: number;
578
  has_spoiler?: boolean;
579
}
580

581
interface InputMediaAudio extends InputMedia {
582
  type: 'audio';
583
  thumbnail?: string;
584
  duration?: number;
585
  performer?: string;
586
  title?: string;
587
}
588

589
interface InputMediaDocument extends InputMedia {
590
  type: 'document';
591
  thumbnail?: string;
592
  disable_content_type_detection?: boolean;
593
}
594
```