tessl/pypi-py-telegram-bot-api
Python Telegram bot API library providing a simple, extensible interface for building Telegram bots with complete Bot API support
—
Pending
media-handling.mddocs/
Media Handling
Sending and managing multimedia content including photos, videos, audio, documents, stickers, animations, and media groups with thumbnail and metadata support.
Capabilities
Photo Handling
Send and manage photo content with captions, thumbnails, and metadata.
def send_photo(self, chat_id: Union[int, str], photo: Union[Any, str],
caption: Optional[str] = None,
reply_to_message_id: Optional[int] = None,
reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
parse_mode: Optional[str] = None,
disable_notification: Optional[bool] = None,
timeout: Optional[int] = None,
caption_entities: Optional[List[types.MessageEntity]] = None,
allow_sending_without_reply: Optional[bool] = None) -> types.Message:
"""
Send photos with optional captions and formatting.
Parameters:
- chat_id (Union[int, str]): Target chat ID or username
- photo (Union[Any, str]): Photo file, file path, URL, or file_id
- caption (str, optional): Photo caption (0-1024 characters)
- reply_to_message_id (int, optional): Message ID to reply to
- reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
- parse_mode (str, optional): Caption parsing mode
- disable_notification (bool, optional): Send silently
- timeout (int, optional): Request timeout
- caption_entities (List[MessageEntity], optional): Caption entities
- allow_sending_without_reply (bool, optional): Send if reply target missing
Returns:
Message: Sent photo message
"""Video Handling
Send videos with duration, thumbnails, and caption support.
def send_video(self, chat_id: Union[int, str], data: Union[Any, str],
duration: Optional[int] = None,
caption: Optional[str] = None,
reply_to_message_id: Optional[int] = None,
reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
parse_mode: Optional[str] = None,
supports_streaming: Optional[bool] = None,
disable_notification: Optional[bool] = None,
timeout: Optional[int] = None,
thumb: Optional[Union[Any, str]] = None,
width: Optional[int] = None,
height: Optional[int] = None,
caption_entities: Optional[List[types.MessageEntity]] = None,
allow_sending_without_reply: Optional[bool] = None) -> types.Message:
"""
Send video files with metadata and thumbnails.
Parameters:
- chat_id (Union[int, str]): Target chat
- data (Union[Any, str]): Video file, path, URL, or file_id
- duration (int, optional): Video duration in seconds
- caption (str, optional): Video caption
- reply_to_message_id (int, optional): Message to reply to
- reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
- parse_mode (str, optional): Caption parsing mode
- supports_streaming (bool, optional): Pass True for streaming support
- disable_notification (bool, optional): Send silently
- timeout (int, optional): Request timeout
- thumb (Union[Any, str], optional): Thumbnail file
- width (int, optional): Video width
- height (int, optional): Video height
- caption_entities (List[MessageEntity], optional): Caption entities
- allow_sending_without_reply (bool, optional): Send if reply target missing
Returns:
Message: Sent video message
"""
def send_video_note(self, chat_id: Union[int, str], data: Union[Any, str],
duration: Optional[int] = None,
length: Optional[int] = None,
reply_to_message_id: Optional[int] = None,
reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
disable_notification: Optional[bool] = None,
timeout: Optional[int] = None,
thumb: Optional[Union[Any, str]] = None,
allow_sending_without_reply: Optional[bool] = None) -> types.Message:
"""
Send video messages (rounded square mp4 videos up to 1 minute).
Parameters:
- chat_id (Union[int, str]): Target chat
- data (Union[Any, str]): Video note file or file_id
- duration (int, optional): Video duration in seconds
- length (int, optional): Video width and height (0-640)
- reply_to_message_id (int, optional): Message to reply to
- reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
- disable_notification (bool, optional): Send silently
- timeout (int, optional): Request timeout
- thumb (Union[Any, str], optional): Thumbnail file
- allow_sending_without_reply (bool, optional): Send if reply target missing
Returns:
Message: Sent video note message
"""Audio Handling
Send audio files and voice messages with metadata support.
def send_audio(self, chat_id: Union[int, str], audio: Union[Any, str],
caption: Optional[str] = None,
duration: Optional[int] = None,
performer: Optional[str] = None,
title: Optional[str] = None,
reply_to_message_id: Optional[int] = None,
reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
parse_mode: Optional[str] = None,
disable_notification: Optional[bool] = None,
timeout: Optional[int] = None,
thumb: Optional[Union[Any, str]] = None,
caption_entities: Optional[List[types.MessageEntity]] = None,
allow_sending_without_reply: Optional[bool] = None) -> types.Message:
"""
Send audio files for music player display (.mp3 format).
Parameters:
- chat_id (Union[int, str]): Target chat
- audio (Union[Any, str]): Audio file, path, URL, or file_id
- caption (str, optional): Audio caption
- duration (int, optional): Audio duration in seconds
- performer (str, optional): Performer name
- title (str, optional): Track name
- reply_to_message_id (int, optional): Message to reply to
- reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
- parse_mode (str, optional): Caption parsing mode
- disable_notification (bool, optional): Send silently
- timeout (int, optional): Request timeout
- thumb (Union[Any, str], optional): Thumbnail file
- caption_entities (List[MessageEntity], optional): Caption entities
- allow_sending_without_reply (bool, optional): Send if reply target missing
Returns:
Message: Sent audio message
"""
def send_voice(self, chat_id: Union[int, str], voice: Union[Any, str],
caption: Optional[str] = None,
duration: Optional[int] = None,
reply_to_message_id: Optional[int] = None,
reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
parse_mode: Optional[str] = None,
disable_notification: Optional[bool] = None,
timeout: Optional[int] = None,
caption_entities: Optional[List[types.MessageEntity]] = None,
allow_sending_without_reply: Optional[bool] = None) -> types.Message:
"""
Send audio files as voice messages.
Parameters:
- chat_id (Union[int, str]): Target chat
- voice (Union[Any, str]): Voice file, path, URL, or file_id
- caption (str, optional): Voice message caption
- duration (int, optional): Duration in seconds
- reply_to_message_id (int, optional): Message to reply to
- reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
- parse_mode (str, optional): Caption parsing mode
- disable_notification (bool, optional): Send silently
- timeout (int, optional): Request timeout
- caption_entities (List[MessageEntity], optional): Caption entities
- allow_sending_without_reply (bool, optional): Send if reply target missing
Returns:
Message: Sent voice message
"""Document Handling
Send general files and documents with custom filenames and thumbnails.
def send_document(self, chat_id: Union[int, str], data: Union[Any, str],
reply_to_message_id: Optional[int] = None,
caption: Optional[str] = None,
reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
parse_mode: Optional[str] = None,
disable_notification: Optional[bool] = None,
timeout: Optional[int] = None,
thumb: Optional[Union[Any, str]] = None,
caption_entities: Optional[List[types.MessageEntity]] = None,
allow_sending_without_reply: Optional[bool] = None,
visible_file_name: Optional[str] = None,
disable_content_type_detection: Optional[bool] = None) -> types.Message:
"""
Send general files and documents.
Parameters:
- chat_id (Union[int, str]): Target chat
- data (Union[Any, str]): Document file, path, URL, or file_id
- reply_to_message_id (int, optional): Message to reply to
- caption (str, optional): Document caption (0-1024 characters)
- reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
- parse_mode (str, optional): Caption parsing mode
- disable_notification (bool, optional): Send silently
- timeout (int, optional): Request timeout
- thumb (Union[Any, str], optional): Thumbnail file (JPEG, <200kB, <320px)
- caption_entities (List[MessageEntity], optional): Caption entities
- allow_sending_without_reply (bool, optional): Send if reply target missing
- visible_file_name (str, optional): Custom filename for display
- disable_content_type_detection (bool, optional): Disable server-side detection
Returns:
Message: Sent document message
"""Animation and Sticker Handling
Send GIF animations and stickers.
def send_animation(self, chat_id: Union[int, str], animation: Union[Any, str],
duration: Optional[int] = None,
caption: Optional[str] = None,
reply_to_message_id: Optional[int] = None,
reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
parse_mode: Optional[str] = None,
disable_notification: Optional[bool] = None,
timeout: Optional[int] = None,
thumb: Optional[Union[Any, str]] = None,
caption_entities: Optional[List[types.MessageEntity]] = None,
allow_sending_without_reply: Optional[bool] = None) -> types.Message:
"""
Send animation files (GIF or H.264/MPEG-4 AVC video without sound).
Parameters:
- chat_id (Union[int, str]): Target chat
- animation (Union[Any, str]): Animation file, path, URL, or file_id
- duration (int, optional): Animation duration in seconds
- caption (str, optional): Animation caption
- reply_to_message_id (int, optional): Message to reply to
- reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
- parse_mode (str, optional): Caption parsing mode
- disable_notification (bool, optional): Send silently
- timeout (int, optional): Request timeout
- thumb (Union[Any, str], optional): Thumbnail file
- caption_entities (List[MessageEntity], optional): Caption entities
- allow_sending_without_reply (bool, optional): Send if reply target missing
Returns:
Message: Sent animation message
"""
def send_sticker(self, chat_id: Union[int, str], data: Union[Any, str],
reply_to_message_id: Optional[int] = None,
reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
disable_notification: Optional[bool] = None,
timeout: Optional[int] = None,
allow_sending_without_reply: Optional[bool] = None) -> types.Message:
"""
Send .webp stickers.
Parameters:
- chat_id (Union[int, str]): Target chat
- data (Union[Any, str]): Sticker file, path, URL, or file_id
- reply_to_message_id (int, optional): Message to reply to
- reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
- disable_notification (bool, optional): Send silently
- timeout (int, optional): Request timeout
- allow_sending_without_reply (bool, optional): Send if reply target missing
Returns:
Message: Sent sticker message
"""Sticker Management
Create, manage, and modify custom sticker sets for your bot.
def create_new_sticker_set(self, user_id: int, name: str, title: str,
emojis: str,
png_sticker: Optional[Union[Any, str]] = None,
tgs_sticker: Optional[Union[Any, str]] = None,
contains_masks: Optional[bool] = None,
mask_position: Optional[types.MaskPosition] = None) -> bool:
"""
Create a new sticker set owned by a user.
The bot will be able to edit the created sticker set.
Parameters:
- user_id (int): User identifier of created sticker set owner
- name (str): Short name of sticker set (1-64 characters, lowercase letters, digits, underscores)
- title (str): Sticker set title (1-64 characters)
- emojis (str): One or more emoji corresponding to the sticker
- png_sticker (Union[Any, str], optional): PNG image or file ID
- tgs_sticker (Union[Any, str], optional): TGS animation or file ID
- contains_masks (bool, optional): True if stickers in set are masks
- mask_position (MaskPosition, optional): Position where mask is placed
Returns:
bool: True on success
"""
def add_sticker_to_set(self, user_id: int, name: str, emojis: str,
png_sticker: Optional[Union[Any, str]] = None,
tgs_sticker: Optional[Union[Any, str]] = None,
mask_position: Optional[types.MaskPosition] = None) -> bool:
"""
Add a new sticker to a set created by the bot.
Either png_sticker or tgs_sticker is required.
Parameters:
- user_id (int): User identifier of sticker set owner
- name (str): Sticker set name
- emojis (str): One or more emoji corresponding to the sticker
- png_sticker (Union[Any, str], optional): PNG image or file ID
- tgs_sticker (Union[Any, str], optional): TGS animation or file ID
- mask_position (MaskPosition, optional): Position where mask is placed
Returns:
bool: True on success
"""
def delete_sticker_from_set(self, sticker: str) -> bool:
"""
Delete a sticker from a set created by the bot.
Parameters:
- sticker (str): File identifier of the sticker
Returns:
bool: True on success
"""
def set_sticker_set_thumb(self, name: str, user_id: int,
thumb: Optional[Union[Any, str]] = None) -> bool:
"""
Set the thumbnail of a sticker set.
Animated thumbnails can be set for animated sticker sets only.
Parameters:
- name (str): Sticker set name
- user_id (int): User identifier of the sticker set owner
- thumb (Union[Any, str], optional): PNG image or file ID for thumbnail
Returns:
bool: True on success
"""
def upload_sticker_file(self, user_id: int, png_sticker: Union[Any, str]) -> types.File:
"""
Upload a PNG file with a sticker for later use in sticker set operations.
Parameters:
- user_id (int): User identifier of sticker file owner
- png_sticker (Union[Any, str]): PNG image file
Returns:
File: Information about the uploaded file
"""Media Groups
Send multiple media files as an album.
def send_media_group(self, chat_id: Union[int, str],
media: List[Union[types.InputMediaAudio, types.InputMediaDocument,
types.InputMediaPhoto, types.InputMediaVideo]],
disable_notification: Optional[bool] = None,
reply_to_message_id: Optional[int] = None,
timeout: Optional[int] = None,
allow_sending_without_reply: Optional[bool] = None) -> List[types.Message]:
"""
Send a group of photos or videos as an album.
Parameters:
- chat_id (Union[int, str]): Target chat
- media (List[InputMedia]): Array of photos and videos (2-10 items)
- disable_notification (bool, optional): Send silently
- reply_to_message_id (int, optional): Message to reply to
- timeout (int, optional): Request timeout
- allow_sending_without_reply (bool, optional): Send if reply target missing
Returns:
List[Message]: Array of sent messages
"""Location and Contact Sharing
Send location data and contact information.
def send_location(self, chat_id: Union[int, str], latitude: float, longitude: float,
live_period: Optional[int] = None,
reply_to_message_id: Optional[int] = None,
reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
disable_notification: Optional[bool] = None,
timeout: Optional[int] = None,
horizontal_accuracy: Optional[float] = None,
heading: Optional[int] = None,
proximity_alert_radius: Optional[int] = None,
allow_sending_without_reply: Optional[bool] = None) -> types.Message:
"""
Send point on the map with optional live location.
Parameters:
- chat_id (Union[int, str]): Target chat
- latitude (float): Latitude of the location
- longitude (float): Longitude of the location
- live_period (int, optional): Live location period in seconds (60-86400)
- reply_to_message_id (int, optional): Message to reply to
- reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
- disable_notification (bool, optional): Send silently
- timeout (int, optional): Request timeout
- horizontal_accuracy (float, optional): Radius uncertainty in meters (0-1500)
- heading (int, optional): Direction in degrees (1-360)
- proximity_alert_radius (int, optional): Alert radius in meters (1-100000)
- allow_sending_without_reply (bool, optional): Send if reply target missing
Returns:
Message: Sent location message
"""
def send_contact(self, chat_id: Union[int, str], phone_number: str,
first_name: str, last_name: Optional[str] = None,
vcard: Optional[str] = None,
disable_notification: Optional[bool] = None,
reply_to_message_id: Optional[int] = None,
reply_markup: Optional[REPLY_MARKUP_TYPES] = None,
timeout: Optional[int] = None,
allow_sending_without_reply: Optional[bool] = None) -> types.Message:
"""
Send phone contact information.
Parameters:
- chat_id (Union[int, str]): Target chat
- phone_number (str): Contact's phone number
- first_name (str): Contact's first name
- last_name (str, optional): Contact's last name
- vcard (str, optional): vCard data for additional contact info
- disable_notification (bool, optional): Send silently
- reply_to_message_id (int, optional): Message to reply to
- reply_markup (REPLY_MARKUP_TYPES, optional): Keyboard markup
- timeout (int, optional): Request timeout
- allow_sending_without_reply (bool, optional): Send if reply target missing
Returns:
Message: Sent contact message
"""Usage Examples
Photo Sending Example
# Send photo from file
with open('photo.jpg', 'rb') as photo:
bot.send_photo(chat_id, photo, caption="A beautiful photo!")
# Send photo by URL
bot.send_photo(chat_id, "https://example.com/photo.jpg")
# Send photo with inline keyboard
from telebot import types
markup = types.InlineKeyboardMarkup()
markup.add(types.InlineKeyboardButton("Like", callback_data="like"))
bot.send_photo(chat_id, photo, caption="Rate this photo:", reply_markup=markup)Media Group Example
from telebot import types
# Create media group with mixed content
media_group = [
types.InputMediaPhoto("photo1.jpg", caption="Photo 1"),
types.InputMediaPhoto("photo2.jpg", caption="Photo 2"),
types.InputMediaVideo("video.mp4", caption="Video")
]
bot.send_media_group(chat_id, media_group)Live Location Example
# Send live location for 1 hour
bot.send_location(
chat_id=chat_id,
latitude=40.7128,
longitude=-74.0060,
live_period=3600, # 1 hour
horizontal_accuracy=10.0
)Types
class InputMediaPhoto:
type: str = "photo"
media: str
caption: Optional[str]
parse_mode: Optional[str]
caption_entities: Optional[List[MessageEntity]]
class InputMediaVideo:
type: str = "video"
media: str
thumb: Optional[str]
caption: Optional[str]
parse_mode: Optional[str]
caption_entities: Optional[List[MessageEntity]]
width: Optional[int]
height: Optional[int]
duration: Optional[int]
supports_streaming: Optional[bool]
class Audio:
file_id: str
file_unique_id: str
duration: int
performer: Optional[str]
title: Optional[str]
file_name: Optional[str]
mime_type: Optional[str]
file_size: Optional[int]
thumb: Optional[PhotoSize]
class Video:
file_id: str
file_unique_id: str
width: int
height: int
duration: int
thumb: Optional[PhotoSize]
file_name: Optional[str]
mime_type: Optional[str]
file_size: Optional[int]
class Document:
file_id: str
file_unique_id: str
thumb: Optional[PhotoSize]
file_name: Optional[str]
mime_type: Optional[str]
file_size: Optional[int]
class Location:
longitude: float
latitude: float
horizontal_accuracy: Optional[float]
live_period: Optional[int]
heading: Optional[int]
proximity_alert_radius: Optional[int]
class Contact:
phone_number: str
first_name: str
last_name: Optional[str]
user_id: Optional[int]
vcard: Optional[str]
class Sticker:
file_id: str
file_unique_id: str
width: int
height: int
is_animated: bool
thumb: Optional[PhotoSize]
emoji: Optional[str]
set_name: Optional[str]
mask_position: Optional[MaskPosition]
file_size: Optional[int]
class StickerSet:
name: str
title: str
is_animated: bool
contains_masks: bool
stickers: List[Sticker]
thumb: Optional[PhotoSize]
class MaskPosition:
point: str # "forehead", "eyes", "mouth", or "chin"
x_shift: float
y_shift: float
scale: floatInstall with Tessl CLI
npx tessl i tessl/pypi-py-telegram-bot-api