Telegram Bot API

Telegram 机器人命令:setMyCommands、命令作用域与 /start 深层链接

· 8 分钟阅读

Telegram 机器人命令是以 / 开头的关键字,例如 /start 或 /help:Telegram 客户端会在消息中高亮它们,在用户输入 / 时给出提示,并列在机器人的菜单里。命令列表可以在 @BotFather 中用 /setcommands 设置,也可以调用 setMyCommands 方法设置;后者还支持作用域(为群组、管理员或某个聊天设置不同的命令)和按语言区分的列表。机器人收到的命令就是普通文本消息,/start 还可以携带深层链接参数。本文结合 curl、Python 和 JavaScript 示例逐一讲解。

Telegram 机器人命令的工作原理

命令只是一条以 / 开头的消息。注册命令不会改变机器人收到的内容,只是告诉 Telegram 客户端该提示什么。用 setMyCommands 注册的列表(BotCommand 对象)有以下规则:

Telegram 要求每个机器人都支持全局命令 /start(开始交互,也用于接收深层链接参数)和 /help(介绍机器人的功能和命令列表),如果机器人有设置项,还应支持 /settings。命令尽量具体,例如用 /newlocation,而不是需要额外参数的笼统的 /new。

用 @BotFather 设置命令

无需写代码,适合固定不变的命令列表:

  1. 打开 @BotFather,发送 /setcommands。
  2. 选择你的机器人。
  3. 发送命令列表,每行一条,格式为 命令 - 描述:
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 部分,并忽略发给其他机器人的命令。深层链接的规则如下:

下面是一个长轮询机器人:解析命令,分别处理带参数和不带参数的 /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:在群组中发送这类命令时,其他成员和机器人都看不到,只有本机器人能收到。

机器人命令的最佳实践

常见问题排查

现象可能原因解决方法
返回 400,提示 BOT_COMMAND_INVALIDcommand 中有大写字母、连字符、开头的 /,或超过 32 个字符使用 1–32 个小写字母、数字和下划线,不带斜杠
命令已设置,但用户看到的是另一个列表更具体的作用域或用户语言的列表优先用 getMyCommands 逐个检查各作用域和语言
机器人在群里不响应 /start隐私模式开启,且最后发言的是另一个机器人发送 /start@your_bot,或修改隐私模式
收不到启动参数含有 A-Z a-z 0-9 _ - 以外的字符(例如 = 填充),或超过 64 个字符用 base64url 编码,去掉填充,缩短内容
401 UnauthorizedToken 错误或已被撤销参见 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 校验代码。