Telegram Bot API 提供了完整的机器人开发能力支持消息处理、命令交互、Webhook 回调、内联按钮等功能。对于开发者来说它是一套设计完善且易于上手的 Bot 开发接口。本文将使用 Python 从零开始创建一个 Telegram Bot并介绍消息处理机制以及 Long Polling 和 Webhook 两种接入方式的使用场景与区别。一、创建一个 Telegram BotTelegram 官方提供了 Bot 管理机器人BotFather用于创建和管理自己的 Bot。创建步骤如下向 BotFather 发送/newbot设置机器人的显示名称Name设置机器人的用户名Username必须以bot结尾获取 Bot Token例如NameMy Demo BotUsernamemy_demo_botBotFather 会返回一个 Bot Token例如YOUR_BOT_TOKEN⚠️ Token 相当于机器人的身份凭证请不要提交到 GitHub 仓库也不要暴露在前端代码中。建议通过环境变量或配置文件进行管理。二、使用 python-telegram-bot 编写第一个 Echo BotPython 社区中比较常用的 Telegram Bot SDK 是python-telegram-bot。安装pipinstallpython-telegram-bot创建一个最简单的 Echo Bot收到什么消息就回复什么消息fromtelegramimportUpdatefromtelegram.extimport(ApplicationBuilder,ContextTypes,MessageHandler,filters,)TOKENYOUR_BOT_TOKENasyncdefecho(update:Update,context:ContextTypes.DEFAULT_TYPE):awaitupdate.message.reply_text(f你发送的内容是{update.message.text})appApplicationBuilder().token(TOKEN).build()app.add_handler(MessageHandler(filters.TEXT~filters.COMMAND,echo,))app.run_polling()运行程序之后在 Telegram 中向机器人发送任意文本消息即可收到回复。三、处理命令与用户上下文实际开发中机器人通常会提供一些基础命令例如/start /help /menu可以通过CommandHandler注册命令处理函数fromtelegram.extimportCommandHandlerasyncdefstart(update:Update,context:ContextTypes.DEFAULT_TYPE):awaitupdate.message.reply_text(你好我是你的第一个 Telegram Bot\n发送 /help 查看帮助信息。)asyncdefhelp_command(update:Update,context:ContextTypes.DEFAULT_TYPE):awaitupdate.message.reply_text(/start - 初始化机器人\n/help - 查看帮助信息)app.add_handler(CommandHandler(start,start))app.add_handler(CommandHandler(help,help_command))使用 user_data 保存用户状态如果需要实现多轮对话可以使用context.user_data保存用户上下文信息。示例asyncdefask(update,context):context.user_data[step]1awaitupdate.message.reply_text(请输入你的名字)asyncdefecho(update,context):ifcontext.user_data.get(step)1:nameupdate.message.textawaitupdate.message.reply_text(f你好{name})context.user_data.clear()user_data是按用户隔离的数据结构非常适合保存对话状态。四、Long Polling 与 Webhook 的区别Telegram Bot 提供两种消息接收方式接入方式特点推荐场景Long Polling配置简单无需公网地址本地开发与调试Webhook延迟更低适合长期运行云服务器部署Long PollingLong Polling 的工作方式可以简单理解为Bot ↓ 不断向 Telegram 请求新消息 ↓ 有消息则返回 ↓ 继续请求下一次消息优点无需公网服务器本地即可调试配置简单使用方式app.run_polling()适用于学习 Bot API本地开发快速验证功能WebhookWebhook 的工作方式为Telegram Server ↓ 收到用户消息 ↓ 主动推送到你的 HTTPS 地址 ↓ Bot 处理消息适用于云服务器部署长期运行对实时性有要求的场景示例awaitapp.bot.set_webhook(urlhttps://example.com/telegram/webhook)app.run_webhook(listen0.0.0.0,port8443,webhook_urlhttps://example.com/telegram/webhook,)注意Webhook 地址必须使用 HTTPS并且需要有效的 SSL 证书。如果只是学习 Bot API 或本地调试建议优先使用 Long Polling部署到生产环境时推荐使用 Webhook。五、使用 Inline Keyboard 创建交互按钮Telegram Bot 支持丰富的消息交互能力其中最常见的就是 Inline Keyboard内联按钮。示例fromtelegramimport(InlineKeyboardButton,InlineKeyboardMarkup,)asyncdefmenu(update,context):keyboard[[InlineKeyboardButton(Bot API 文档,urlhttps://core.telegram.org/bots/api)],[InlineKeyboardButton(选项 A,callback_dataa),InlineKeyboardButton(选项 B,callback_datab)]]awaitupdate.message.reply_text(请选择一个操作,reply_markupInlineKeyboardMarkup(keyboard),)用户点击按钮之后可以通过CallbackQueryHandler获取回调数据fromtelegram.extimportCallbackQueryHandlerasyncdefbutton(update,context):queryupdate.callback_queryawaitquery.answer()awaitquery.edit_message_text(f你点击的是{query.data})其中callback_data用于标识业务逻辑最大支持 64 字节的数据非常适合实现菜单、状态机以及多轮交互功能。六、部署与常见问题1、消息限速Telegram Bot 存在消息发送速率限制。如果需要进行批量消息发送建议控制发送频率使用异步任务队列合理处理 429 错误响应2、用户状态持久化默认情况下context.user_data仅保存在内存中。如果程序重启用户状态会丢失。开发阶段可以使用PicklePersistence生产环境建议RedisMySQLPostgreSQLMongoDB进行用户状态持久化管理。3、异常处理建议为 Bot 添加统一的异常处理逻辑asyncdeferror_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 官方项目文档
