Telegram 机器人命令:setMyCommands、命令作用域与 /start 深层链接
Telegram 机器人命令是以 / 开头的关键字,例如 /start 或 /help:Telegram 客户端会在消息中高亮它们,在用户输入 / 时给出提示,并列在机器人的菜单里。命令列表可以在 @BotFather 中用 /setcommands 设置,也可以调用 setMyCommands 方法设置;后者还支持作用域(为群组、管理员或某个聊天设置不同的命令)和按语言区分的列表。机器人收到的命令就是普通文本消息,/start 还可以携带深层链接参数。本文结合 curl、Python 和 JavaScript 示例逐一讲解。
Telegram 机器人命令的工作原理
命令只是一条以 / 开头的消息。注册命令不会改变机器人收到的内容,只是告诉 Telegram 客户端该提示什么。用 setMyCommands 注册的列表(BotCommand 对象)有以下规则:
command:1–32 个字符,只能包含小写英文字母、数字和下划线,不带开头的斜杠。description:1–256 个字符,显示在提示列表中命令的旁边。- 每个列表最多 100 条命令。
Telegram 要求每个机器人都支持全局命令 /start(开始交互,也用于接收深层链接参数)和 /help(介绍机器人的功能和命令列表),如果机器人有设置项,还应支持 /settings。命令尽量具体,例如用 /newlocation,而不是需要额外参数的笼统的 /new。
用 @BotFather 设置命令
无需写代码,适合固定不变的命令列表:
- 打开 @BotFather,发送
/setcommands。 - 选择你的机器人。
- 发送命令列表,每行一条,格式为
命令 - 描述:
start - 启动机器人
help - 使用说明
settings - 个人设置
还没有机器人的话,请先阅读创建 Telegram 机器人教程。
用 setMyCommands 设置命令
setMyCommands 在代码中完成同样的事,命令列表可以放在代码仓库里,随部署一起更新。参数:commands(必填,BotCommand 数组)、scope(可选,默认为 default 作用域)和 language_code(可选,两个字母的 ISO 639-1 代码)。成功时返回 true:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMyCommands" \
-H "Content-Type: application/json" \
-d '{"commands":[{"command":"start","description":"启动机器人"},{"command":"help","description":"使用说明"}]}'
不写代码也能试:在 Bot API Tester 中打开 setMyCommands,填入 Token 和命令,点击执行。然后调用 getMyCommands 查看保存的列表。
命令作用域与语言
作用域决定谁能看到某个列表。BotCommandScope 共有 7 种类型:
作用域 type | 谁能看到 | 额外字段 |
|---|---|---|
default | 所有人(没有更具体的列表时) | — |
all_private_chats | 所有与机器人的私聊 | — |
all_group_chats | 所有群组和超级群组 | — |
all_chat_administrators | 所有群组和超级群组的管理员 | — |
chat | 某个特定聊天 | chat_id |
chat_administrators | 某个群组或超级群组的管理员 | chat_id |
chat_member | 某个群组或超级群组中的某个成员 | chat_id、user_id |
chat_id 可以是数字 ID 或超级群组的 @username;不支持频道和频道私信聊天。每个作用域还可以有按语言区分的列表:带 language_code 的列表发给使用该界面语言的用户,不带的则发给该作用域内没有专属语言列表的所有人。
Telegram 从最具体的作用域开始依次查找,显示第一个已设置的列表。私聊中的顺序是 chat → all_private_chats → default;群组中是 chat_member → chat_administrators → chat → all_chat_administrators → all_group_chats → default(管理员作用域只对管理员生效)。每一步中,匹配用户 language_code 的列表优先于不带语言的列表。
下面的脚本设置一个默认列表、一个英文版本和群管理员专用的额外命令,然后读回其中一个:
import os
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
def call(method, **params):
data = requests.post(f"{API}/{method}", json=params, timeout=10).json()
if not data["ok"]:
raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
return data["result"]
# 所有人的默认列表
call("setMyCommands", commands=[
{"command": "start", "description": "启动机器人"},
{"command": "help", "description": "使用说明"},
{"command": "settings", "description": "个人设置"},
])
# 为 Telegram 界面语言为英语的用户提供同样的命令
call("setMyCommands", language_code="en", commands=[
{"command": "start", "description": "Start the bot"},
{"command": "help", "description": "How to use the bot"},
{"command": "settings", "description": "Your settings"},
])
# 所有群组管理员的额外命令
call("setMyCommands", scope={"type": "all_chat_administrators"}, commands=[
{"command": "help", "description": "使用说明"},
{"command": "stats", "description": "群组统计"},
])
print(call("getMyCommands", scope={"type": "all_chat_administrators"}))const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
async function call(method, params = {}) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
});
const data = await res.json();
if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
return data.result;
}
// 所有人的默认列表
await call("setMyCommands", {
commands: [
{ command: "start", description: "启动机器人" },
{ command: "help", description: "使用说明" },
{ command: "settings", description: "个人设置" },
],
});
// 为 Telegram 界面语言为英语的用户提供同样的命令
await call("setMyCommands", {
language_code: "en",
commands: [
{ command: "start", description: "Start the bot" },
{ command: "help", description: "How to use the bot" },
{ command: "settings", description: "Your settings" },
],
});
// 所有群组管理员的额外命令
await call("setMyCommands", {
scope: { type: "all_chat_administrators" },
commands: [
{ command: "help", description: "使用说明" },
{ command: "stats", description: "群组统计" },
],
});
console.log(await call("getMyCommands", { scope: { type: "all_chat_administrators" } }));作用域只控制用户看到什么。更新中不会说明命令来自哪个作用域,而且用户可以手动输入任何命令,包括你从未注册的命令。务必在服务器端检查命令是否存在、用户是否有权执行(例如用 getChatMember 检查管理员权限)。
getMyCommands 与 deleteMyCommands
getMyCommands 返回指定 scope 和 language_code 下的 BotCommand 数组,没有设置时返回空数组。deleteMyCommands 删除该作用域和语言下的列表,受影响的用户随后会按查找顺序看到下一个列表:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/deleteMyCommands" \
-H "Content-Type: application/json" \
-d '{"scope":{"type":"all_chat_administrators"}}'
处理命令和 /start 参数
命令以普通 message 更新的形式到达,文本与用户输入的一致。在群组中,命令可能以 /command@your_bot 的形式指定给某个机器人,所以要去掉 @username 部分,并忽略发给其他机器人的命令。深层链接的规则如下:
https://t.me/your_bot?start=airplane会打开与机器人的聊天,机器人收到/start airplane。https://t.me/your_bot?startgroup=spaceship会让用户选择要把机器人加入的群组,机器人收到/start@your_bot spaceship。- 参数最多 64 个字符,只允许
A-Z、a-z、0-9、_和-。二进制或其他数据,Telegram 建议使用 base64url 编码。
下面是一个长轮询机器人:解析命令,分别处理带参数和不带参数的 /start,并生成 base64url 编码的深层链接:
import base64
import os
import re
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
BOT_USERNAME = requests.get(f"{API}/getMe", timeout=10).json()["result"]["username"]
COMMAND_RE = re.compile(r"^/([A-Za-z0-9_]+)(?:@([A-Za-z0-9_]+))?(?:\s+(.*))?$", re.S)
def make_start_link(payload: str) -> str:
# 去掉 "=" 填充的 base64url:只剩 A-Z a-z 0-9 _ -(最多 64 个字符)
code = base64.urlsafe_b64encode(payload.encode()).decode().rstrip("=")
return f"https://t.me/{BOT_USERNAME}?start={code}"
def read_start_param(code: str) -> str:
return base64.urlsafe_b64decode(code + "=" * (-len(code) % 4)).decode()
def parse_command(text):
m = COMMAND_RE.match(text)
if not m or (m[2] and m[2].lower() != BOT_USERNAME.lower()):
return None # 不是命令,或者是发给其他机器人的命令
return m[1].lower(), (m[3] or "").strip()
def send(chat_id, text):
requests.post(f"{API}/sendMessage", json={"chat_id": chat_id, "text": text}, timeout=10)
print("分享这个链接:", make_start_link("ref:42"))
offset = 0
while True:
resp = requests.get(f"{API}/getUpdates", params={"offset": offset, "timeout": 30}, timeout=40).json()
for update in resp["result"]:
offset = update["update_id"] + 1
msg = update.get("message")
parsed = parse_command(msg.get("text", "")) if msg else None
if not parsed:
continue
name, args = parsed
chat_id = msg["chat"]["id"]
if name == "start" and args:
try:
send(chat_id, "欢迎!你的来源是:" + read_start_param(args))
except ValueError:
send(chat_id, "欢迎!无法识别的启动参数。")
elif name == "start":
send(chat_id, "欢迎!发送 /help 查看我能做什么。")
elif name == "help":
send(chat_id, "/start - 启动机器人\n/help - 显示本帮助\n/settings - 个人设置")
elif name == "settings":
send(chat_id, "暂时还没有可用的设置。")const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const BOT_USERNAME = (await (await fetch(`${API}/getMe`)).json()).result.username;
const COMMAND_RE = /^\/([A-Za-z0-9_]+)(?:@([A-Za-z0-9_]+))?(?:\s+([\s\S]*))?$/;
function makeStartLink(payload) {
// Node 的 base64url 不带 "=" 填充:只剩 A-Z a-z 0-9 _ -(最多 64 个字符)
const code = Buffer.from(payload).toString("base64url");
return `https://t.me/${BOT_USERNAME}?start=${code}`;
}
function readStartParam(code) {
return Buffer.from(code, "base64url").toString("utf8");
}
function parseCommand(text) {
const m = COMMAND_RE.exec(text);
if (!m || (m[2] && m[2].toLowerCase() !== BOT_USERNAME.toLowerCase())) {
return null; // 不是命令,或者是发给其他机器人的命令
}
return { name: m[1].toLowerCase(), args: (m[3] ?? "").trim() };
}
async function send(chatId, text) {
await fetch(`${API}/sendMessage`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ chat_id: chatId, text }),
});
}
console.log("分享这个链接:", makeStartLink("ref:42"));
let offset = 0;
while (true) {
const resp = await (await fetch(`${API}/getUpdates?offset=${offset}&timeout=30`)).json();
for (const update of resp.result) {
offset = update.update_id + 1;
const msg = update.message;
const parsed = msg ? parseCommand(msg.text ?? "") : null;
if (!parsed) continue;
const { name, args } = parsed;
const chatId = msg.chat.id;
if (name === "start" && args) {
await send(chatId, "欢迎!你的来源是:" + readStartParam(args));
} else if (name === "start") {
await send(chatId, "欢迎!发送 /help 查看我能做什么。");
} else if (name === "help") {
await send(chatId, "/start - 启动机器人\n/help - 显示本帮助\n/settings - 个人设置");
} else if (name === "settings") {
await send(chatId, "暂时还没有可用的设置。");
}
}
}把 JavaScript 版本保存为 bot.mjs,用 Node.js 18+ 运行(代码用到了顶层 await)。启动参数要当作不可信输入:任何人都能构造链接,所以不要在里面放单凭它就能获得权限的密钥。设置了 Webhook 时 getUpdates 无法使用;正式部署请参考 Telegram Bot Webhook 设置教程。
群组中的命令与隐私模式
群组中的机器人默认处于隐私模式。此时它只会收到:明确发给它的命令(/command@your_bot)、像 /start 这样的通用命令(仅当它是最后一个在群里发言的机器人时)、对它消息的回复以及服务消息。如果一个群里有多个机器人,请让用户从命令列表中点选命令,客户端会自动加上 @your_bot。要接收全部消息,可以把机器人设为管理员,或在 @BotFather 中用 /setprivacy 关闭隐私模式。
菜单按钮
在私聊中,输入框旁边的菜单按钮默认会打开命令列表。你可以用 setChatMenuButton 把它改成打开 Mini App,或者改回命令列表;不传 chat_id 时修改的是所有聊天的默认设置:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
-H "Content-Type: application/json" \
-d '{"menu_button":{"type":"commands"}}'
其他类型还有 web_app(需要 text 和 web_app)和 default。从 Bot API 10.2 起,BotCommand 还可以设置 is_ephemeral: true:在群组中发送这类命令时,其他成员和机器人都看不到,只有本机器人能收到。
机器人命令的最佳实践
- 列表要精简。只注册用户真正需要的命令;不常用的管理工具更适合放进仅管理员可见的作用域。
- 描述写成动作。“创建提醒”比“提醒”更清楚。
- 部署时同步命令。在部署脚本中调用
setMyCommands,让菜单与处理命令的代码保持一致。 - 礼貌回应未知命令。在私聊中可以提示用户发送
/help。 - 选项交给按钮。多步骤的交互用内联键盘往往比带参数的命令更好用。
常见问题排查
| 现象 | 可能原因 | 解决方法 |
|---|---|---|
返回 400,提示 BOT_COMMAND_INVALID | command 中有大写字母、连字符、开头的 /,或超过 32 个字符 | 使用 1–32 个小写字母、数字和下划线,不带斜杠 |
| 命令已设置,但用户看到的是另一个列表 | 更具体的作用域或用户语言的列表优先 | 用 getMyCommands 逐个检查各作用域和语言 |
机器人在群里不响应 /start | 隐私模式开启,且最后发言的是另一个机器人 | 发送 /start@your_bot,或修改隐私模式 |
| 收不到启动参数 | 含有 A-Z a-z 0-9 _ - 以外的字符(例如 = 填充),或超过 64 个字符 | 用 base64url 编码,去掉填充,缩短内容 |
401 Unauthorized | Token 错误或已被撤销 | 参见 Telegram Bot Token 获取与管理教程 |
常见问题
怎样给 Telegram 机器人添加命令?
向 @BotFather 发送 /setcommands 并选择机器人,或者调用 Bot API 方法 setMyCommands,传入 BotCommand 对象列表。之后用户输入 / 时,Telegram 客户端会提示这些命令,并在菜单中列出。
Telegram 机器人命令可以包含哪些字符?
在 setMyCommands 中,命令文本为 1–32 个字符,只能包含小写英文字母、数字和下划线;描述为 1–256 个字符。每个作用域和语言最多设置 100 条命令。
怎样给 /start 传参数?
使用深层链接,例如 https://t.me/your_bot?start=airplane,机器人会收到消息 /start airplane。参数最多 64 个字符,只能使用 A-Z、a-z、0-9、_ 和 -;其他数据请用 base64url 编码。
为什么机器人在群组里收不到命令?
开启隐私模式时(默认开启),群组中的机器人只会收到明确发给它的命令,如 /command@your_bot;像 /start 这样的通用命令,只有当它是最后一个在群里发言的机器人时才会收到。请使用 @your_bot 形式、把机器人设为管理员,或用 /setprivacy 关闭隐私模式。
怎样给群管理员显示不同的命令?
调用 setMyCommands,对所有群组把 scope 设为 {"type": "all_chat_administrators"},对单个群组设为 {"type": "chat_administrators", "chat_id": ...}。服务器端仍要校验权限:更新中不会说明命令来自哪个作用域。
怎样删除机器人的全部命令?
对设置过的每个作用域和 language_code 分别调用 deleteMyCommands。删除后,用户会按查找顺序看到下一个列表,例如默认命令。
相关教程
Telegram 机器人教程:从零创建 Telegram 机器人并发送第一条消息
Telegram 机器人教程:在 @BotFather 中用 /newbot 创建机器人并获取 Token,用 getMe 验证,再通过 getUpdates 找到 chat_id,用 curl 和 Python 发出第一条消息,附常见问题排查。
Telegram 机器人部署教程:VPS、Docker 与 Serverless 托管方案
Telegram 机器人部署与托管指南:轮询还是 Webhook,VPS 上的 systemd 服务、Docker 部署、带 secret_token 校验的 Cloudflare Workers,以及上线检查清单。
Telegram Bot API 10.0–10.5 新功能:机器人设置、小组件、富文本消息、临时消息、访客模式等
Telegram Bot API 10.0–10.5 更新了什么:setMySettings 与 BotFullInfo、HTML 小组件、富文本消息、临时消息、访客模式,附 JSON 示例与升级清单。
Telegram Bot API 错误码大全:每种报错的含义与解决方法
Telegram Bot API 常见错误详解:400 chat not found、403 bot was blocked by the user、409 Conflict、429 retry_after,逐一说明原因、解决方法,并附错误处理代码。
Telegram Bot API 限制汇总:发送频率、429 错误、文件大小与消息长度
Telegram Bot API 频率限制详解:每秒约 30 条、单聊每秒 1 条、群组每分钟 20 条,429 错误与 retry_after 处理代码,以及文件大小和消息长度限制。
Telegram 机器人键盘教程:内联键盘、回调按钮与回复键盘
Telegram 机器人按钮教程:用 callback_data 创建内联键盘、answerCallbackQuery 应答、点击后编辑消息,以及回复键盘和 ForceReply,附完整 Python 与 JS 示例。
n8n Telegram 集成教程:连接机器人、触发工作流并发送消息
n8n 对接 Telegram 机器人:把 bot token 填入 Access Token,Telegram Trigger 通过公网 HTTPS Webhook 接收消息,按 chat id 发送消息,以及常见报错的解决方法。
Telegram Bot API 发送消息教程:sendMessage 参数、格式、按钮与错误处理
Telegram Bot API 发送消息中文教程:sendMessage 参数说明,curl、Python、JavaScript 示例,HTML 与 MarkdownV2 格式、内联按钮、群组和频道发送,以及 400、403、429 错误处理。
Telegram Bot Token 怎么获取:获取、查看、验证和撤销机器人 Token
Telegram Bot Token 怎么获取?用 @BotFather 的 /newbot 获取新 Token,在 /mybots 中查看已有 Token,用 getMe 检查是否有效,泄露后及时撤销,并配合 chat_id 接入 n8n 等工具。
Telegram Bot Webhook 设置教程:用 setWebhook 配置 Webhook URL 和 secret_token
Telegram Bot API setWebhook 中文教程:Webhook URL 的 HTTPS 与端口要求、secret_token 请求头校验、用 getWebhookInfo 排错、用 deleteWebhook 切回轮询,以及 409 等常见错误的解决方法。
Telegram chat id 获取教程:查看用户、群组、频道和话题的聊天 ID
Telegram chat id 获取教程:用 getUpdates 查看私聊、群组、超级群组、频道和论坛话题的聊天 ID,讲清负数和 -100 前缀的含义,并排查 result 为空、409 Conflict 等常见问题,附 Python 示例。
Telegram 内联机器人教程:开启 Inline 模式并用 answerInlineQuery 响应查询
Telegram 内联机器人(inline bot)开发教程:用 @BotFather 或 setMySettings 开启 Inline 模式,处理 inline_query 更新,并通过 answerInlineQuery 返回结果。
Telegram 机器人 Stars 支付教程:发票、预结账确认、退款与订阅
Telegram 机器人接入 Stars 支付:用 XTR 调用 sendInvoice,处理 pre_checkout_query 和 successful_payment,退款与订阅,附 Python/JS 代码。
Telegram 测试服务器:如何在 Telegram 测试环境中测试机器人
Telegram 测试服务器中文教程:如何登录测试环境、创建测试机器人、通过 /test/ 调用 Bot API,以及在 Bot API Tester 中开启 TEST 开关测试 Telegram 机器人。
Telegram 网站小部件教程:用 Telegram 登录网站、嵌入帖子、评论区与分享按钮
在网站上接入 Telegram:新版 Telegram 登录(OpenID Connect)、旧版 Login Widget 及 hash 校验代码、嵌入 Telegram 帖子、评论区小部件和分享按钮,附常见问题排查。
TelegramWidget JavaScript API:属性、事件、错误码与限制参考
TelegramWidget JavaScript API 中文参考:属性、request()、事件、错误码、CSS 变量,widget_query 与 answerWidgetQuery 的用法,以及小组件的全部限制。
Telegram Widget 示例:完整的小组件 HTML 与 Python 机器人代码
可直接运行的 Telegram widget 示例:静态订单卡片、用 widget_query 通信的计数器、共享小组件实时投票,以及本地预览与体积检查脚本,附完整 Python 代码。
Telegram 小组件(Widget)入门:在机器人消息中运行交互式 HTML
Telegram 小组件(Bot API 10.4)是什么:sendWidget 怎么发送、chat_data 与 public_data 状态如何运作、目前在哪里可用,以及与 Mini App 的区别。
Telegram Mini App 测试教程:从浏览器模拟到真实 Telegram 客户端
Telegram Mini App 测试全流程:浏览器模拟模式、通过 HTTPS 隧道在 localhost 调试、测试环境、各平台打开 DevTools 的方法,以及服务器端 initData 校验代码。