Telegram Bot API 提供了完整的机器人开发能力，支持消息处理、命令交互、Webhook 回调、内联按钮等功能。对于开发者来说，它是一套设计完善且易于上手的 Bot 开发接口。

本文将使用 Python 从零开始创建一个 Telegram Bot，并介绍消息处理机制以及 Long Polling 和 Webhook 两种接入方式的使用场景与区别。

---

一、创建一个 Telegram Bot

Telegram 官方提供了 Bot 管理机器人 @BotFather，用于创建和管理自己的 Bot。

创建步骤如下：

1. 向 BotFather 发送 /newbot
2. 设置机器人的显示名称（Name）
3. 设置机器人的用户名（Username，必须以 bot 结尾）
4. 获取 Bot Token

例如：

• Name：My Demo Bot
• Username：my_demo_bot

BotFather 会返回一个 Bot Token，例如：

<YOUR_BOT_TOKEN>

⚠️ Token 相当于机器人的身份凭证，请不要提交到 GitHub 仓库，也不要暴露在前端代码中。建议通过环境变量或配置文件进行管理。

---

二、使用 python-telegram-bot 编写第一个 Echo Bot

Python 社区中比较常用的 Telegram Bot SDK 是 python-telegram-bot。

安装：

pip install python-telegram-bot

创建一个最简单的 Echo Bot（收到什么消息就回复什么消息）：

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

TOKEN = "<YOUR_BOT_TOKEN>"


async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text(
        f"你发送的内容是：{update.message.text}"
    )


app = ApplicationBuilder().token(TOKEN).build()

app.add_handler(
    MessageHandler(
        filters.TEXT & ~filters.COMMAND,
        echo,
    )
)

app.run_polling()

运行程序之后，在 Telegram 中向机器人发送任意文本消息，即可收到回复。

---

三、处理命令与用户上下文

实际开发中，机器人通常会提供一些基础命令，例如：

/start
/help
/menu

可以通过 CommandHandler 注册命令处理函数：

from telegram.ext import CommandHandler


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text(
        "你好，我是你的第一个 Telegram Bot！\n"
        "发送 /help 查看帮助信息。"
    )


async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text(
        "/start - 初始化机器人\n"
        "/help - 查看帮助信息"
    )


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

app.add_handler(
    CommandHandler("help", help_command)
)

使用 user_data 保存用户状态

如果需要实现多轮对话，可以使用 context.user_data 保存用户上下文信息。

示例：

async def ask(update, context):
    context.user_data["step"] = 1

    await update.message.reply_text(
        "请输入你的名字："
    )


async def echo(update, context):
    if context.user_data.get("step") == 1:
        name = update.message.text

        await update.message.reply_text(
            f"你好，{name}！"
        )

        context.user_data.clear()

user_data 是按用户隔离的数据结构，非常适合保存对话状态。

---

四、Long Polling 与 Webhook 的区别

Telegram Bot 提供两种消息接收方式：

接入方式	特点	推荐场景
Long Polling	配置简单，无需公网地址	本地开发与调试
Webhook	延迟更低，适合长期运行	云服务器部署

Long Polling

Long Polling 的工作方式可以简单理解为：

Bot
↓

不断向 Telegram 请求新消息

↓

有消息则返回

↓

继续请求下一次消息

优点：

• 无需公网服务器
• 本地即可调试
• 配置简单

使用方式：

app.run_polling()

适用于：

• 学习 Bot API
• 本地开发
• 快速验证功能

---

Webhook

Webhook 的工作方式为：

Telegram Server
↓

收到用户消息

↓

主动推送到你的 HTTPS 地址

↓

Bot 处理消息

适用于：

• 云服务器部署
• 长期运行
• 对实时性有要求的场景

示例：

await app.bot.set_webhook(
    url="https://example.com/telegram/webhook"
)


app.run_webhook(
    listen="0.0.0.0",
    port=8443,
    webhook_url="https://example.com/telegram/webhook",
)

注意：Webhook 地址必须使用 HTTPS，并且需要有效的 SSL 证书。

如果只是学习 Bot API 或本地调试，建议优先使用 Long Polling；部署到生产环境时，推荐使用 Webhook。

---

五、使用 Inline Keyboard 创建交互按钮

Telegram Bot 支持丰富的消息交互能力，其中最常见的就是 Inline Keyboard（内联按钮）。

示例：

from telegram import (
    InlineKeyboardButton,
    InlineKeyboardMarkup,
)


async def menu(update, context):

    keyboard = [
        [
            InlineKeyboardButton(
                "Bot API 文档",
                url="https://core.telegram.org/bots/api"
            )
        ],
        [
            InlineKeyboardButton(
                "选项 A",
                callback_data="a"
            ),
            InlineKeyboardButton(
                "选项 B",
                callback_data="b"
            )
        ]
    ]

    await update.message.reply_text(
        "请选择一个操作：",
        reply_markup=InlineKeyboardMarkup(keyboard),
    )

用户点击按钮之后，可以通过 CallbackQueryHandler 获取回调数据：

from telegram.ext import CallbackQueryHandler


async def button(update, context):

    query = update.callback_query

    await query.answer()

    await query.edit_message_text(
        f"你点击的是：{query.data}"
    )

其中：

callback_data

用于标识业务逻辑，最大支持 64 字节的数据，非常适合实现菜单、状态机以及多轮交互功能。

---

六、部署与常见问题

1、消息限速

Telegram Bot 存在消息发送速率限制。

如果需要进行批量消息发送，建议：

• 控制发送频率
• 使用异步任务队列
• 合理处理 429 错误响应

---

2、用户状态持久化

默认情况下：

context.user_data

仅保存在内存中。

如果程序重启，用户状态会丢失。

开发阶段可以使用：

PicklePersistence

生产环境建议：

• Redis
• MySQL
• PostgreSQL
• MongoDB

进行用户状态持久化管理。

---

3、异常处理

建议为 Bot 添加统一的异常处理逻辑：

async def error_handler(
    update,
    context,
):
    print(
        f"发生异常：{context.error}"
    )


app.add_error_handler(
    error_handler
)

这样能够避免单个异常影响消息处理流程。

---

小结

一个基础的 Telegram Bot 开发流程可以概括为：

创建 Bot
↓

获取 Token
↓

编写消息处理逻辑
↓

选择 Long Polling 或 Webhook

↓

部署运行

通过 Telegram Bot API，开发者可以实现：

• 消息收发
• 命令处理
• Webhook 回调
• 内联按钮交互
• 富媒体消息发送
• 群组与频道消息处理

掌握这些基础能力之后，还可以进一步扩展定时任务、群组管理、消息统计以及其他 Bot API 提供的高级功能。

---

参考资料

• Telegram Bot API 官方文档
• python-telegram-bot 官方项目文档