什么是 Telegram 机器人命令，为什么我的列表不更新？

Telegram 机器人命令是机器人发布的斜杠关键词之一，让用户了解它能做什么。它们显示在消息框旁边的菜单中，Telegram 自己的定义也很直白："A command is a simple /keyword that tells the bot what to do."

值得用一整页来讲的不是命令本身，而是某个用户到底看到哪些命令，因为这由优先级规则而非单一列表决定，也是修改后看起来没生效的常见原因。

命令可以是什么样的？

Telegram 的格式规则严格且简短。命令 "must always start with the / symbol and contain up to 32 characters. They can use Latin letters, numbers and underscores, though simple lowercase text is recommended for a cleaner look."

所以不能有空格、连字符、重音字符，也不能超过 32 个字符（包括斜杠的关键词）。不符合这些规则的命令不是一个更短的命令，它根本不是命令。

有三个命令是所有机器人都应支持的。Telegram 要求所有开发者在适用时支持 /start、/help 和 /settings，以便用户无论打开哪个机器人都能看到一致的命令集。即使你的机器人用同一个词做完全不同的事，把这三个视为保留命令也是好习惯。

如何设置命令？

两种方式，底层是同一个列表。

你可以通过 Telegram 自带的 @BotFather 以对话方式设置，这是开发阶段的常用方式。也可以通过代码调用 Bot API 方法 setMyCommands，它接受一个数组形式的列表，最多 100 条命令，并接受一个可选的作用域参数 "Defaults to BotCommandScopeDefault"。

一旦命令内容取决于状态，就应使用 API 方式，因为它可以在状态变化时随时调用，而不必等到有人记得手动操作。

为什么我的命令列表没有变化？

因为作用域不会合并，而你之前设置的更窄作用域仍在胜出。

Telegram 的模型是一个机器人 "is able to show different commands to different users and groups"，由作用域控制，共有七个：

• BotCommandScopeDefault
• BotCommandScopeAllPrivateChats
• BotCommandScopeAllGroupChats
• BotCommandScopeAllChatAdministrators
• BotCommandScopeChat
• BotCommandScopeChatAdministrators
• BotCommandScopeChatMember

解析规则是 Telegram 文档中 "Determining list of commands" 下面的一句话："The first list of commands which is set is returned."

这就是最常见问题的全部答案。列表不会合并。Telegram 按从最具体到最宽泛的顺序依次检查作用域，并在遇到第一个已设置的作用域时停止。

在与机器人的私聊中，Telegram 的检查顺序是：botCommandScopeChat（匹配 language_code），然后 botCommandScopeChat，然后带语言代码的 botCommandScopeAllPrivateChats，然后 botCommandScopeAllPrivateChats，然后带语言代码的 botCommandScopeDefault，然后 botCommandScopeDefault。

在群组和超级群组中，序列更长，从 botCommandScopeChatMember 开始，经过仅管理员作用域和 botCommandScopeAllGroupChats，最后到达默认值。

有一点在两种场景中是相反的，这正是容易踩的坑。 在私聊中，botCommandScopeChat 是最具体的作用域。但在群组中不是：botCommandScopeChatAdministrators 及其语言变体的优先级都高于它，因此你曾设置的管理员列表会在你最期望按聊天列表生效的地方覆盖掉它。

所以如果你在测试时设置了按聊天列表，之后又修改了默认列表，那个聊天会永远显示旧列表。修复方法是清除较窄的作用域，而不是反复编辑较宽的作用域。带 language_code 变体的情况同理，它在优先级顺序中位于其自身作用域之上。

我应该怎么做？

从优先级规则可以得出三个好习惯。

1. 先设置默认作用域，最后再改它。 它是没有更窄作用域时所有人都会匹配到的兜底列表，也是大多数用户看到的列表。
2. 有意使用窄作用域，而不是图方便。 在聊天或成员级别设置的内容之后不主动查看就不会注意到，而且它会静默覆盖所有更宽的作用域。
3. 当列表看起来过时时，逐一检查作用域，而不是重新设置你刚编辑过的那个。 正在胜出的通常不是你一直在改的那个。

Bird 支持 Telegram 吗？

对于验证码，支持；但不涉及本页描述的任何内容。

Bird Verify 通过 Telegram 以及电子邮件、SMS 和 WhatsApp 发送一次性验证码，使用的是 Telegram 自有的认证通知账号，而非你自己运行的机器人。这与带命令菜单的机器人是不同的机制：不需要注册机器人，不需要发布命令，本页的内容均不适用。如果你是因为验证码投递来到这里，Bird Verify 介绍了支持的渠道及回退方式。

以上内容均为 Telegram 自身的平台行为。他们的机器人功能指南和 Bot API 参考文档是原始来源，也是查看变更的地方。