CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-python-telegram-bot

A pure Python, asynchronous interface for the Telegram Bot API with comprehensive wrapper and high-level framework for building sophisticated Telegram bots

—

Pending
Overview
Eval results
Files

bot-api.mddocs/

Bot API

The Bot class provides direct access to all Telegram Bot API methods. It handles HTTP requests, response parsing, and file operations while maintaining full compatibility with the official Telegram Bot API.

Capabilities

Bot Initialization

Create and configure a Bot instance with authentication token and optional settings.

class Bot:
    def __init__(
        self,
        token: str,
        base_url: str = "https://api.telegram.org/bot",
        base_file_url: str = "https://api.telegram.org/file/bot",
        request: BaseRequest = None,
        get_updates_request: BaseRequest = None,
        private_key: bytes = None,
        private_key_password: bytes = None,
        local_mode: bool = False
    ): ...

Usage example:

from telegram import Bot

# Basic initialization
bot = Bot(token="YOUR_BOT_TOKEN")

# With custom configuration
from telegram.request import HTTPXRequest
bot = Bot(
    token="YOUR_BOT_TOKEN",
    request=HTTPXRequest(connection_pool_size=8)
)

Sending Messages

Send text messages with formatting, reply parameters, and keyboard attachments.

async def send_message(
    self,
    chat_id: int | str,
    text: str,
    parse_mode: str = None,
    entities: list[MessageEntity] = None,
    link_preview_options: LinkPreviewOptions = None,
    disable_notification: bool = None,
    protect_content: bool = None,
    reply_parameters: ReplyParameters = None,
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
    message_thread_id: int = None,
    business_connection_id: str = None
) -> Message: ...

Usage example:

from telegram.constants import ParseMode

# Simple text message
message = await bot.send_message(chat_id=123456, text="Hello World!")

# Formatted message with keyboard
from telegram import InlineKeyboardMarkup, InlineKeyboardButton

keyboard = InlineKeyboardMarkup([
    [InlineKeyboardButton("Option 1", callback_data="opt1")]
])

message = await bot.send_message(
    chat_id=123456,
    text="Choose an option:",
    parse_mode=ParseMode.MARKDOWN_V2,
    reply_markup=keyboard
)

Sending Media

Send photos, videos, documents, audio files, and other media with captions and formatting.

async def send_photo(
    self,
    chat_id: int | str,
    photo: InputFile | str,
    caption: str = None,
    parse_mode: str = None,
    caption_entities: list[MessageEntity] = None,
    show_caption_above_media: bool = None,
    has_spoiler: bool = None,
    disable_notification: bool = None,
    protect_content: bool = None,
    reply_parameters: ReplyParameters = None,
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
    message_thread_id: int = None,
    business_connection_id: str = None
) -> Message: ...

async def send_video(
    self,
    chat_id: int | str,
    video: InputFile | str,
    duration: int = None,
    width: int = None,
    height: int = None,
    thumbnail: InputFile | str = None,
    caption: str = None,
    parse_mode: str = None,
    caption_entities: list[MessageEntity] = None,
    show_caption_above_media: bool = None,
    has_spoiler: bool = None,
    supports_streaming: bool = None,
    disable_notification: bool = None,
    protect_content: bool = None,
    reply_parameters: ReplyParameters = None,
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
    message_thread_id: int = None,
    business_connection_id: str = None
) -> Message: ...

async def send_document(
    self,
    chat_id: int | str,
    document: InputFile | str,
    thumbnail: InputFile | str = None,
    caption: str = None,
    parse_mode: str = None,
    caption_entities: list[MessageEntity] = None,
    disable_content_type_detection: bool = None,
    disable_notification: bool = None,
    protect_content: bool = None,
    reply_parameters: ReplyParameters = None,
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
    message_thread_id: int = None,
    business_connection_id: str = None
) -> Message: ...

async def send_audio(
    self,
    chat_id: int | str,
    audio: InputFile | str,
    caption: str = None,
    parse_mode: str = None,
    caption_entities: list[MessageEntity] = None,
    duration: int = None,
    performer: str = None,
    title: str = None,
    thumbnail: InputFile | str = None,
    disable_notification: bool = None,
    protect_content: bool = None,
    reply_parameters: ReplyParameters = None,
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
    message_thread_id: int = None,
    business_connection_id: str = None
) -> Message: ...

async def send_voice(
    self,
    chat_id: int | str,
    voice: InputFile | str,
    duration: int = None,
    caption: str = None,
    parse_mode: str = None,
    caption_entities: list[MessageEntity] = None,
    disable_notification: bool = None,
    protect_content: bool = None,
    reply_parameters: ReplyParameters = None,
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
    message_thread_id: int = None,
    business_connection_id: str = None
) -> Message: ...

async def send_video_note(
    self,
    chat_id: int | str,
    video_note: InputFile | str,
    duration: int = None,
    length: int = None,
    thumbnail: InputFile | str = None,
    disable_notification: bool = None,
    protect_content: bool = None,
    reply_parameters: ReplyParameters = None,
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
    message_thread_id: int = None,
    business_connection_id: str = None
) -> Message: ...

async def send_animation(
    self,
    chat_id: int | str,
    animation: InputFile | str,
    duration: int = None,
    width: int = None,
    height: int = None,
    thumbnail: InputFile | str = None,
    caption: str = None,
    parse_mode: str = None,
    caption_entities: list[MessageEntity] = None,
    has_spoiler: bool = None,
    disable_notification: bool = None,
    protect_content: bool = None,
    reply_parameters: ReplyParameters = None,
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
    message_thread_id: int = None,
    business_connection_id: str = None
) -> Message: ...

async def send_sticker(
    self,
    chat_id: int | str,
    sticker: InputFile | str,
    emoji: str = None,
    disable_notification: bool = None,
    protect_content: bool = None,
    reply_parameters: ReplyParameters = None,
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
    message_thread_id: int = None,
    business_connection_id: str = None
) -> Message: ...

Usage examples:

# Send a voice message
with open("voice.ogg", "rb") as voice_file:
    await bot.send_voice(chat_id=123456, voice=voice_file, caption="Voice message")

# Send an animation (GIF)
await bot.send_animation(
    chat_id=123456, 
    animation="https://example.com/animation.gif",
    caption="Check this out!"
)

# Send a sticker
await bot.send_sticker(chat_id=123456, sticker="CAACAgIAAxkBAAI...")

# Send a video note (circular video)
with open("video_note.mp4", "rb") as video_file:
    await bot.send_video_note(chat_id=123456, video_note=video_file, duration=30)

Sending Location & Contacts

Send location data, venue information, and contact details.

async def send_location(
    self,
    chat_id: int | str,
    latitude: float,
    longitude: float,
    horizontal_accuracy: float = None,
    live_period: int = None,
    heading: int = None,
    proximity_alert_radius: int = None,
    disable_notification: bool = None,
    protect_content: bool = None,
    reply_parameters: ReplyParameters = None,
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
    message_thread_id: int = None,
    business_connection_id: str = None
) -> Message: ...

async def send_venue(
    self,
    chat_id: int | str,
    latitude: float,
    longitude: float,
    title: str,
    address: str,
    foursquare_id: str = None,
    foursquare_type: str = None,
    google_place_id: str = None,
    google_place_type: str = None,
    disable_notification: bool = None,
    protect_content: bool = None,
    reply_parameters: ReplyParameters = None,
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
    message_thread_id: int = None,
    business_connection_id: str = None
) -> Message: ...

async def send_contact(
    self,
    chat_id: int | str,
    phone_number: str,
    first_name: str,
    last_name: str = None,
    vcard: str = None,
    disable_notification: bool = None,
    protect_content: bool = None,
    reply_parameters: ReplyParameters = None,
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
    message_thread_id: int = None,
    business_connection_id: str = None
) -> Message: ...

Usage examples:

# Send current location
await bot.send_location(
    chat_id=123456, 
    latitude=37.7749, 
    longitude=-122.4194
)

# Send live location that updates for 1 hour
await bot.send_location(
    chat_id=123456,
    latitude=37.7749,
    longitude=-122.4194,
    live_period=3600,  # 1 hour in seconds
    horizontal_accuracy=50
)

# Send venue information
await bot.send_venue(
    chat_id=123456,
    latitude=37.7749,
    longitude=-122.4194,
    title="Golden Gate Park",
    address="San Francisco, CA, USA",
    foursquare_id="49e3a8c3f964a520fd1a1fe3"
)

# Send contact information
await bot.send_contact(
    chat_id=123456,
    phone_number="+1234567890",
    first_name="John",
    last_name="Doe",
    vcard="BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nTEL:+1234567890\nEND:VCARD"
)

Getting Updates

Retrieve incoming updates using polling or webhook methods.

async def get_updates(
    self,
    offset: int = None,
    limit: int = None,
    timeout: int = None,
    allowed_updates: list[str] = None
) -> list[Update]: ...

async def set_webhook(
    self,
    url: str,
    certificate: InputFile = None,
    ip_address: str = None,
    max_connections: int = None,
    allowed_updates: list[str] = None,
    drop_pending_updates: bool = None,
    secret_token: str = None
) -> bool: ...

async def delete_webhook(self, drop_pending_updates: bool = None) -> bool: ...

async def get_webhook_info(self) -> WebhookInfo: ...

Bot Information

Get information about the bot and manage bot settings.

async def get_me(self) -> User: ...

async def log_out(self) -> bool: ...

async def close(self) -> bool: ...

async def set_my_commands(
    self,
    commands: list[BotCommand],
    scope: BotCommandScope = None,
    language_code: str = None
) -> bool: ...

async def delete_my_commands(
    self,
    scope: BotCommandScope = None,
    language_code: str = None
) -> bool: ...

async def get_my_commands(
    self,
    scope: BotCommandScope = None,
    language_code: str = None
) -> list[BotCommand]: ...

Chat Management

Manage chat members, permissions, and chat settings.

async def get_chat(self, chat_id: int | str) -> ChatFullInfo: ...

async def get_chat_administrators(self, chat_id: int | str) -> list[ChatMember]: ...

async def get_chat_member_count(self, chat_id: int | str) -> int: ...

async def get_chat_member(self, chat_id: int | str, user_id: int) -> ChatMember: ...

async def set_chat_sticker_set(self, chat_id: int | str, sticker_set_name: str) -> bool: ...

async def delete_chat_sticker_set(self, chat_id: int | str) -> bool: ...

async def ban_chat_member(
    self,
    chat_id: int | str,
    user_id: int,
    until_date: int = None,
    revoke_messages: bool = None
) -> bool: ...

async def unban_chat_member(
    self,
    chat_id: int | str,
    user_id: int,
    only_if_banned: bool = None
) -> bool: ...

async def restrict_chat_member(
    self,
    chat_id: int | str,
    user_id: int,
    permissions: ChatPermissions,
    use_independent_chat_permissions: bool = None,
    until_date: int = None
) -> bool: ...

async def promote_chat_member(
    self,
    chat_id: int | str,
    user_id: int,
    is_anonymous: bool = None,
    can_manage_chat: bool = None,
    can_post_messages: bool = None,
    can_edit_messages: bool = None,
    can_delete_messages: bool = None,
    can_manage_video_chats: bool = None,
    can_restrict_members: bool = None,
    can_promote_members: bool = None,
    can_change_info: bool = None,
    can_invite_users: bool = None,
    can_pin_messages: bool = None,
    can_manage_topics: bool = None
) -> bool: ...

async def set_chat_title(
    self,
    chat_id: int | str,
    title: str
) -> bool: ...

async def set_chat_description(
    self,
    chat_id: int | str,
    description: str = None
) -> bool: ...

async def pin_chat_message(
    self,
    chat_id: int | str,
    message_id: int,
    disable_notification: bool = None,
    business_connection_id: str = None
) -> bool: ...

async def unpin_chat_message(
    self,
    chat_id: int | str,
    message_id: int = None,
    business_connection_id: str = None
) -> bool: ...

Usage examples:

# Update chat title
await bot.set_chat_title(chat_id=-123456789, title="New Group Title")

# Update chat description
await bot.set_chat_description(
    chat_id=-123456789, 
    description="This is the new group description"
)

# Clear description by passing None
await bot.set_chat_description(chat_id=-123456789, description=None)

# Pin a message
await bot.pin_chat_message(chat_id=-123456789, message_id=12345)

# Unpin a specific message
await bot.unpin_chat_message(chat_id=-123456789, message_id=12345)

# Unpin most recent pinned message
await bot.unpin_chat_message(chat_id=-123456789)

File Operations

Download files and get file information.

async def get_file(self, file_id: str) -> File: ...

Usage example:

# Get file object and download
file = await bot.get_file(file_id="BAADBAADrwADBREAAYdaO-...")
await file.download_to_drive("downloaded_file.jpg")

Message Operations

Edit, forward, copy, and delete messages.

async def edit_message_text(
    self,
    text: str,
    chat_id: int | str = None,
    message_id: int = None,
    inline_message_id: str = None,
    parse_mode: str = None,
    entities: list[MessageEntity] = None,
    link_preview_options: LinkPreviewOptions = None,
    reply_markup: InlineKeyboardMarkup = None
) -> Message | bool: ...

async def edit_message_caption(
    self,
    chat_id: int | str = None,
    message_id: int = None,
    inline_message_id: str = None,
    caption: str = None,
    parse_mode: str = None,
    caption_entities: list[MessageEntity] = None,
    show_caption_above_media: bool = None,
    reply_markup: InlineKeyboardMarkup = None
) -> Message | bool: ...

async def edit_message_reply_markup(
    self,
    chat_id: int | str = None,
    message_id: int = None,
    inline_message_id: str = None,
    reply_markup: InlineKeyboardMarkup = None
) -> Message | bool: ...

async def delete_message(self, chat_id: int | str, message_id: int) -> bool: ...

async def forward_message(
    self,
    chat_id: int | str,
    from_chat_id: int | str,
    message_id: int,
    disable_notification: bool = None,
    protect_content: bool = None,
    message_thread_id: int = None
) -> Message: ...

async def copy_message(
    self,
    chat_id: int | str,
    from_chat_id: int | str,
    message_id: int,
    caption: str = None,
    parse_mode: str = None,
    caption_entities: list[MessageEntity] = None,
    show_caption_above_media: bool = None,
    disable_notification: bool = None,
    protect_content: bool = None,
    reply_parameters: ReplyParameters = None,
    reply_markup: InlineKeyboardMarkup | ReplyKeyboardMarkup | ReplyKeyboardRemove | ForceReply = None,
    message_thread_id: int = None
) -> MessageId: ...

Inline Queries

Handle inline query results and prepared inline messages.

async def answer_inline_query(
    self,
    inline_query_id: str,
    results: list[InlineQueryResult],
    cache_time: int = None,
    is_personal: bool = None,
    next_offset: str = None,
    button: InlineQueryResultsButton = None
) -> bool: ...

async def save_prepared_inline_message(
    self,
    user_id: int,
    result: InlineQueryResult,
    allow_user_chats: bool = None,
    allow_bot_chats: bool = None,
    allow_group_chats: bool = None,
    allow_channel_chats: bool = None
) -> PreparedInlineMessage: ...

Callback Queries

Answer callback queries from inline keyboard buttons.

async def answer_callback_query(
    self,
    callback_query_id: str,
    text: str = None,
    show_alert: bool = None,
    url: str = None,
    cache_time: int = None
) -> bool: ...

Types

class BotCommand:
    command: str
    description: str
    def __init__(self, command: str, description: str): ...

class BotCommandScope:
    type: str

class BotCommandScopeDefault(BotCommandScope):
    def __init__(self): ...

class BotCommandScopeAllPrivateChats(BotCommandScope):
    def __init__(self): ...

class BotCommandScopeAllGroupChats(BotCommandScope):
    def __init__(self): ...

class BotCommandScopeAllChatAdministrators(BotCommandScope):
    def __init__(self): ...

class BotCommandScopeChat(BotCommandScope):
    chat_id: int | str
    def __init__(self, chat_id: int | str): ...

class BotCommandScopeChatAdministrators(BotCommandScope):
    chat_id: int | str
    def __init__(self, chat_id: int | str): ...

class BotCommandScopeChatMember(BotCommandScope):
    chat_id: int | str
    user_id: int
    def __init__(self, chat_id: int | str, user_id: int): ...

class WebhookInfo:
    url: str
    has_custom_certificate: bool
    pending_update_count: int
    ip_address: str | None
    last_error_date: int | None
    last_error_message: str | None
    last_synchronization_error_date: int | None
    max_connections: int | None
    allowed_updates: list[str] | None

Install with Tessl CLI

npx tessl i tessl/pypi-python-telegram-bot

docs

advanced-features.md

application-framework.md

bot-api.md

files.md

filters.md

handlers.md

index.md

keyboards.md

telegram-types.md

tile.json