0
# Media Handling
1

2
Sending and managing multimedia content including photos, videos, audio, documents, stickers, animations, and media groups with thumbnail and metadata support.
3

4
## Capabilities
5

6
### Photo Handling
7

8
Send and manage photo content with captions, thumbnails, and metadata.
9

10
```python { .api }
11
def send_photo(self, chat_id: Union[int, str], photo: Union[Any, str],
12
              caption: Optional[str] = None, 
13
              reply_to_message_id: Optional[int] = None,
14
              reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
15
              parse_mode: Optional[str] = None,
16
              disable_notification: Optional[bool] = None,
17
              timeout: Optional[int] = None,
18
              caption_entities: Optional[List[types.MessageEntity]] = None,
19
              allow_sending_without_reply: Optional[bool] = None) -> types.Message:
20
    """
21
    Send photos with optional captions and formatting.
22

23
    Parameters:
24
    - chat_id (Union[int, str]): Target chat ID or username
25
    - photo (Union[Any, str]): Photo file, file path, URL, or file_id
26
    - caption (str, optional): Photo caption (0-1024 characters)
27
    - reply_to_message_id (int, optional): Message ID to reply to
28
    - reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
29
    - parse_mode (str, optional): Caption parsing mode
30
    - disable_notification (bool, optional): Send silently
31
    - timeout (int, optional): Request timeout
32
    - caption_entities (List[MessageEntity], optional): Caption entities
33
    - allow_sending_without_reply (bool, optional): Send if reply target missing
34

35
    Returns:
36
    Message: Sent photo message
37
    """
38
```
39

40
### Video Handling
41

42
Send videos with duration, thumbnails, and caption support.
43

44
```python { .api }
45
def send_video(self, chat_id: Union[int, str], data: Union[Any, str],
46
              duration: Optional[int] = None,
47
              caption: Optional[str] = None,
48
              reply_to_message_id: Optional[int] = None,
49
              reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
50
              parse_mode: Optional[str] = None,
51
              supports_streaming: Optional[bool] = None,
52
              disable_notification: Optional[bool] = None,
53
              timeout: Optional[int] = None,
54
              thumb: Optional[Union[Any, str]] = None,
55
              width: Optional[int] = None,
56
              height: Optional[int] = None,
57
              caption_entities: Optional[List[types.MessageEntity]] = None,
58
              allow_sending_without_reply: Optional[bool] = None) -> types.Message:
59
    """
60
    Send video files with metadata and thumbnails.
61

62
    Parameters:
63
    - chat_id (Union[int, str]): Target chat
64
    - data (Union[Any, str]): Video file, path, URL, or file_id
65
    - duration (int, optional): Video duration in seconds
66
    - caption (str, optional): Video caption
67
    - reply_to_message_id (int, optional): Message to reply to
68
    - reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
69
    - parse_mode (str, optional): Caption parsing mode
70
    - supports_streaming (bool, optional): Pass True for streaming support
71
    - disable_notification (bool, optional): Send silently
72
    - timeout (int, optional): Request timeout
73
    - thumb (Union[Any, str], optional): Thumbnail file
74
    - width (int, optional): Video width
75
    - height (int, optional): Video height
76
    - caption_entities (List[MessageEntity], optional): Caption entities
77
    - allow_sending_without_reply (bool, optional): Send if reply target missing
78

79
    Returns:
80
    Message: Sent video message
81
    """
82

83
def send_video_note(self, chat_id: Union[int, str], data: Union[Any, str],
84
                   duration: Optional[int] = None,
85
                   length: Optional[int] = None,
86
                   reply_to_message_id: Optional[int] = None,
87
                   reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
88
                   disable_notification: Optional[bool] = None,
89
                   timeout: Optional[int] = None,
90
                   thumb: Optional[Union[Any, str]] = None,
91
                   allow_sending_without_reply: Optional[bool] = None) -> types.Message:
92
    """
93
    Send video messages (rounded square mp4 videos up to 1 minute).
94

95
    Parameters:
96
    - chat_id (Union[int, str]): Target chat
97
    - data (Union[Any, str]): Video note file or file_id
98
    - duration (int, optional): Video duration in seconds
99
    - length (int, optional): Video width and height (0-640)
100
    - reply_to_message_id (int, optional): Message to reply to
101
    - reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
102
    - disable_notification (bool, optional): Send silently
103
    - timeout (int, optional): Request timeout
104
    - thumb (Union[Any, str], optional): Thumbnail file
105
    - allow_sending_without_reply (bool, optional): Send if reply target missing
106

107
    Returns:
108
    Message: Sent video note message
109
    """
110
```
111

112
### Audio Handling
113

114
Send audio files and voice messages with metadata support.
115

116
```python { .api }
117
def send_audio(self, chat_id: Union[int, str], audio: Union[Any, str],
118
              caption: Optional[str] = None,
119
              duration: Optional[int] = None,
120
              performer: Optional[str] = None,
121
              title: Optional[str] = None,
122
              reply_to_message_id: Optional[int] = None,
123
              reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
124
              parse_mode: Optional[str] = None,
125
              disable_notification: Optional[bool] = None,
126
              timeout: Optional[int] = None,
127
              thumb: Optional[Union[Any, str]] = None,
128
              caption_entities: Optional[List[types.MessageEntity]] = None,
129
              allow_sending_without_reply: Optional[bool] = None) -> types.Message:
130
    """
131
    Send audio files for music player display (.mp3 format).
132

133
    Parameters:
134
    - chat_id (Union[int, str]): Target chat
135
    - audio (Union[Any, str]): Audio file, path, URL, or file_id
136
    - caption (str, optional): Audio caption
137
    - duration (int, optional): Audio duration in seconds
138
    - performer (str, optional): Performer name
139
    - title (str, optional): Track name
140
    - reply_to_message_id (int, optional): Message to reply to
141
    - reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
142
    - parse_mode (str, optional): Caption parsing mode
143
    - disable_notification (bool, optional): Send silently
144
    - timeout (int, optional): Request timeout
145
    - thumb (Union[Any, str], optional): Thumbnail file
146
    - caption_entities (List[MessageEntity], optional): Caption entities
147
    - allow_sending_without_reply (bool, optional): Send if reply target missing
148

149
    Returns:
150
    Message: Sent audio message
151
    """
152

153
def send_voice(self, chat_id: Union[int, str], voice: Union[Any, str],
154
              caption: Optional[str] = None,
155
              duration: Optional[int] = None,
156
              reply_to_message_id: Optional[int] = None,
157
              reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
158
              parse_mode: Optional[str] = None,
159
              disable_notification: Optional[bool] = None,
160
              timeout: Optional[int] = None,
161
              caption_entities: Optional[List[types.MessageEntity]] = None,
162
              allow_sending_without_reply: Optional[bool] = None) -> types.Message:
163
    """
164
    Send audio files as voice messages.
165

166
    Parameters:
167
    - chat_id (Union[int, str]): Target chat
168
    - voice (Union[Any, str]): Voice file, path, URL, or file_id
169
    - caption (str, optional): Voice message caption
170
    - duration (int, optional): Duration in seconds
171
    - reply_to_message_id (int, optional): Message to reply to
172
    - reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
173
    - parse_mode (str, optional): Caption parsing mode
174
    - disable_notification (bool, optional): Send silently
175
    - timeout (int, optional): Request timeout
176
    - caption_entities (List[MessageEntity], optional): Caption entities
177
    - allow_sending_without_reply (bool, optional): Send if reply target missing
178

179
    Returns:
180
    Message: Sent voice message
181
    """
182
```
183

184
### Document Handling
185

186
Send general files and documents with custom filenames and thumbnails.
187

188
```python { .api }
189
def send_document(self, chat_id: Union[int, str], data: Union[Any, str],
190
                 reply_to_message_id: Optional[int] = None,
191
                 caption: Optional[str] = None,
192
                 reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
193
                 parse_mode: Optional[str] = None,
194
                 disable_notification: Optional[bool] = None,
195
                 timeout: Optional[int] = None,
196
                 thumb: Optional[Union[Any, str]] = None,
197
                 caption_entities: Optional[List[types.MessageEntity]] = None,
198
                 allow_sending_without_reply: Optional[bool] = None,
199
                 visible_file_name: Optional[str] = None,
200
                 disable_content_type_detection: Optional[bool] = None) -> types.Message:
201
    """
202
    Send general files and documents.
203

204
    Parameters:
205
    - chat_id (Union[int, str]): Target chat
206
    - data (Union[Any, str]): Document file, path, URL, or file_id
207
    - reply_to_message_id (int, optional): Message to reply to
208
    - caption (str, optional): Document caption (0-1024 characters)
209
    - reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
210
    - parse_mode (str, optional): Caption parsing mode
211
    - disable_notification (bool, optional): Send silently
212
    - timeout (int, optional): Request timeout
213
    - thumb (Union[Any, str], optional): Thumbnail file (JPEG, <200kB, <320px)
214
    - caption_entities (List[MessageEntity], optional): Caption entities
215
    - allow_sending_without_reply (bool, optional): Send if reply target missing
216
    - visible_file_name (str, optional): Custom filename for display
217
    - disable_content_type_detection (bool, optional): Disable server-side detection
218

219
    Returns:
220
    Message: Sent document message
221
    """
222
```
223

224
### Animation and Sticker Handling
225

226
Send GIF animations and stickers.
227

228
```python { .api }
229
def send_animation(self, chat_id: Union[int, str], animation: Union[Any, str],
230
                  duration: Optional[int] = None,
231
                  caption: Optional[str] = None,
232
                  reply_to_message_id: Optional[int] = None,
233
                  reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
234
                  parse_mode: Optional[str] = None,
235
                  disable_notification: Optional[bool] = None,
236
                  timeout: Optional[int] = None,
237
                  thumb: Optional[Union[Any, str]] = None,
238
                  caption_entities: Optional[List[types.MessageEntity]] = None,
239
                  allow_sending_without_reply: Optional[bool] = None) -> types.Message:
240
    """
241
    Send animation files (GIF or H.264/MPEG-4 AVC video without sound).
242

243
    Parameters:
244
    - chat_id (Union[int, str]): Target chat
245
    - animation (Union[Any, str]): Animation file, path, URL, or file_id
246
    - duration (int, optional): Animation duration in seconds
247
    - caption (str, optional): Animation caption
248
    - reply_to_message_id (int, optional): Message to reply to
249
    - reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
250
    - parse_mode (str, optional): Caption parsing mode
251
    - disable_notification (bool, optional): Send silently
252
    - timeout (int, optional): Request timeout
253
    - thumb (Union[Any, str], optional): Thumbnail file
254
    - caption_entities (List[MessageEntity], optional): Caption entities
255
    - allow_sending_without_reply (bool, optional): Send if reply target missing
256

257
    Returns:
258
    Message: Sent animation message
259
    """
260

261
def send_sticker(self, chat_id: Union[int, str], data: Union[Any, str],
262
                reply_to_message_id: Optional[int] = None,
263
                reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
264
                disable_notification: Optional[bool] = None,
265
                timeout: Optional[int] = None,
266
                allow_sending_without_reply: Optional[bool] = None) -> types.Message:
267
    """
268
    Send .webp stickers.
269

270
    Parameters:
271
    - chat_id (Union[int, str]): Target chat
272
    - data (Union[Any, str]): Sticker file, path, URL, or file_id
273
    - reply_to_message_id (int, optional): Message to reply to
274
    - reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
275
    - disable_notification (bool, optional): Send silently
276
    - timeout (int, optional): Request timeout
277
    - allow_sending_without_reply (bool, optional): Send if reply target missing
278

279
    Returns:
280
    Message: Sent sticker message
281
    """
282
```
283

284
### Sticker Management
285

286
Create, manage, and modify custom sticker sets for your bot.
287

288
```python { .api }
289
def create_new_sticker_set(self, user_id: int, name: str, title: str, 
290
                          emojis: str,
291
                          png_sticker: Optional[Union[Any, str]] = None,
292
                          tgs_sticker: Optional[Union[Any, str]] = None, 
293
                          contains_masks: Optional[bool] = None,
294
                          mask_position: Optional[types.MaskPosition] = None) -> bool:
295
    """
296
    Create a new sticker set owned by a user.
297
    The bot will be able to edit the created sticker set.
298

299
    Parameters:
300
    - user_id (int): User identifier of created sticker set owner
301
    - name (str): Short name of sticker set (1-64 characters, lowercase letters, digits, underscores)
302
    - title (str): Sticker set title (1-64 characters)
303
    - emojis (str): One or more emoji corresponding to the sticker
304
    - png_sticker (Union[Any, str], optional): PNG image or file ID
305
    - tgs_sticker (Union[Any, str], optional): TGS animation or file ID
306
    - contains_masks (bool, optional): True if stickers in set are masks
307
    - mask_position (MaskPosition, optional): Position where mask is placed
308

309
    Returns:
310
    bool: True on success
311
    """
312

313
def add_sticker_to_set(self, user_id: int, name: str, emojis: str,
314
                      png_sticker: Optional[Union[Any, str]] = None, 
315
                      tgs_sticker: Optional[Union[Any, str]] = None,  
316
                      mask_position: Optional[types.MaskPosition] = None) -> bool:
317
    """
318
    Add a new sticker to a set created by the bot.
319
    Either png_sticker or tgs_sticker is required.
320

321
    Parameters:
322
    - user_id (int): User identifier of sticker set owner
323
    - name (str): Sticker set name
324
    - emojis (str): One or more emoji corresponding to the sticker
325
    - png_sticker (Union[Any, str], optional): PNG image or file ID
326
    - tgs_sticker (Union[Any, str], optional): TGS animation or file ID
327
    - mask_position (MaskPosition, optional): Position where mask is placed
328

329
    Returns:
330
    bool: True on success
331
    """
332

333
def delete_sticker_from_set(self, sticker: str) -> bool:
334
    """
335
    Delete a sticker from a set created by the bot.
336

337
    Parameters:
338
    - sticker (str): File identifier of the sticker
339

340
    Returns:
341
    bool: True on success
342
    """
343

344
def set_sticker_set_thumb(self, name: str, user_id: int, 
345
                         thumb: Optional[Union[Any, str]] = None) -> bool:
346
    """
347
    Set the thumbnail of a sticker set.
348
    Animated thumbnails can be set for animated sticker sets only.
349

350
    Parameters:
351
    - name (str): Sticker set name
352
    - user_id (int): User identifier of the sticker set owner
353
    - thumb (Union[Any, str], optional): PNG image or file ID for thumbnail
354

355
    Returns:
356
    bool: True on success
357
    """
358

359
def upload_sticker_file(self, user_id: int, png_sticker: Union[Any, str]) -> types.File:
360
    """
361
    Upload a PNG file with a sticker for later use in sticker set operations.
362

363
    Parameters:
364
    - user_id (int): User identifier of sticker file owner
365
    - png_sticker (Union[Any, str]): PNG image file
366

367
    Returns:
368
    File: Information about the uploaded file
369
    """
370
```
371

372
### Media Groups
373

374
Send multiple media files as an album.
375

376
```python { .api }
377
def send_media_group(self, chat_id: Union[int, str],
378
                    media: List[Union[types.InputMediaAudio, types.InputMediaDocument,
379
                                    types.InputMediaPhoto, types.InputMediaVideo]],
380
                    disable_notification: Optional[bool] = None,
381
                    reply_to_message_id: Optional[int] = None,
382
                    timeout: Optional[int] = None,
383
                    allow_sending_without_reply: Optional[bool] = None) -> List[types.Message]:
384
    """
385
    Send a group of photos or videos as an album.
386

387
    Parameters:
388
    - chat_id (Union[int, str]): Target chat
389
    - media (List[InputMedia]): Array of photos and videos (2-10 items)
390
    - disable_notification (bool, optional): Send silently
391
    - reply_to_message_id (int, optional): Message to reply to
392
    - timeout (int, optional): Request timeout
393
    - allow_sending_without_reply (bool, optional): Send if reply target missing
394

395
    Returns:
396
    List[Message]: Array of sent messages
397
    """
398
```
399

400
### Location and Contact Sharing
401

402
Send location data and contact information.
403

404
```python { .api }
405
def send_location(self, chat_id: Union[int, str], latitude: float, longitude: float,
406
                 live_period: Optional[int] = None,
407
                 reply_to_message_id: Optional[int] = None,
408
                 reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
409
                 disable_notification: Optional[bool] = None,
410
                 timeout: Optional[int] = None,
411
                 horizontal_accuracy: Optional[float] = None,
412
                 heading: Optional[int] = None,
413
                 proximity_alert_radius: Optional[int] = None,
414
                 allow_sending_without_reply: Optional[bool] = None) -> types.Message:
415
    """
416
    Send point on the map with optional live location.
417

418
    Parameters:
419
    - chat_id (Union[int, str]): Target chat
420
    - latitude (float): Latitude of the location
421
    - longitude (float): Longitude of the location
422
    - live_period (int, optional): Live location period in seconds (60-86400)
423
    - reply_to_message_id (int, optional): Message to reply to
424
    - reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
425
    - disable_notification (bool, optional): Send silently
426
    - timeout (int, optional): Request timeout
427
    - horizontal_accuracy (float, optional): Radius uncertainty in meters (0-1500)
428
    - heading (int, optional): Direction in degrees (1-360)
429
    - proximity_alert_radius (int, optional): Alert radius in meters (1-100000)
430
    - allow_sending_without_reply (bool, optional): Send if reply target missing
431

432
    Returns:
433
    Message: Sent location message
434
    """
435

436
def send_contact(self, chat_id: Union[int, str], phone_number: str,
437
                first_name: str, last_name: Optional[str] = None,
438
                vcard: Optional[str] = None,
439
                disable_notification: Optional[bool] = None,
440
                reply_to_message_id: Optional[int] = None,
441
                reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
442
                timeout: Optional[int] = None,
443
                allow_sending_without_reply: Optional[bool] = None) -> types.Message:
444
    """
445
    Send phone contact information.
446

447
    Parameters:
448
    - chat_id (Union[int, str]): Target chat
449
    - phone_number (str): Contact's phone number
450
    - first_name (str): Contact's first name
451
    - last_name (str, optional): Contact's last name
452
    - vcard (str, optional): vCard data for additional contact info
453
    - disable_notification (bool, optional): Send silently
454
    - reply_to_message_id (int, optional): Message to reply to
455
    - reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
456
    - timeout (int, optional): Request timeout
457
    - allow_sending_without_reply (bool, optional): Send if reply target missing
458

459
    Returns:
460
    Message: Sent contact message
461
    """
462
```
463

464
## Usage Examples
465

466
### Photo Sending Example
467

468
```python
469
# Send photo from file
470
with open('photo.jpg', 'rb') as photo:
471
    bot.send_photo(chat_id, photo, caption="A beautiful photo!")
472

473
# Send photo by URL
474
bot.send_photo(chat_id, "https://example.com/photo.jpg")
475

476
# Send photo with inline keyboard
477
from telebot import types
478
markup = types.InlineKeyboardMarkup()
479
markup.add(types.InlineKeyboardButton("Like", callback_data="like"))
480
bot.send_photo(chat_id, photo, caption="Rate this photo:", reply_markup=markup)
481
```
482

483
### Media Group Example
484

485
```python
486
from telebot import types
487

488
# Create media group with mixed content
489
media_group = [
490
    types.InputMediaPhoto("photo1.jpg", caption="Photo 1"),
491
    types.InputMediaPhoto("photo2.jpg", caption="Photo 2"),
492
    types.InputMediaVideo("video.mp4", caption="Video")
493
]
494

495
bot.send_media_group(chat_id, media_group)
496
```
497

498
### Live Location Example
499

500
```python
501
# Send live location for 1 hour
502
bot.send_location(
503
    chat_id=chat_id,
504
    latitude=40.7128,
505
    longitude=-74.0060,
506
    live_period=3600,  # 1 hour
507
    horizontal_accuracy=10.0
508
)
509
```
510

511
## Types
512

513
```python { .api }
514
class InputMediaPhoto:
515
    type: str = "photo"
516
    media: str
517
    caption: Optional[str]
518
    parse_mode: Optional[str]
519
    caption_entities: Optional[List[MessageEntity]]
520

521
class InputMediaVideo:
522
    type: str = "video"
523
    media: str
524
    thumb: Optional[str]
525
    caption: Optional[str]
526
    parse_mode: Optional[str]
527
    caption_entities: Optional[List[MessageEntity]]
528
    width: Optional[int]
529
    height: Optional[int]
530
    duration: Optional[int]
531
    supports_streaming: Optional[bool]
532

533
class Audio:
534
    file_id: str
535
    file_unique_id: str
536
    duration: int
537
    performer: Optional[str]
538
    title: Optional[str]
539
    file_name: Optional[str]
540
    mime_type: Optional[str]
541
    file_size: Optional[int]
542
    thumb: Optional[PhotoSize]
543

544
class Video:
545
    file_id: str
546
    file_unique_id: str
547
    width: int
548
    height: int
549
    duration: int
550
    thumb: Optional[PhotoSize]
551
    file_name: Optional[str]
552
    mime_type: Optional[str]
553
    file_size: Optional[int]
554

555
class Document:
556
    file_id: str
557
    file_unique_id: str
558
    thumb: Optional[PhotoSize]
559
    file_name: Optional[str]
560
    mime_type: Optional[str]
561
    file_size: Optional[int]
562

563
class Location:
564
    longitude: float
565
    latitude: float
566
    horizontal_accuracy: Optional[float]
567
    live_period: Optional[int]
568
    heading: Optional[int]
569
    proximity_alert_radius: Optional[int]
570

571
class Contact:
572
    phone_number: str
573
    first_name: str
574
    last_name: Optional[str]
575
    user_id: Optional[int]
576
    vcard: Optional[str]
577

578
class Sticker:
579
    file_id: str
580
    file_unique_id: str
581
    width: int
582
    height: int
583
    is_animated: bool
584
    thumb: Optional[PhotoSize]
585
    emoji: Optional[str]
586
    set_name: Optional[str]
587
    mask_position: Optional[MaskPosition]
588
    file_size: Optional[int]
589

590
class StickerSet:
591
    name: str
592
    title: str
593
    is_animated: bool
594
    contains_masks: bool
595
    stickers: List[Sticker]
596
    thumb: Optional[PhotoSize]
597

598
class MaskPosition:
599
    point: str  # "forehead", "eyes", "mouth", or "chin"
600
    x_shift: float
601
    y_shift: float
602
    scale: float
603
```