Telegram 机器人命令全集：内置指令与自定义开发接口详解

功能定位与变更脉络

在 Telegram 生态里，「命令」是机器人与用户唯一的官方级交互入口。Bot API 从 2015 年的 /start 单指令，到 2025 年 7.0 版已扩展到 3 类：内置指令、自定义指令、内联快捷命令。内置指令由客户端硬编码，不可改名；后两类由开发者通过 setMyCommands 接口注册，支持本地化与范围限定（群组/频道/私聊）。

经验性观察：2025-06 之后，同一机器人最多可注册 100 条命令，超出会报 400 COMMAND_LIMIT_EXCEEDED；若与频道「强制评论」灰度撞车，部分客户端会隐藏 / 符号，导致菜单拉取失败，需降级到 10.11 桌面端验证。

内置指令清单与一次性验证

以下 6 条指令在任何机器人会话中均可使用，客户端在本地解析，不经过服务器：

/start – 激活机器人并附带 deep_linking 参数
/help – 拉起默认说明，若未设置则显示「No help message」
/settings – 仅私聊可见，自动关联 BotFather 的「/setabout」文本
/privacy – 返回当前 bot 的隐私模式状态（仅群主可见）
/cancel – 中断任何等待中的 conversation 会话
/request – 向群主发送加入请求（仅对限制模式 bot 有效）

验证方法：在任意对话输入「@BotFather /mybots → 选择机器人 → Edit Bot → Show Bot Commands」，若列表为空仍能用上述 6 条，即证明为客户端级内置。

自定义命令注册：最短路径与平台差异

A. 无代码方式（BotFather 面板）

1. 私聊 @BotFather → /mybots → 选中目标 bot → Edit Bot → Edit Commands。
2. 按格式输入：command1 - Description 每行一条，最多 100 行。
3. 完成后 /setmenu 选择「Show command list」，命令立即生效，全平台同步时间 ≤ 30 s。

提示：iOS 需下拉聊天页面触发「刷新命令」；桌面版 10.12 需在输入框敲 / 后等待 1 s 拉取补全。

B. 程序化方式（setMyCommands 接口）

POST https://api.telegram.org/bot<token>/setMyCommands
Content-Type: application/json
{
  "commands": [
    {"command":"price","description":"查询实时价格"},
    {"command":"alert","description":"设置价格提醒"}
  ],
  "scope":{"type":"chat","chat_id":-100123456789},
  "language_code":"zh-cn"
}

边界：scope 为默认时，命令对「所有私聊」生效；若限定群组，则频道订阅者无法看到。同一指令可针对不同语言注册多次，客户端按用户系统语言自动切换。

命令冲突与降级策略

经验性观察：2025-07 起，相同作用域内大小写不敏感，/Price 与 /price 只能存一条，后写入覆盖前者。若机器人与频道管理员各自声明同名命令，频道级优先级高于机器人，导致机器人侧命令被隐藏。缓解方案：

为机器人增加前缀，如 /bot_price；
或把频道命令拆分到子群组，作用域隔离。

警告：一旦冲突，用户端无报错，机器人将收不到对应 update，易被误判为「命令失效」。可用 /getMyCommands 核对回包，若返回空数组即证明被覆盖。

与内联键盘、Web App 的协同

命令负责「入口」，内联键盘负责「流程」。最佳实践：/start 附带 deep_link 参数 → 机器人返回 Web App 按钮 → Web App 内部用 WebApp.initData 拿到 query_id，再回写结果。如此可把「命令可见性」与「HTML5 体验」结合，同时规避 1/0 格式文本在移动端折行问题。

权限最小化原则：Web App 只需启用 write 权限即可发消息，切勿勾选「删除消息」与「封禁成员」，降低被滥扫风险。

监控与验收指标

指标	采集方式	及格线
命令补全耗时	客户端输入 / 到菜单出现	≤ 1.2 s（Wi-Fi）
误触发率	update 中无对应 handler 占比	≤ 0.5%
多语言覆盖率	getMyCommands 返回语言数 / 主要用户语言	≥ 80%

验收脚本：每夜定时调用 /getMyCommands 与 /getChatMember 抽样 100 个群，若命令缺失或权限异常即告警。

故障排查速查表

现象：命令菜单空白

可能原因：① 机器人被群主禁用；② 作用域限定错误；③ 客户端缓存未刷新。
验证：用另一账号私聊机器人，若菜单正常则排除①；调用 getMyCommands 核对 scope；桌面端清缓存路径：设置 → 高级 → 清除本地数据库。

现象：/start 参数丢失

2025-05 之后，iOS 端通过「分享链接」打开时，若系统语言与 t.me 参数含非 ASCII 字符，会被二次 URL Encode，导致空格变 + 号。缓解：服务器端兼容解析 + 号，或在 Web App 中用 initData 重新取值。

版本差异与迁移建议

Bot API 7.0 将「菜单按钮」独立为 MenuButton 对象，支持「默认 / 指令 / Web App」三态。若你的机器人曾在 6.x 使用 setChatMenuButton 自定义文字，需在 2025-08 前迁移，否则客户端会回退到「默认」态，用户需多点一次才能展开命令列表。

迁移步骤：调用 /getChatMenuButton 导出旧配置 → 把文字写入 Web App 按钮的 text 字段 → 重新 /setChatMenuButton 并 type=web_app。完成后旧版移动端（10.10 前）仅显示「默认」箭头，不影响功能，但转化率可能下降 3–5%。

适用/不适用场景清单

高适用：客服 FAQ（日咨询 1 k 以内）、频道工具箱（投票/抽奖）、私聊订阅提醒。
谨慎使用：多轮工单系统（>5 层分支）、高频交易指令（秒级行情），建议改用内联键盘+Web App，降低输错率。
不建议：富文本编辑器、大型游戏，因命令长度≤32 字节且无法插入样式，体验受限。

最佳实践 10 条（检查表）

命名用动词+名词，如 /price_alert，避免纯英文生僻词。
为每条命令写 12–18 字中文描述，移动端不会折行。
至少覆盖 en, zh-hans, es 三种语言，占全球 MAU 72%。
用 getUpdates 长轮询时，设 timeout=30 s，减少 400 重试。
命令处理器加「输入状态」typing()，降低用户重复发送率约 8%。
对敏感操作（支付/删除）二次确认，用内联键盘而勿仅靠命令。
每周跑 /getMyCommands 抽样，防止被频道同名覆盖。
深链参数≤64 字节，防止旧版 iOS 截断。
在频道置顶消息写明「机器人指令大全」并附 t.me 链接，提升搜索曝光。
灰度发布时，用 scope 限定 10% 群，观察 24 h 误触发率 < 0.5% 再全量。

案例研究

A. 万级社群：NFT 掉落提醒机器人

场景：官方频道 8.2 万订阅，需 7×24 推送地板价变动。
做法：注册 /price /alert /unalert 三条指令，scope 限定频道评论群；用 setMyCommands 中英双语，命令描述控制在 16 字内。Web App 承接高频「自定义阈值」交互，减少群聊刷屏。
结果：上线 14 天，/alert 订阅率 31%，误触发率 0.3%，命令补全耗时中位数 0.9 s。
复盘：提前用 BotFather 面板做冷启动，10 分钟完成初版；后期切换到程序化接口，实现动态开关灰度。唯一踩坑：iOS 15 以下长按 / 符号不出现补全，需置顶教程消息引导。

B. 小型课堂：50 人编程班辅助 Bot

场景：每周直播课，老师需秒级收作业、发成绩。
做法：仅用 /submit /grade /query 三条指令，作用域设为班级群；提交作业环节用 Web App 承载代码高亮与文件上传，避免 32 字节命令限制。
结果：学生平均 38 秒完成一次提交，教师端批改效率提升 2.4 倍；零运维成本运行 6 个月。
复盘：小群场景下，命令数量宜少不宜多，把「流程」交给 Web App 可显著降低输错率；同时把 /grade 设为仅管理员可见，防止学生误点。

监控与回滚 Runbook

异常信号

1. 命令补全耗时 >2 s 且持续 5 min；2. getMyCommands 返回空数组；3. Sentry 报错「handler not found」突增；4. 用户反馈「/xxx 无响应」工单日增 >3 例。

定位步骤

立即采样 10 个群，执行 /getMyCommands 核对 scope 与语言；
用备用账号私聊机器人，确认是否全局失效；
检查是否近期修改频道管理员命令，造成同名覆盖；
查看 BotFather 历史消息，确认是否出现 400 COMMAND_LIMIT_EXCEEDED；
若启用 CDN，对比边缘节点与源站时差，排除缓存穿透。

回退指令

# 回滚到上一版命令
curl -X POST https://api.telegram.org/bot<token>/setMyCommands \
 -H "Content-Type: application/json" \
 -d @commands_backup.json

# 若需彻底清空
curl -X POST https://api.telegram.org/bot<token>/deleteMyCommands

演练清单

每月低峰期执行「灰度群→清空命令→恢复备份」全流程，要求：监控无异常告警、误触发率 <0.5%、用户 0 投诉。演练脚本纳入 CI，失败自动开 Incident 工单。

FAQ

Q1: 命令描述能否使用 Emoji？: A: 可以，但需放在句尾，避免 iOS 10.10 之前出现截断。; 背景: 官方文档未限制字符集，经验性观察显示 Emoji 占 2 字节，长度≤18 字时不会折行。
Q2: /start 参数最大长度？: A: 64 字节，含 URL Encode 后字符。; 背景: 2025-05 版 iOS 曾出现超过 64 字节被截断案例，官方后续未提升上限。
Q3: 为何桌面端敲 / 不出现补全？: A: 需等待 1 s 拉取；若仍失败，清本地数据库缓存。; 背景: 桌面版 10.12 采用懒加载，无手动刷新按钮。
Q4: 可以针对单个用户定制命令吗？: A: 不可，scope 最小粒度为群或频道。; 背景: API 未提供 user_id 级 scope，需改用内联键盘动态按钮实现。
Q5: 命令名区分大小写吗？: A: 不区分，/Price 与 /price 互斥。; 背景: 2025-07 起服务端统一转小写存储。
Q6: setMyCommands 返回 400，却无明细？: A: 常见原因是 description 为空或超过 256 字节。; 背景: 官方文档未写明长度，经验性观察得出上限。
Q7: 机器人被频道同名命令覆盖，有通知吗？: A: 无，需自测 /getMyCommands 是否返回空。; 背景: 客户端侧静默隐藏，机器人不会收到事件。
Q8: 是否支持斜杠以外的触发符号？: A: 不支持，只能使用 /。; 背景: 协议层硬编码，Bot API 未提供可配置入口。
Q9: 可以同时使用 BotFather 与 setMyCommands 吗？: A: 可以，后者会覆盖前者。; 背景: 最终以最新写入来源为准。
Q10: 命令数量超限会怎样？: A: 返回 400 COMMAND_LIMIT_EXCEEDED，不写入。; 背景: 上限 100 条，含多语言重复计数。

术语表

deep_linking: 在 /start 后携带参数，引导用户进入指定场景；首次出现：内置指令清单。
scope: setMyCommands 中的作用域对象，可限定群、频道或默认；首次出现：自定义命令注册。
BotFather: Telegram 官方机器人，用于创建与配置机器人；首次出现：无代码方式。
MenuButton: Bot API 7.0 引入的菜单按钮对象，支持三态切换；首次出现：版本差异。
Web App: Telegram 内嵌的 HTML5 应用，可通过按钮打开；首次出现：协同章节。
update: 服务器推送给机器人的事件对象，含消息、回调等；首次出现：冲突警告。
COMMAND_LIMIT_EXCEEDED: 命令数量超限错误码；首次出现：功能定位。
initData: Web App 启动时由 Telegram 签名的初始化数据；首次出现：协同章节。
privacy mode: 机器人隐私模式，决定能否读取群消息；首次出现：/privacy 指令。
typing(): sendChatAction 的「输入中」状态，用于降低重复发送；首次出现：最佳实践。
gray scale: 灰度发布，指先小范围再全量；首次出现：案例研究。
conversation 会话: 多轮交互状态，/cancel 可中断；首次出现：内置指令。
handler not found: 无对应命令处理器，被计入误触发率；首次出现：监控指标。
long polling: getUpdates 长轮询模式，减少空请求；首次出现：最佳实践。
MAU: 月活跃用户数；首次出现：多语言覆盖率。

风险与边界

不可用情形：命令长度≤32 字节，无法承载富文本；超过 100 条直接拒绝写入；频道级命令优先级高于机器人，导致隐藏且无通知。
副作用：多语言注册重复占用额度；iOS 旧版截断深链参数；桌面端懒加载失败时用户误以为机器人宕机。
替代方案：复杂流程改用内联键盘+Web App；高频交易场景用 WebSocket 推送，避免用户手动输入；需要富样式可直接发送 HTML 消息，放弃命令入口。

未来趋势与版本预期

Telegram 官方在 2025-09 的 AMA 中透露，Bot API 7.2 计划把「语音命令」纳入补全列表，用户可长按麦克风说「价格」直接匹配 /price，届时需额外提供 voice_keywords 字段；同时 Mini App 将支持「离线缓存」，命令入口可秒开而不依赖网络。建议提前在机器人简介保留英文动词，以便语音模型匹配。

收尾结论

命令是 Telegram 机器人与用户的第一触点，却也是最容易被忽视的「索引入口」。用好内置指令保底线，用活自定义指令做增长，再配合内联键盘与 Web App 承载复杂流程，可在不增加客户端学习成本的前提下，把留存率提升 10–15%。记得把「可搜索性」「可维护性」「可灰度」作为三条验收红线，下一版 API 变动时，你的机器人才不必连夜救火。