DEV Community: Telegram Bot Engineering Note

Telegram频道适合发布哪些内容？

Telegram Bot Engineering Note — Fri, 28 Aug 2026 05:46:18 +0000

Telegram频道适合持续发布面向订阅者的信息，例如行业资讯、课程通知、活动安排、产品动态、作品内容和兴趣主题整理。频道通常由创建者或管理员发布内容，订阅者以阅读为主，因此比开放群组更适合集中传递重要消息。发布前应先确定频道主题与更新频率，让订阅者清楚自己可以获得哪些内容。

发布行业资讯与知识整理

科技、教育、设计、游戏、语言学习和职场等领域，都可以通过频道持续整理资讯。运营者可发布新闻摘要、工具介绍、经验分享、书籍推荐和实用链接，帮助订阅者更快找到相关信息。

资讯内容应注明来源和发布时间，避免把未经核实的传闻写成事实。转载文章、图片或视频时，也应注意版权范围。相比单纯复制大量内容，加入简短的背景说明、适用人群和注意事项，更容易让读者理解信息价值。

发布课程与学习通知

教师、培训机构或学习社群可以用频道发布课程时间、作业要求、资料更新和直播提醒。频道可作为统一通知入口，减少信息分散在多个聊天群里后被遗漏的情况。

发布学习资料时，建议按课程、日期或主题建立固定格式。例如先写课程名称和适用对象，再放文件或链接，并说明截止时间。重要通知可以置顶，方便新加入的订阅者快速找到。涉及学生资料时，不应公开姓名、成绩和联系方式。

发布活动与社群公告

线上讲座、线下聚会、游戏活动和兴趣社群都可以通过频道发布报名时间、地点、参与规则和后续提醒。对成员较多的社群来说，频道比群组更适合发送统一公告，能够避免重要信息被日常聊天淹没。

活动内容发生变化时，应及时发布更新，并在原通知中注明调整原因。若需要收集报名信息，可使用可信的表单工具，并明确说明信息用途。不要要求订阅者在公开频道中提交身份证号、付款密码或其他敏感资料。

分享作品与品牌动态

创作者、开发者、小型团队和个人品牌可以在频道发布新作品、更新日志、案例展示、使用技巧和幕后内容。固定的栏目形式，例如每周精选、常见问题、更新说明或用户反馈整理，有助于读者形成稳定预期。

品牌宣传内容应避免只发布广告。除了介绍产品，也可以提供解决问题的方法、使用场景和公开资料，让订阅者获得实际价值。对于合作推广或付费内容，应清楚标注，避免让读者误以为是普通推荐。

发布文件与实用资源

频道支持发布图片、视频、文档和链接，适合整理模板、清单、公开资料和常用工具。运营者可以为每份资源补充用途、版本、更新时间和使用限制，减少订阅者下载后不知道如何使用的问题。

涉及软件安装包或外部链接时，应优先提供可信来源，并提醒订阅者核对文件名称、发布者和权限请求。不要在频道中传播来历不明的程序、破解工具、盗版资源或可能损害设备安全的文件。

用频道配合讨论群组

频道适合单向发布，群组更适合成员互动。若运营者既需要稳定公告，又希望收集读者意见，可以建立频道发布重要内容，再设置讨论群组处理提问和交流。这样能让公告与聊天分开，管理也更清楚。

新用户可通过Telegram查看适用于Windows、macOS、Android及iOS设备的客户端版本，并获取频道、群组与中文设置说明。创建频道后，建议先确定主题、发布节奏和内容规范，再根据订阅者反馈逐步调整。

总体来看，Telegram频道适合发布有明确主题、可持续更新且对订阅者有帮助的内容。无论是资讯、课程、公告、作品还是资源，保持信息真实、结构清楚和更新稳定，才能让频道长期获得读者关注。

Telegram是否支持创建大型群组？

Telegram Bot Engineering Note — Fri, 28 Aug 2026 05:12:46 +0000

Telegram支持创建大型群组，适合用于兴趣社群、学习讨论、远程协作和活动通知等场景。群主和管理员可以设置成员权限、邀请方式、发言规则及内容管理范围，让人数较多的交流保持相对有序。建立群组前，建议先明确主题、成员来源和管理方式，避免群组人数增加后出现广告、骚扰或无关内容过多的问题。

大型群组适合哪些使用场景

大型群组适合需要多人持续交流的场景，例如课程学习、行业讨论、游戏社群、同城活动和项目协作。成员可以发送文字、图片、文件、链接和表情，也能围绕某条消息进行回复，使讨论内容更容易追溯。

如果群组主要用于发布通知，而不是开放讨论，可考虑限制普通成员的发言权限。这样能减少重复提问和无关聊天，让重要信息更容易被看到。需要成员互动时，则可根据主题设置不同的讨论区域或子群组。

建群前先规划群组规则

人数较多的群组若没有清晰规则，很容易被广告、刷屏和争吵影响。群主可在群公告或置顶消息中说明群组主题、允许发布的内容、禁止行为和违规处理方式，并在新成员加入后提醒阅读。

规则应尽量具体，例如是否允许推广链接、是否允许发布重复内容、遇到问题应如何提问，以及管理员如何处理违规消息。规则不是为了限制正常交流，而是帮助成员理解边界，降低管理人员反复解释的成本。

管理员权限需要合理分配

群主可以根据实际需要添加管理员，并分别设置管理权限。负责审核新成员的人不一定需要删除消息权限，负责整理公告的人也不一定需要邀请成员权限。按职责分配权限，能减少误操作和账号被盗后带来的影响。

管理员账号应开启两步验证，并避免把验证码、密码或恢复邮箱信息分享给他人。成员较多时，可定期检查管理员列表，及时移除已经不再参与管理的账号。对来源不明的管理机器人，也应谨慎授权。

控制成员加入方式

大型群组可以通过邀请链接、公开搜索或其他方式吸引成员，但不同加入方式带来的管理压力不同。公开群组更容易被陌生用户找到，也更容易出现广告和垃圾账号；邀请制群组则适合成员来源明确的学习班、团队或朋友圈。

管理员可以按需要调整邀请权限，必要时要求新成员经过审核后再加入。活动结束后，如果邀请链接被大量转发，也应及时更换或关闭旧链接，避免无关人员持续进入群组。

使用工具辅助维护秩序

成员不断增加后，仅靠人工查看每一条消息会比较困难。管理员可使用平台提供的权限设置、慢速模式、置顶消息和举报功能维护秩序。对于重复广告、恶意链接和明显骚扰行为，应尽快处理，避免其他成员模仿。

机器人可以协助完成欢迎提示、关键词过滤和基础问答，但不应完全代替人工管理。设置机器人前，应了解其权限范围和数据处理方式，避免让机器人读取与群组目标无关的内容。

区分群组与频道的用途

群组主要用于成员之间的互动和讨论，频道更适合由管理员向大量订阅者单向发布内容。若社群既要发布重要公告，又要收集成员反馈，可以将频道和讨论群组配合使用，让不同内容进入更合适的位置。

新用户可通过Telegram查看适用于Windows、macOS、Android及iOS设备的客户端版本，并了解群组、频道与基础设置说明。创建大型群组后，应先从清晰的主题和适度的成员规模开始，再逐步完善规则与管理权限。

总体来说，Telegram适合创建和管理大型群组，但群组规模越大，越需要明确规则、分配管理员权限并控制加入方式。只有在交流目标和管理机制都清楚的情况下，群组才能长期保持有价值的讨论环境。

How to Handle Telegram Bot Rate Limits with Python

Telegram Bot Engineering Note — Wed, 26 Aug 2026 02:51:36 +0000

A Telegram bot may work correctly during development but begin returning errors when it sends notifications to many users. One of the most common responses is 429 Too Many Requests, which means the bot has exceeded a flood-control limit.

The correct solution is not to resend the same request continuously. A reliable bot should queue outgoing messages, control its sending speed, read Telegram’s retry_after value, and retry failed requests after the required delay.

This tutorial demonstrates how to build a basic rate-limited Telegram message sender with Python.

Understanding Telegram Bot Rate Limits

Telegram applies different restrictions depending on the destination and sending pattern. According to the official Telegram Bots FAQ, developers should generally avoid sending more than one message per second to a single chat. Group messages and bulk broadcasts have separate limits.

When a bot exceeds a limit, the API may return a response similar to this:

{
  "ok": false,
  "error_code": 429,
  "description": "Too Many Requests: retry after 3",
  "parameters": {
    "retry_after": 3
  }
}

The retry_after field specifies how many seconds the program should wait before repeating the request.

Preparing the Python Project

Create a project directory and install the requests package:

mkdir telegram-rate-limiter
cd telegram-rate-limiter

python -m venv .venv
source .venv/bin/activate
pip install requests

Windows PowerShell users can activate the environment with:

.venv\Scripts\Activate.ps1

Create a bot through BotFather and store its Token in an environment variable. Never publish a bot Token in an article, screenshot or public repository.

Linux and macOS users can run:

export TELEGRAM_BOT_TOKEN="YOUR_BOT_TOKEN"

Windows PowerShell users can run:

$env:TELEGRAM_BOT_TOKEN="YOUR_BOT_TOKEN"

For local testing, install a mobile client or review the available desktop versions through this Telegram download page.

Creating the Telegram API Client

Create a file named sender.py:

import os
import requests

TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]
API_URL = f"https://api.telegram.org/bot{TOKEN}"


def call_send_message(chat_id: int, text: str):
    response = requests.post(
        f"{API_URL}/sendMessage",
        json={
            "chat_id": chat_id,
            "text": text
        },
        timeout=20
    )

    try:
        data = response.json()
    except ValueError:
        data = {
            "ok": False,
            "description": response.text
        }

    return response.status_code, data

This function returns the HTTP status code and Telegram’s JSON response. The program can therefore distinguish rate limits from network errors and invalid requests.

Adding an Outgoing Message Queue

A queue separates message creation from delivery. Other parts of the application can add messages immediately, while a worker sends them at a controlled speed.

Add the following code:

from dataclasses import dataclass
from queue import Queue


@dataclass
class MessageJob:
    chat_id: int
    text: str
    attempts: int = 0


message_queue = Queue()

A new message can now be scheduled without sending it immediately:

message_queue.put(
    MessageJob(
        chat_id=123456789,
        text="Your report is ready."
    )
)

The queue preserves the order of the jobs and allows the sending process to operate independently.

Handling HTTP 429 Responses

Import time and create a function that processes each queued job:

import time


def process_job(job: MessageJob):
    status, data = call_send_message(
        job.chat_id,
        job.text
    )

    if status == 200 and data.get("ok"):
        print(f"Sent message to {job.chat_id}")
        return

    if status == 429:
        parameters = data.get("parameters", {})
        wait_time = int(
            parameters.get("retry_after", 1)
        )

        print(
            f"Rate limited for {wait_time} seconds. "
            f"Chat: {job.chat_id}"
        )

        time.sleep(wait_time)
        message_queue.put(job)
        return

    raise RuntimeError(
        f"Telegram API error: {status} {data}"
    )

When Telegram returns HTTP 429, the function reads retry_after, waits for the specified period and returns the job to the queue. This is safer than retrying immediately or using the same arbitrary delay for every error.

Creating the Background Worker

The queue needs a worker that continuously processes pending jobs:

import threading

GLOBAL_INTERVAL = 0.05


def run_worker():
    while True:
        job = message_queue.get()

        try:
            process_job(job)

        except requests.RequestException as error:
            print(f"Network error: {error}")

            if job.attempts < 3:
                job.attempts += 1
                time.sleep(2 ** job.attempts)
                message_queue.put(job)

        except RuntimeError as error:
            print(error)

        finally:
            message_queue.task_done()
            time.sleep(GLOBAL_INTERVAL)


worker = threading.Thread(
    target=run_worker,
    daemon=True
)

worker.start()

The worker uses exponential backoff for temporary network errors. The first retry waits two seconds, the next waits four seconds, and the final retry waits eight seconds.

Preventing Bursts to the Same Chat

A bot may send messages to different users successfully while still exceeding the limit for one specific conversation. Store the latest delivery time for every chat:

last_sent_at = {}
PER_CHAT_INTERVAL = 1.0


def wait_for_chat(chat_id: int):
    previous = last_sent_at.get(chat_id, 0)
    elapsed = time.monotonic() - previous
    remaining = PER_CHAT_INTERVAL - elapsed

    if remaining > 0:
        time.sleep(remaining)

    last_sent_at[chat_id] = time.monotonic()

Call this function before making the request:

def process_job(job: MessageJob):
    wait_for_chat(job.chat_id)

    status, data = call_send_message(
        job.chat_id,
        job.text
    )

    if status == 200 and data.get("ok"):
        print(f"Sent message to {job.chat_id}")
        return

    if status == 429:
        wait_time = int(
            data.get("parameters", {})
                .get("retry_after", 1)
        )

        time.sleep(wait_time)
        message_queue.put(job)
        return

    raise RuntimeError(
        f"Telegram API error: {status} {data}"
    )

For an application with multiple worker processes, per-chat timestamps should be stored in a shared system such as Redis.

Testing the Queue

Add several test jobs at the bottom of the file:

if __name__ == "__main__":
    target_chat_id = 123456789

    for number in range(1, 6):
        message_queue.put(
            MessageJob(
                chat_id=target_chat_id,
                text=f"Queued message number {number}"
            )
        )

    message_queue.join()
    print("All jobs completed")

Replace target_chat_id with your own chat ID, start a conversation with the bot and run:

python sender.py

The messages should be delivered in order instead of being sent as one uncontrolled burst.

Recommended Production Improvements

This example stores jobs in memory. If the Python process stops, pending messages will be lost. A production application should use a persistent queue such as Redis, RabbitMQ, Amazon SQS or a database-backed job system.

It should also include:

Structured logging without exposing the bot Token
A maximum retry count for permanent failures
Separate handling for blocked users and invalid chat IDs
Graceful shutdown logic
Monitoring for queue size and delivery latency
Message identifiers to prevent duplicate delivery

The Telegram Bot API documentation should remain the primary source for current methods, parameters and error responses.

Conclusion

Handling Telegram rate limits requires more than adding a delay to a loop. A stable bot needs an outgoing queue, per-chat pacing, network-error retries and explicit handling of HTTP 429 responses.

Once these controls are in place, the same architecture can support monitoring alerts, order updates, scheduled notifications and larger subscriber lists without repeatedly failing during traffic spikes.

Telegram中文语言包与汉化设置攻略

Telegram Bot Engineering Note — Sat, 22 Aug 2026 10:26:24 +0000

Telegram默认界面可能显示英文，但用户不需要重新安装所谓的“汉化版”，通过应用内的语言选项或Telegram语言包即可切换为简体中文、繁体中文、正体中文（台湾）或繁体中文（香港）。整个过程不会删除聊天记录，也不会影响已经加入的群组与频道。

安装适合设备的Telegram

开始设置前，应先确认手机或电脑已经安装Telegram客户端。用户可以通过Telegram电脑版查看Windows、macOS、Android及iOS版本，并按照设备类型完成安装。

建议尽量使用来源明确的客户端，不要随意安装经过修改的安装包。第三方修改版可能更新不及时，也可能存在账号与隐私风险。

在手机上切换中文

Android和iPhone用户可以打开Telegram，依次进入：

Settings → Language

进入语言列表后，选择简体中文、繁体中文或其他需要的语言。如果列表中已经提供相应选项，点击后界面会立即切换，一般不需要退出账号。

不同版本的菜单名称可能略有差异。如果暂时找不到中文，可以先更新Telegram，再重新打开语言设置页面。

在电脑上设置中文界面

Telegram Desktop用户可以点击左上角菜单，进入：

Settings → Language

选择中文后，菜单、按钮和系统提示会自动切换。如果部分内容仍然显示英文，可以关闭Telegram并重新启动，或者先切换到英文，再重新选择中文。

语言设置只会改变操作界面，不会自动翻译聊天内容。群组消息、频道文章和联系人发送的文字仍会保持原来的语言。

使用Telegram中文语言包

除了应用内置语言，Telegram还设有官方翻译平台。用户可以根据习惯选择不同版本：

简体中文语言包
繁体中文语言包
正体中文（台湾）语言包
繁体中文（香港）语言包

打开对应页面后，按照提示在Telegram中应用语言即可。语言包主要修改应用界面的文字，不会读取聊天内容，也不会改变账号资料。

中文设置没有生效怎么办

如果应用语言包后仍有部分英文，可以检查Telegram是否为最新版本，并重新启动应用。电脑端和手机端可能需要分别设置，修改手机语言不一定会同步改变电脑端界面。

部分语言包仍处于持续翻译和更新状态，因此个别新功能可能暂时保留英文。遇到翻译不完整时，可以等待语言包更新，或暂时改用另一个完成度较高的中文版本。

使用中文语言包要注意什么

语言包本身只是界面翻译，不会提供额外功能，也不能解除账号限制。对于来源不明的语言包链接，应先核对域名，优先选择Telegram官方翻译平台提供的版本。

完成设置后，Telegram的聊天、频道、群组、文件传输和通话功能都不会受到影响。用户也可以随时返回Language页面，重新切换为英文或其他语言。对于第一次使用Telegram的人来说，先完成中文界面设置，再调整隐私、通知和储存空间选项，会更容易熟悉各项功能。

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.