DEV Community: Telegram Bot Engineering Note

How to Receive and Download Photos and Files with a Telegram Bot in Python

Telegram Bot Engineering Note — Mon, 17 Aug 2026 17:12:55 +0000

Telegram bots can do more than reply to text messages. They can receive photos, PDF files, spreadsheets, ZIP archives, and other documents sent by users.

In this tutorial, we will build a Python bot that:

Detects photos and documents
Reads their metadata
Downloads them to a local folder
Creates safe, unique filenames
Rejects unsupported or oversized uploads
Explains the difference between file_id and file_unique_id

The example uses the asynchronous python-telegram-bot library.

Prerequisites

You need:

Python 3.10 or newer
A Telegram bot created through BotFather
Your bot token
The python-telegram-bot package

If Telegram is not yet installed on your test device, use this Telegram download guide to choose the appropriate mobile or desktop version.

Install the Python package:

pip install python-telegram-bot

Keep your bot token in an environment variable instead of placing it directly inside the source code.

Linux or macOS:

export TELEGRAM_BOT_TOKEN="YOUR_BOT_TOKEN"

Windows PowerShell:

$env:TELEGRAM_BOT_TOKEN="YOUR_BOT_TOKEN"
How Telegram Represents Uploaded Files

When a user sends media, Telegram does not immediately place the actual file contents inside the update.

Instead, the update contains information such as:

file_id: Used by your bot to retrieve or resend the file
file_unique_id: A stable identifier for recognizing the same file
file_size: Approximate file size in bytes
file_name: Original name of a document, when available
mime_type: Reported media type
Photo dimensions and available sizes

Your bot passes the file_id to Telegram’s getFile method. The returned File object can then be downloaded.

A photo message normally contains several PhotoSize objects. Telegram generates these versions at different resolutions. The last item is generally the largest available version:

photo = update.message.photo[-1]

Documents are available through:

document = update.message.document
Receiving and Downloading a Photo

Create a file named bot.py and start with the following handler:

from pathlib import Path
from uuid import uuid4

from telegram import Update
from telegram.ext import ContextTypes

DOWNLOAD_DIR = Path("downloads").resolve()
DOWNLOAD_DIR.mkdir(parents=True, exist_ok=True)

async def receive_photo(
update: Update,
context: ContextTypes.DEFAULT_TYPE
) -> None:
message = update.effective_message

if not message or not message.photo:
    return

photo = message.photo[-1]

telegram_file = await context.bot.get_file(photo.file_id)

filename = f"{uuid4().hex}.jpg"
destination = DOWNLOAD_DIR / filename

await telegram_file.download_to_drive(
    custom_path=destination
)

await message.reply_text(
    f"Photo received successfully.\nSaved as: {filename}"
)

The handler performs four operations:

Selects the largest photo version
Retrieves its File object
Generates a unique local filename
Downloads the photo into the downloads directory

The download_to_drive() documentation describes the available download behavior in python-telegram-bot.

Receiving Documents Safely

Documents require more validation because users can upload many different file formats.

For this example, we will allow:

PDF
TXT
CSV
JSON
ZIP

We will also apply an application-level limit of 10 MB.

MAX_FILE_SIZE = 10 * 1024 * 1024

ALLOWED_EXTENSIONS = {
".pdf",
".txt",
".csv",
".json",
".zip",
}

Now create the document handler:

async def receive_document(
update: Update,
context: ContextTypes.DEFAULT_TYPE
) -> None:
message = update.effective_message

if not message or not message.document:
    return

document = message.document

if document.file_size and document.file_size > MAX_FILE_SIZE:
    await message.reply_text(
        "This file is too large. The current limit is 10 MB."
    )
    return

original_name = Path(
    document.file_name or "upload.bin"
).name

extension = Path(original_name).suffix.lower()

if extension not in ALLOWED_EXTENSIONS:
    await message.reply_text(
        "Unsupported file type. Please send a PDF, TXT, CSV, JSON, or ZIP file."
    )
    return

safe_filename = f"{uuid4().hex}{extension}"
destination = DOWNLOAD_DIR / safe_filename

telegram_file = await context.bot.get_file(
    document.file_id
)

await telegram_file.download_to_drive(
    custom_path=destination
)

await message.reply_text(
    "Document received successfully.\n"
    f"Original name: {original_name}\n"
    f"Stored as: {safe_filename}"
)

Why Generate a New Filename?

Saving an uploaded document using its original name can create several problems.

Two users might upload files with the same name:

report.pdf

A malicious filename might also contain path components intended to escape the download directory.

Using this line removes path information:

original_name = Path(document.file_name).name

Generating a UUID-based filename also prevents accidental overwrites:

safe_filename = f"{uuid4().hex}{extension}"

Do not assume that a filename extension or MIME type proves that a file is safe. Both values can be misleading. A production application should inspect file contents and scan untrusted uploads before further processing.

Complete Working Bot

Here is the complete example:

import logging
import os
from pathlib import Path
from uuid import uuid4

from telegram import Update
from telegram.ext import (
Application,
CommandHandler,
ContextTypes,
MessageHandler,
filters,
)

logging.basicConfig(
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
level=logging.INFO,
)

logger = logging.getLogger(name)

DOWNLOAD_DIR = Path("downloads").resolve()
DOWNLOAD_DIR.mkdir(parents=True, exist_ok=True)

MAX_FILE_SIZE = 10 * 1024 * 1024

ALLOWED_EXTENSIONS = {
".pdf",
".txt",
".csv",
".json",
".zip",
}

async def start(
update: Update,
context: ContextTypes.DEFAULT_TYPE
) -> None:
await update.effective_message.reply_text(
"Send me a photo or an allowed document.\n"
"Supported documents: PDF, TXT, CSV, JSON, and ZIP."
)

async def receive_photo(
update: Update,
context: ContextTypes.DEFAULT_TYPE
) -> None:
message = update.effective_message

if not message or not message.photo:
    return

photo = message.photo[-1]

if photo.file_size and photo.file_size > MAX_FILE_SIZE:
    await message.reply_text(
        "This photo is too large. The current limit is 10 MB."
    )
    return

telegram_file = await context.bot.get_file(
    photo.file_id
)

filename = f"{uuid4().hex}.jpg"
destination = DOWNLOAD_DIR / filename

await telegram_file.download_to_drive(
    custom_path=destination
)

logger.info(
    "Saved photo %s as %s",
    photo.file_unique_id,
    filename,
)

await message.reply_text(
    f"Photo downloaded successfully.\nFile ID: {filename}"
)

async def receive_document(
update: Update,
context: ContextTypes.DEFAULT_TYPE
) -> None:
message = update.effective_message

if not message or not message.document:
    return

document = message.document

if document.file_size and document.file_size > MAX_FILE_SIZE:
    await message.reply_text(
        "This document is too large. The current limit is 10 MB."
    )
    return

original_name = Path(
    document.file_name or "upload.bin"
).name

extension = Path(original_name).suffix.lower()

if extension not in ALLOWED_EXTENSIONS:
    await message.reply_text(
        "Unsupported file type.\n"
        "Allowed formats: PDF, TXT, CSV, JSON, and ZIP."
    )
    return

safe_filename = f"{uuid4().hex}{extension}"
destination = DOWNLOAD_DIR / safe_filename

telegram_file = await context.bot.get_file(
    document.file_id
)

await telegram_file.download_to_drive(
    custom_path=destination
)

logger.info(
    "Saved document %s as %s",
    document.file_unique_id,
    safe_filename,
)

await message.reply_text(
    "Document downloaded successfully.\n"
    f"Original name: {original_name}\n"
    f"File ID: {safe_filename}"
)

async def unsupported_file(
update: Update,
context: ContextTypes.DEFAULT_TYPE
) -> None:
await update.effective_message.reply_text(
"I cannot process this message type yet. "
"Please send a photo or a supported document."
)

async def error_handler(
update: object,
context: ContextTypes.DEFAULT_TYPE
) -> None:
logger.exception(
"An error occurred while processing an update",
exc_info=context.error,
)

def main() -> None:
token = os.getenv("TELEGRAM_BOT_TOKEN")

if not token:
    raise RuntimeError(
        "The TELEGRAM_BOT_TOKEN environment variable is missing."
    )

application = Application.builder().token(token).build()

application.add_handler(
    CommandHandler("start", start)
)

application.add_handler(
    MessageHandler(filters.PHOTO, receive_photo)
)

application.add_handler(
    MessageHandler(
        filters.Document.ALL,
        receive_document,
    )
)

application.add_handler(
    MessageHandler(
        ~filters.COMMAND,
        unsupported_file,
    )
)

application.add_error_handler(error_handler)

application.run_polling()

if name == "main":
main()

Run the bot:

python bot.py

Open your bot in Telegram, send /start, and then upload a photo or supported document.

The downloaded files will appear in:

downloads/
file_id vs. file_unique_id

These two values serve different purposes.

file_id

A file_id can be passed to Telegram API methods. Your bot can use it to retrieve or resend a previously uploaded file without uploading that file again.

However, a file_id is associated with the bot that received it. It should not be treated as a universal public identifier.

file_unique_id

A file_unique_id helps identify the same file over time and across bots.

It is useful for:

Detecting duplicate uploads
Creating database references
Comparing previously received media

It cannot be used directly to download or resend a file.

A practical database record could contain:

file_id
file_unique_id
original_name
stored_name
file_size
uploaded_by
uploaded_at
Important Security Rules

File-upload bots should be treated like public upload forms. Never trust uploaded content automatically.

Apply these precautions:

Set your own size limit. Reject files before downloading whenever file_size is available.
Generate server-side filenames. Do not use raw user filenames as storage paths.
Use an extension allowlist. Reject formats your application does not need.
Inspect actual contents. File extensions and MIME types can be forged.
Store uploads outside the public web root.
Never execute uploaded files.
Scan untrusted files before opening or processing them.
Restrict access by user ID if the bot is intended for a private team.
Avoid exposing local server paths in bot replies.
Review Telegram’s current file limits before designing large-file workflows.

The official MessageFilter documentation lists filters for photos, documents, MIME types, extensions, videos, audio, voice messages, and other Telegram content.

Common Problems
The Photo Handler Does Not Run

Confirm that the photo handler is registered before a broad fallback handler:

application.add_handler(
MessageHandler(filters.PHOTO, receive_photo)
)

Handler order matters because an earlier matching handler in the same group may process the update first.

The Download Directory Is Missing

Create it before starting the bot:

DOWNLOAD_DIR.mkdir(
parents=True,
exist_ok=True
)
The Bot Rejects a Valid File

Print or log the received filename and MIME type:

logger.info(
"Received %s with MIME type %s",
document.file_name,
document.mime_type,
)

Then check whether its extension is included in ALLOWED_EXTENSIONS.

Downloading Large Files Fails

Telegram’s Bot API, the selected library, your network, and your hosting environment may impose different constraints. Check the current Bot API documentation and configure an application-level limit suitable for your server.

Where to Go Next

After receiving files successfully, you can extend the bot to:

Upload files to cloud object storage
Save metadata in PostgreSQL or SQLite
Generate image thumbnails
Extract text from PDF documents
Scan uploads for malware
Detect duplicate files with file_unique_id
Restrict uploads to approved Telegram users
Send processing results back to the user

The core workflow remains the same: validate the incoming message, obtain its file_id, request the File object, and download it to a controlled destination.

繁體中文摘要

這篇教學示範如何使用 Python 與 python-telegram-bot 接收 Telegram 使用者傳送的照片及文件。程式會透過 file_id 取得檔案、限制檔案大小、檢查副檔名，並以 UUID 產生不重複的安全檔名。

正式部署時，不應直接信任使用者提供的檔名、MIME 類型或副檔名。建議將上傳內容存放在網站公開目錄以外，加入檔案內容檢查、惡意程式掃描及使用者權限限制，避免上傳功能成為安全漏洞。

How to Add a Command Menu to a Telegram Bot with Python

Telegram Bot Engineering Note — Mon, 17 Aug 2026 17:07:55 +0000

A Telegram bot can recognize commands without displaying them in the client. However, users should not have to memorize every available command. Registering a command menu lets Telegram show a list when someone taps the menu button or types /.

In this tutorial, we will create /start, /help, and /status handlers, register them through the Bot API, and display different command menus in private chats and groups.

What Is a Telegram Bot Command Menu?

A bot command begins with a slash:

/start
/help
/status

A registered command has two parts:

command: the value users send, without the leading slash.
description: a short explanation shown in the Telegram interface.

For example:

start - Start the bot
help - Show available commands
status - Check the service status

Registering this list improves discoverability, but it does not create the command logic. Your Python application must still contain a handler for every command.

If /status appears in the menu but no CommandHandler exists for it, Telegram will send the command to the bot, but the program will not know how to respond.

Prerequisites

You will need:

Python 3.10 or newer
A Telegram bot created through BotFather
A valid bot token
The python-telegram-bot package
Basic knowledge of Python functions

If the Telegram client is not installed on your test device, follow this Telegram download guide before starting.

Create a project directory:

mkdir telegram-command-menu
cd telegram-command-menu

Create a virtual environment:

python -m venv .venv

Activate it on macOS or Linux:

source .venv/bin/activate

Activate it in Windows PowerShell:

.venv\Scripts\Activate.ps1

Install the library:

python -m pip install --upgrade python-telegram-bot

Store the bot token in an environment variable.

macOS or Linux:

export TELEGRAM_BOT_TOKEN='PASTE_YOUR_TOKEN_HERE'

Windows PowerShell:

$env:TELEGRAM_BOT_TOKEN="PASTE_YOUR_TOKEN_HERE"

Do not place a real token directly in a public code sample or repository.

Create the Command Handlers

Create a file named bot.py:

import os

from telegram import Update
from telegram.ext import (
    Application,
    CommandHandler,
    ContextTypes,
)


async def start(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
) -> None:
    if update.message is None:
        return

    user = update.effective_user
    name = user.first_name if user else "there"

    await update.message.reply_text(
        f"Hello, {name}! Use /help to view available commands."
    )


async def help_command(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
) -> None:
    if update.message is None:
        return

    await update.message.reply_text(
        "Available commands:\n\n"
        "/start - Start the bot\n"
        "/help - Show this help message\n"
        "/status - Check the service status"
    )


async def status(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
) -> None:
    if update.message is None:
        return

    await update.message.reply_text(
        "🟢 The service is operating normally."
    )


def main() -> None:
    token = os.environ.get("TELEGRAM_BOT_TOKEN")

    if not token:
        raise RuntimeError(
            "The TELEGRAM_BOT_TOKEN environment variable is missing."
        )

    application = Application.builder().token(token).build()

    application.add_handler(CommandHandler("start", start))
    application.add_handler(CommandHandler("help", help_command))
    application.add_handler(CommandHandler("status", status))

    application.run_polling()


if __name__ == "__main__":
    main()

Run the program:

python bot.py

Open the bot and test:

/start
/help
/status

The handlers work, but the Telegram command menu may still be empty. The next step is to register the commands.

Method 1: Register Commands with BotFather

For a small bot with a fixed command list, BotFather provides a simple setup method.

Open @BotFather and send:

/mybots

Then select:

Your Bot
→ Edit Bot
→ Edit Commands

Submit one command per line:

start - Start the bot
help - Show available commands
status - Check the service status

After saving, reopen the bot or type / in the message field. Telegram should display the menu.

This approach is convenient when:

The command list rarely changes.
The bot has only one language.
Every chat uses the same commands.
Command registration does not need to be part of deployment.

For a larger project, registering commands from Python keeps the visible menu synchronized with the code.

Method 2: Register Commands from Python

Import BotCommand:

from telegram import BotCommand, Update

Create a startup function:

async def set_commands(application: Application) -> None:
    commands = [
        BotCommand("start", "Start the bot"),
        BotCommand("help", "Show available commands"),
        BotCommand("status", "Check the service status"),
    ]

    await application.bot.set_my_commands(commands)

Update the application builder:

application = (
    Application.builder()
    .token(token)
    .post_init(set_commands)
    .build()
)

The post_init callback runs after the application has been initialized and can access application.bot.

The relevant section now looks like this:

async def set_commands(application: Application) -> None:
    commands = [
        BotCommand("start", "Start the bot"),
        BotCommand("help", "Show available commands"),
        BotCommand("status", "Check the service status"),
    ]

    await application.bot.set_my_commands(commands)


def main() -> None:
    token = os.environ.get("TELEGRAM_BOT_TOKEN")

    if not token:
        raise RuntimeError(
            "The TELEGRAM_BOT_TOKEN environment variable is missing."
        )

    application = (
        Application.builder()
        .token(token)
        .post_init(set_commands)
        .build()
    )

    application.add_handler(CommandHandler("start", start))
    application.add_handler(CommandHandler("help", help_command))
    application.add_handler(CommandHandler("status", status))

    application.run_polling()

Restart the bot:

python bot.py

The command menu is now registered automatically whenever the application starts.

Telegram documents this operation in the official setMyCommands reference.

Command Naming Rules

A command name should be simple and predictable.

Good examples:

start
help
status
account
language
server_1

Avoid:

Start
show-status
my command
/settings!

Bot commands use lowercase English letters, digits, and underscores. Do not include the leading slash when creating a BotCommand.

Correct:

BotCommand("status", "Check service status")

Incorrect:

BotCommand("/status", "Check service status")

Descriptions should explain the result of using the command. Avoid vague descriptions such as “Click here” or “Do something.”

Create Different Menus for Private Chats and Groups

A bot may need one menu in private chats and another in groups.

Private commands might include:

/start
/help
/settings
/status

Group commands might include:

/help
/rules
/report
/status

Import the required scopes:

from telegram import (
    BotCommand,
    BotCommandScopeAllGroupChats,
    BotCommandScopeAllPrivateChats,
    Update,
)

Replace set_commands() with:

async def set_commands(application: Application) -> None:
    private_commands = [
        BotCommand("start", "Start the bot"),
        BotCommand("help", "Show available commands"),
        BotCommand("settings", "Open personal settings"),
        BotCommand("status", "Check service status"),
    ]

    group_commands = [
        BotCommand("help", "Show group commands"),
        BotCommand("rules", "Display the group rules"),
        BotCommand("report", "Report a message to moderators"),
        BotCommand("status", "Check bot status"),
    ]

    await application.bot.set_my_commands(
        private_commands,
        scope=BotCommandScopeAllPrivateChats(),
    )

    await application.bot.set_my_commands(
        group_commands,
        scope=BotCommandScopeAllGroupChats(),
    )

The visible menu now depends on the chat type.

However, the menu and the handlers remain separate. If /rules is displayed for groups, a handler must also be registered:

application.add_handler(
    CommandHandler("rules", rules)
)

Telegram supports several command scopes, including default commands, all private chats, all group chats, administrators, specific chats, and specific chat members. The selection rules are documented in the official BotCommandScope reference.

Add Group-Only Command Handlers

A command visible in a group menu should normally reject private-chat usage.

Import ChatType:

from telegram.constants import ChatType

Create a /rules handler:

async def rules(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
) -> None:
    if update.message is None:
        return

    chat = update.effective_chat

    if chat is None:
        return

    if chat.type == ChatType.PRIVATE:
        await update.message.reply_text(
            "The /rules command is available in groups only."
        )
        return

    await update.message.reply_text(
        "Group rules:\n\n"
        "1. Be respectful.\n"
        "2. Stay on topic.\n"
        "3. Do not post sensitive information."
    )

application.add_handler(CommandHandler("rules", rules))

Hiding a command from the private-chat menu improves the interface, but it does not enforce authorization. Users may still type a command manually, so the handler must validate the chat type and permissions.

Create Administrator-Only Commands

Some commands should only be visible to group administrators.

Import the administrator scope:

from telegram import BotCommandScopeAllChatAdministrators

admin_commands = [
    BotCommand("report", "Review reported messages"),
    BotCommand("cleanup", "Remove recent unwanted messages"),
]

await application.bot.set_my_commands(
    admin_commands,
    scope=BotCommandScopeAllChatAdministrators(),
)

The menu scope only controls visibility. It does not prove that the caller is authorized.

A sensitive handler must still check the member status:

async def is_group_admin(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
) -> bool:
    chat = update.effective_chat
    user = update.effective_user

    if chat is None or user is None:
        return False

    member = await context.bot.get_chat_member(
        chat_id=chat.id,
        user_id=user.id,
    )

    return member.status in {"administrator", "creator"}

Use the check inside an administrator command:

async def cleanup(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
) -> None:
    if update.message is None:
        return

    if not await is_group_admin(update, context):
        await update.message.reply_text(
            "You do not have permission to use this command."
        )
        return

    await update.message.reply_text(
        "Cleanup request accepted."
    )

Never rely on command visibility as an access-control mechanism.

Add Language-Specific Commands

Telegram can register different descriptions for different language codes.

For example:

english_commands = [
    BotCommand("start", "Start the bot"),
    BotCommand("help", "Show available commands"),
]

traditional_chinese_commands = [
    BotCommand("start", "開始使用機器人"),
    BotCommand("help", "查看可用指令"),
]

await application.bot.set_my_commands(
    english_commands
)

await application.bot.set_my_commands(
    traditional_chinese_commands,
    language_code="zh-hant",
)

A default command list should still exist for users whose language does not match a localized menu.

The language code affects menu descriptions, not the command handler itself. /help can inspect update.effective_user.language_code if the bot needs to respond in a different language.

Complete Working Example

import logging
import os

from telegram import (
    BotCommand,
    BotCommandScopeAllGroupChats,
    BotCommandScopeAllPrivateChats,
    Update,
)
from telegram.constants import ChatType
from telegram.ext import (
    Application,
    CommandHandler,
    ContextTypes,
)

logging.basicConfig(
    format=(
        "%(asctime)s - %(name)s - "
        "%(levelname)s - %(message)s"
    ),
    level=logging.INFO,
)

logger = logging.getLogger(__name__)


async def start(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
) -> None:
    if update.message is None:
        return

    user = update.effective_user
    name = user.first_name if user else "there"

    await update.message.reply_text(
        f"Hello, {name}! Use /help to view available commands."
    )


async def help_command(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
) -> None:
    if update.message is None:
        return

    await update.message.reply_text(
        "Available commands:\n\n"
        "/start - Start the bot\n"
        "/help - Show this message\n"
        "/status - Check service status"
    )


async def status(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
) -> None:
    if update.message is None:
        return

    await update.message.reply_text(
        "🟢 The service is operating normally."
    )


async def rules(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
) -> None:
    if update.message is None:
        return

    chat = update.effective_chat

    if chat is None or chat.type == ChatType.PRIVATE:
        await update.message.reply_text(
            "The /rules command is available in groups only."
        )
        return

    await update.message.reply_text(
        "Group rules:\n\n"
        "1. Be respectful.\n"
        "2. Stay on topic.\n"
        "3. Do not share sensitive information."
    )


async def set_commands(application: Application) -> None:
    private_commands = [
        BotCommand("start", "Start the bot"),
        BotCommand("help", "Show available commands"),
        BotCommand("status", "Check service status"),
    ]

    group_commands = [
        BotCommand("help", "Show group commands"),
        BotCommand("rules", "Display the group rules"),
        BotCommand("status", "Check bot status"),
    ]

    await application.bot.set_my_commands(
        private_commands,
        scope=BotCommandScopeAllPrivateChats(),
    )

    await application.bot.set_my_commands(
        group_commands,
        scope=BotCommandScopeAllGroupChats(),
    )


async def error_handler(
    update: object,
    context: ContextTypes.DEFAULT_TYPE,
) -> None:
    logger.error(
        "An exception occurred while processing an update.",
        exc_info=context.error,
    )


def main() -> None:
    token = os.environ.get("TELEGRAM_BOT_TOKEN")

    if not token:
        raise RuntimeError(
            "The TELEGRAM_BOT_TOKEN environment variable is missing."
        )

    application = (
        Application.builder()
        .token(token)
        .post_init(set_commands)
        .build()
    )

    application.add_handler(CommandHandler("start", start))
    application.add_handler(CommandHandler("help", help_command))
    application.add_handler(CommandHandler("status", status))
    application.add_handler(CommandHandler("rules", rules))
    application.add_error_handler(error_handler)

    application.run_polling()


if __name__ == "__main__":
    main()

Run:

python bot.py

Test the bot in both a private chat and a group. The displayed commands should differ according to the selected scope.

Common Problems

Commands Work but the Menu Is Empty

The handlers exist, but the command list has not been registered. Use BotFather or set_my_commands().

After registering commands, close and reopen the chat if the client does not refresh immediately.

A Command Appears but Does Nothing

The command was registered in the menu, but no matching handler exists.

For every visible command, confirm that the application contains:

application.add_handler(
    CommandHandler("command_name", handler_function)
)

Old Commands Still Appear

The application may be registering commands under a different scope. It is also possible that commands were previously set through BotFather or another deployment.

Inspect which scopes are being used, update them consistently, and restart the client if necessary.

Telegram also provides deleteMyCommands for removing a command list from a selected scope.

Group Commands Appear in Private Chats

A default command list may be overriding the intended design, or the private scope was not configured.

Administrator Commands Are Visible to the Wrong Users

Review the command scope, but also remember that visibility is not authorization. Every sensitive handler must verify the caller's current member status.

Commands Stop Updating After Code Changes

The startup callback may not be running, or the application may be exiting before set_my_commands() succeeds.

Add logging inside the startup function:

async def set_commands(application: Application) -> None:
    logger.info("Registering bot commands")
    # Register commands here.

Do not log the bot token.

Final Design Guidelines

A useful command menu should be:

Short enough to scan quickly
Consistent with implemented handlers
Different where private and group workflows differ
Localized when the bot serves multiple languages
Protected by server-side permission checks
Updated as part of deployment

Avoid registering every internal or debugging command. Public menus should contain only actions that ordinary users need.

The command menu improves discoverability, while handlers provide behavior and authorization. Both parts must be maintained together.

繁體中文摘要

Telegram Bot 的指令選單可以讓使用者在輸入 / 時看到 /start、/help 與 /status 等功能。指令可以透過 BotFather 手動設定，也可以使用 set_my_commands() 在 Python 程式啟動時自動註冊。

私人聊天、群組及管理員可以使用不同的 BotCommandScope。不過，選單只控制顯示內容，不代表使用者具有操作權限。管理功能仍需在處理函式中驗證聊天類型與管理員身分。

Disclosure: This tutorial was drafted with AI assistance and reviewed against the Telegram Bot API and python-telegram-bot documentation. Test all permission-sensitive commands with a development bot before production use.

How to Build a Telegram Bot Inline Keyboard with Python

Telegram Bot Engineering Note — Mon, 17 Aug 2026 17:01:40 +0000

Text commands are enough for a basic Telegram bot, but they become inconvenient as the number of features grows. An inline keyboard gives users a clearer interface by placing buttons directly below a message.

In this tutorial, we will build a small menu using Python and python-telegram-bot. The bot will display buttons, process callback queries, update the original message, and safely handle unknown actions.

What Is an Inline Keyboard?

An inline keyboard is a collection of buttons attached to a Telegram message. Unlike a reply keyboard, it does not replace the user's typing area.

Inline keyboards are useful for:

Navigation menus
Confirmation dialogs
Pagination
Language selection
Account settings
Order and service status checks
Links to websites or documentation
Group and channel administration

Telegram represents an inline keyboard with two main objects:

InlineKeyboardMarkup contains the complete button layout.
InlineKeyboardButton represents an individual button.

A keyboard is arranged as a list of rows. Each row contains one or more buttons.

[ Documentation ] [ Service Status ]
[ Open the Bot API Docs ]

A simplified API representation looks like this:

{
"inline_keyboard": [
[
{
"text": "Documentation",
"callback_data": "menu:docs"
},
{
"text": "Service Status",
"callback_data": "menu:status"
}
],
[
{
"text": "Open the Bot API Docs",
"url": "https://core.telegram.org/bots/api"
}
]
]
}

A button with callback_data sends a callback query to the bot. A button with a url opens the destination directly and does not trigger the same callback flow.

See Telegram's official InlineKeyboardMarkup documentation for the complete object definition.

Prerequisites

You will need:

Python 3.10 or newer
A Telegram account
A bot created through @botfather
The bot token stored securely
Basic familiarity with running Python from a terminal

If you still need the client, use this Telegram download guide to install it on desktop or mobile.

This tutorial uses the asynchronous python-telegram-bot interface.

Create the Project

Create a new directory:

mkdir telegram-inline-keyboard
cd telegram-inline-keyboard

Create a virtual environment:

python -m venv .venv

Activate it on macOS or Linux:

source .venv/bin/activate

Activate it in Windows PowerShell:

.venv\Scripts\Activate.ps1

Install or upgrade the library:

python -m pip install --upgrade python-telegram-bot

The current stable python-telegram-bot library uses an asynchronous API. Handler functions therefore use async def, and Telegram operations must be awaited.

Store the Bot Token Safely

Do not place a real token directly in source code.

On macOS or Linux:

export TELEGRAM_BOT_TOKEN='PASTE_YOUR_TOKEN_HERE'

In Windows PowerShell:

$env:TELEGRAM_BOT_TOKEN="PASTE_YOUR_TOKEN_HERE"

The environment variable exists only in the current terminal session. For production, use the secret-management feature provided by your hosting platform.

Never commit a .env file containing a token to a public repository. If a token is exposed, revoke it through BotFather and generate a new one.

Build the First Menu

Create a file named bot.py:

import os

from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
from telegram.ext import Application, CommandHandler, ContextTypes

def build_home_keyboard() -> InlineKeyboardMarkup:
keyboard = [
[
InlineKeyboardButton(
"📚 Documentation",
callback_data="menu:docs",
),
InlineKeyboardButton(
"🟢 Service Status",
callback_data="menu:status",
),
],
[
InlineKeyboardButton(
"🌐 Open the Bot API Docs",
url="https://core.telegram.org/bots/api",
)
],
]

return InlineKeyboardMarkup(keyboard)

async def start(
update: Update,
context: ContextTypes.DEFAULT_TYPE,
) -> None:
if update.message is None:
return

await update.message.reply_text(
    "Choose an option:",
    reply_markup=build_home_keyboard(),
)

def main() -> None:
token = os.environ.get("TELEGRAM_BOT_TOKEN")

if not token:
    raise RuntimeError(
        "The TELEGRAM_BOT_TOKEN environment variable is missing."
    )

application = Application.builder().token(token).build()
application.add_handler(CommandHandler("start", start))

application.run_polling()

if name == "main":
main()

Run the bot:

python bot.py

Open the bot in Telegram and send:

/start

You should see two callback buttons and one URL button. The URL button already works, but the callback buttons do not yet have a handler.

Understanding callback_data

The callback_data value is a short string associated with a button:

InlineKeyboardButton(
"Service Status",
callback_data="menu:status",
)

When a user presses this button, Telegram sends a CallbackQuery update containing:

menu:status

A useful convention is to organize callback values with prefixes:

menu:home
menu:docs
menu:status
settings:language:en
page:articles:2
order:confirm:5821

Telegram limits callback_data to a small payload, so it should contain an action identifier rather than a complete data object.

Do not include the following information in callback data:

Bot tokens
Passwords
API keys
Payment information
Email addresses
Private user data
Complete JSON documents
Authorization credentials

For database-backed actions, include a short record identifier and load the actual data on the server after validating the request.

Add a Callback Query Handler

Update the imports:

from telegram.ext import (
Application,
CallbackQueryHandler,
CommandHandler,
ContextTypes,
)

Add the following function below start():

async def handle_button(
update: Update,
context: ContextTypes.DEFAULT_TYPE,
) -> None:
query = update.callback_query

if query is None:
    return

action = query.data

if action == "menu:docs":
    await query.answer()

    keyboard = InlineKeyboardMarkup(
        [
            [
                InlineKeyboardButton(
                    "⬅️ Back",
                    callback_data="menu:home",
                )
            ]
        ]
    )

    await query.edit_message_text(
        text=(
            "📚 Documentation\n\n"
            "Use the official Bot API reference to review "
            "available methods, objects, and update types."
        ),
        reply_markup=keyboard,
    )

elif action == "menu:status":
    await query.answer("Status refreshed")

    keyboard = InlineKeyboardMarkup(
        [
            [
                InlineKeyboardButton(
                    "🔄 Refresh",
                    callback_data="menu:status",
                ),
                InlineKeyboardButton(
                    "⬅️ Back",
                    callback_data="menu:home",
                ),
            ]
        ]
    )

    await query.edit_message_text(
        text="🟢 The service is operating normally.",
        reply_markup=keyboard,
    )

elif action == "menu:home":
    await query.answer()

    await query.edit_message_text(
        text="Choose an option:",
        reply_markup=build_home_keyboard(),
    )

else:
    await query.answer(
        text="Unknown action",
        show_alert=True,
    )

application.add_handler(
CallbackQueryHandler(
handle_button,
pattern=r"^menu:",
)
)

The handler section should now look like this:

application.add_handler(CommandHandler("start", start))

application.add_handler(
CallbackQueryHandler(
handle_button,
pattern=r"^menu:",
)
)

The regular expression limits this handler to callback values beginning with menu:. Future features can use separate prefixes and handlers.

For example:

application.add_handler(
CallbackQueryHandler(
handle_settings,
pattern=r"^settings:",
)
)

This keeps a larger bot easier to maintain.

Why query.answer() Is Required

After a user presses an inline button, the Telegram client displays a loading indicator. The bot should answer the callback query even if no notification needs to be shown.

await query.answer()

Without this call, the loading indicator may continue spinning and make the interface appear broken.

To show a short notification:

await query.answer("Settings saved")

To display an alert dialog:

await query.answer(
text="You do not have permission to perform this action.",
show_alert=True,
)

Only answer each callback once. Decide whether the response should be silent, a short notification, or an alert.

Telegram explains this behavior in the official CallbackQuery documentation.

Complete Working Example

The following version includes logging, menu navigation, filtered callback handling, and a basic error handler:

import logging
import os

from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
from telegram.ext import (
Application,
CallbackQueryHandler,
CommandHandler,
ContextTypes,
)

logging.basicConfig(
format=(
"%(asctime)s - %(name)s - "
"%(levelname)s - %(message)s"
),
level=logging.INFO,
)

logger = logging.getLogger(name)

return InlineKeyboardMarkup(keyboard)

async def start(
update: Update,
context: ContextTypes.DEFAULT_TYPE,
) -> None:
if update.message is None:
return

await update.message.reply_text(
    "Choose an option:",
    reply_markup=build_home_keyboard(),
)

async def handle_button(
update: Update,
context: ContextTypes.DEFAULT_TYPE,
) -> None:
query = update.callback_query

if query is None:
    return

action = query.data

if action == "menu:docs":
    await query.answer()

    keyboard = InlineKeyboardMarkup(
        [
            [
                InlineKeyboardButton(
                    "⬅️ Back",
                    callback_data="menu:home",
                )
            ]
        ]
    )

    await query.edit_message_text(
        text=(
            "📚 Documentation\n\n"
            "Review the Telegram Bot API reference "
            "for available methods and objects."
        ),
        reply_markup=keyboard,
    )

elif action == "menu:status":
    await query.answer("Status refreshed")

    keyboard = InlineKeyboardMarkup(
        [
            [
                InlineKeyboardButton(
                    "🔄 Refresh",
                    callback_data="menu:status",
                ),
                InlineKeyboardButton(
                    "⬅️ Back",
                    callback_data="menu:home",
                ),
            ]
        ]
    )

    await query.edit_message_text(
        text="🟢 The service is operating normally.",
        reply_markup=keyboard,
    )

elif action == "menu:home":
    await query.answer()

    await query.edit_message_text(
        text="Choose an option:",
        reply_markup=build_home_keyboard(),
    )

else:
    await query.answer(
        text="Unknown action",
        show_alert=True,
    )

async def error_handler(
update: object,
context: ContextTypes.DEFAULT_TYPE,
) -> None:
logger.error(
"An exception occurred while processing an update.",
exc_info=context.error,
)

def main() -> None:
token = os.environ.get("TELEGRAM_BOT_TOKEN")

if not token:
    raise RuntimeError(
        "The TELEGRAM_BOT_TOKEN environment variable is missing."
    )

application = Application.builder().token(token).build()

application.add_handler(CommandHandler("start", start))
application.add_handler(
    CallbackQueryHandler(
        handle_button,
        pattern=r"^menu:",
    )
)
application.add_error_handler(error_handler)

application.run_polling()

if name == "main":
main()

Restart the program after saving:

python bot.py

Send /start again and test every button.

The python-telegram-bot project also provides an official inline keyboard example that is useful when comparing implementation patterns.

URL Buttons vs. Callback Buttons

A URL button opens a destination:

InlineKeyboardButton(
"Open Documentation",
url="https://core.telegram.org/bots/api",
)

A callback button sends data to the bot:

InlineKeyboardButton(
"Check Status",
callback_data="menu:status",
)

Use a URL button when the only goal is navigation. Use a callback button when the server needs to validate an action, query a database, modify a message, or change the menu.

Do not use callback data as a substitute for server-side authorization. A user interface is not a security boundary.

Editing a Message vs. Sending a New One

A menu usually works best when it edits the existing message:

await query.edit_message_text(
text="Updated menu content"
)

This prevents a long trail of nearly identical menu messages.

For permanent results, notifications, receipts, or audit information, send a new message instead:

await query.message.reply_text(
"Your request has been completed."
)

Choose based on whether the user needs to retain the previous result.

Common Problems
The Button Keeps Loading

Confirm that every callback path calls one of the following:

await query.answer()
await query.answer("Completed")
await query.answer(
"Permission denied",
show_alert=True,
)

Unknown and error paths also need a callback response.

Nothing Happens After a Click

Check that:

CallbackQueryHandler is registered.
The callback value matches the handler pattern.
The bot process is still running.
The token belongs to the correct bot.
Another process is not consuming updates.
A webhook is not conflicting with polling.
The terminal does not contain an exception.
Message Is Not Modified

Telegram returns this error when the new text and keyboard are identical to the current message.

A refresh button should either produce changed content or handle this case without treating it as a fatal error.

A User Clicks an Old Button

Inline buttons can remain visible in chat history. A user may press one after the referenced database record has expired or changed.

Always verify:

The user is still authorized.
The record still exists.
The action is still valid.
The operation has not already been completed.
The callback belongs to the expected workflow.

Return a clear alert if the action is no longer available.

Duplicate Clicks Create Duplicate Operations

For sensitive actions such as payments, deletions, or order creation, add server-side protection:

Idempotency keys
Transaction checks
Permission validation
Current-state validation
Rate limiting
Audit logs
Confirmation steps

Disabling or replacing a button improves the interface, but it does not replace backend safeguards.

A Better Project Structure

A single file is acceptable for this tutorial. A larger bot should separate menu creation, callback routing, and business logic.

telegram-inline-keyboard/
├── bot.py
├── handlers/
│ ├── commands.py
│ └── callbacks.py
├── keyboards/
│ └── main_menu.py
├── services/
│ └── status_service.py
└── requirements.txt

This structure makes it easier to test functions and add new menus without turning bot.py into a large collection of unrelated conditions.

Where to Go Next

Once the basic menu works, useful extensions include:

Paginated article lists
Language settings
Confirmation dialogs
Database-backed menus
Role-based administrator buttons
Image and document actions
Webhook deployment
Persistent user preferences
Rate limiting and audit logs

The core workflow remains the same:

Create an InlineKeyboardButton
→ assign callback_data
→ register CallbackQueryHandler
→ validate query.data
→ call query.answer()
→ update or send a message

Once this pattern is clear, a command-only Telegram bot can be turned into a practical interactive application.

繁體中文摘要

Inline Keyboard 可以在 Telegram Bot 訊息下方加入互動按鈕。使用者點擊含有 callback_data 的按鈕後，程式會收到 Callback Query。處理函式必須驗證資料並執行 query.answer()，否則按鈕可能持續顯示載入狀態。

一般選單適合使用 edit_message_text() 更新原訊息；需要保留的操作結果則可以另外傳送新訊息。涉及付款、刪除或管理權限時，仍需在伺服器端進行身分與狀態驗證，不能只依賴按鈕介面。

Disclosure: This tutorial was drafted with AI assistance and reviewed against the Telegram Bot API and python-telegram-bot documentation. Test the code in a development bot before using it in production.