Telegram机器人如何设置指令菜单并获取用户点击参数？

功能定位：指令菜单到底解决什么问题

在 Telegram 机器人开发语境里，“指令菜单”指用户输入斜杠/后自动弹出���命令列表，也可通过侧边“菜单”按钮一键展开。它把高频能力显性化，降低用户记忆成本，同时为开发者提供稳定的入口，可携带参数、回调查询、甚至唤起 Web App。与“键盘按钮”相比，指令菜单常驻界面、跨群聊与私聊均可触发，更适合工具型、服务型 Bot。

版本演进：从 1.0 到 3.0 的菜单能力变迁

2015 年的 Bot API 1.0 仅支持静态命令列表；2021 年 5.4 版引入botCommandScope，允许按“私聊/群聊/管理员”隔离可见命令；2024 年 7.0 把菜单与 Web App 打通，支持menu_button字段直接跳转 Mini App；2026 年 2 月最新一次更新，把单 Bot 命令上限从 100 提升至 200 条，并支持 64 字节内嵌回调数据。对开发者而言，这意味着可以把更多子功能收拢到菜单，而无需再嵌套多层 Inline Keyboard。

前置检查：确认 Bot 身份与权限

指令菜单由 Telegram 官方托管，因此必须走 BotFather 通道注册。经验性观察：若 Bot 曾被撤销再重新授权，旧菜单缓存最长需要 6 小时才能在全球客户端刷新；测试阶段可换号私聊，避免等待。确认步骤：

1. 在任意对话输入 /setmycommands 并选择目标 Bot；
2. 若提示“Sorry, this bot is not yours”，说明当前账号并非创建者，需让原账号转让或重新生成 token。

BotFather 设置：最短路径与多端入口

移动端（Android & iOS）

1. 搜索 @BotFather → 打开对话 → 底部菜单点 My Bots → 选择目标 Bot → Edit Bot → Edit Commands。
2. 按格式逐行输入：command1 - 描述1，每行≤32 字符；若需本地化，先选 Set commands in another language。

桌面端（Windows/macOS/Linux）

路径与移动端一致，但桌面版支持快捷键 Ctrl+K 调出全局搜索，输入 @BotFather 后可直接回车跳转，省去列表翻找。

Web 版（Web K / Web Z）

界面与桌面一致，注意若使用浏览器翻译插件，命令描述可能被意外翻译，导致回车提交失败；经验性观察：关闭插件后重试即可。

携带参数：如何让菜单命令附带默认值

Telegram 并未在菜单层面开放“默认参数”字段，但可通过两种变通方式实现“点击即带参”：

• 方式 A：命令+空格+参数——用户可见。例如注册 search 命令，用户点击菜单后输入框预填 /search ，用户继续键入关键字即可。适合搜索、行情等需用户二次输入场景。
• 方式 B：Inline Keyboard 回调查询——用户不可见。菜单命令仅作为入口，Bot 立即回复一行 Inline Button，按钮的 callback_data 携带 64 字节以内参数。适合“一键签到”“一键领取”等零输入场景。

获取用户点击参数：代码最小可运行示例

以下示例使用 Python 3.11 + python-telegram-bot v21（截至当前的最新版本），演示如何读取命令文本与回调数据。

from telegram import Update
from telegram.ext import Application, CommandHandler, CallbackQueryHandler

async def start(update: Update, _):
    # 读取 /start 后携带的参数
    args = update.message.text.split()[1:]
    await update.message.reply_text(f"收到参数: {args}")

async def button(update: Update, _):
    query = update.callback_query
    await query.answer()
    await query.edit_message_text(text=f"回调数据: {query.data}")

app = Application.builder().token("YOUR_TOKEN").build()
app.add_handler(CommandHandler("start", start))
app.add_handler(CallbackQueryHandler(button))
app.run_polling()

部署后，在 BotFather 注册 start 命令，用户点击菜单即触发 start，若手动输入 /start 123，Bot 会回显 收到参数: ['123']；若通过 Inline Button 回调查询，则走 button 函数。

平台差异与兼容性速查

客户端	菜单按钮位置	命令缓存刷新时间	备注
Android	输入框左侧“☰”	约 1~6 小时	杀进程可强制刷新
iOS	输入框左侧“☰”	约 1~6 小时	切换语言可触发刷新
桌面版	输入框上方“菜单”	即时~6 小时	重启客户端立即生效
Web K	同桌面版	即时~6 小时	清缓存并 Ctrl+R 生效

例外与取舍：何时不该用指令菜单

1. 命令数量>200：需改用 Inline Keyboard 或 Web App 分页，否则 BotFather 拒绝提交。
2. 参数极度动态：如每分钟更新的股票代码，维护成本高于收益，应改用自由文本搜索。
3. 多语言频变：每次改描述都需重新走 BotFather，无法像 Web 后台即时发布；若文案日更，建议菜单只保留入口，细节放在 Web App。

故障排查：菜单不更新的 3 类常见原因

1. 缓存未刷新——让测试号在私聊发送 /setmycommands 任意字符，强制客户端重新拉取。
2. Scope 冲突——若曾给群聊单独设置过命令，再次编辑时未选“Default”作用域，导致私聊看不到新命令；用 /deletecommands 清掉旧 scope 后重设。
3. 描述含特殊字符——BotFather 拒绝全角“—”或 Emoji，如用“搜索🔍”会提示格式错误；改为半角“-”即可。

与第三方协同：最小权限原则

若把菜单配置权限下放给运营同学，可创建“子令牌”：在 BotFather 用 /token 重新生成，只保留更新命令所需 scope，不开放修改头像或转让权限；后端再通过独立接口同步命令列表，避免直接暴露主令牌。

适用/不适用场景清单

• 适用：加密货币行情 Bot、工单系统、扫码签到、会员积分查询、频道订阅管理。
• 不适用：实时多人协作白板、参数组合过百的 SQL 查询器、需要富文本拖拽的文档协作。

最佳实践 6 条速记

1. 菜单命令不超过 12 条常用入口，其余放 Web App。
2. 描述用“动词+对象”结构，≤16 字，如“查询余额”而非“余额”。
3. 若命令仅供管理员，用 botCommandScopeChatMember 限定，避免普通用户误点。
4. 回调数据加版本前缀，如 v2_123，未来格式升级可兼容。
5. 菜单更新后，在社群发“/refresh”教学，引导用户重启客户端。
6. 定期审计：用 getMyCommands 拉取线上配置，与 Git 仓库 YAML 比对，防止手滑覆盖。

FAQ：高频疑问一次讲透

收尾：下一步行动清单

读完本文，你已了解 Telegram 机器人指令菜单从注册、参数携带到点击回调查询的完整链路。建议立即：

1. 打开 BotFather，把现有 Bot 的命令压缩到 12 条以内；
2. 在测试群验证作用域，确保管理员与普通用户看到差异化菜单；
3. 用 python-telegram-bot 或任意 SDK 跑通回调数据解析，记录 64 字节长度边界；
4. 把菜单文案纳入 Git 版本管理，下次更新先 diff 再提交，避免手滑。

完成以上四步，你的 Bot 就拥有清晰、易维护、可扩展的指令入口，同时把用户点击参数稳稳地收进后端日志。接下来，把省下的交互成本拿去打磨核心业务逻辑吧。