aiogram 中 BotCommandScopeChatMember 详解：为群组特定成员定制 Bot 命令作用域-北京尧图网络

后端即时通讯API设计【免费下载链接】aiogramaiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio项目地址https://gitcode.com/gh_mirrors/ai/aiogram点击查看免费下载导读BotCommandScopeChatMember是 aiogram 中用于表示Bot 命令作用域覆盖某个群组/超级群组中特定成员的类型对象是 Telegram Bot API 命令菜单bot commands精细化权限控制的最后一环。本文将以 docs/api/types/bot_command_scope_chat_member.rst 对应的源码实现为主线结合setMyCommands/getMyCommands的实际调用链讲解该作用域的三个字段、它与另外六种作用域的关系、pydantic 判别式联合的序列化原理以及将命令仅暴露给单个用户的可运行示例。读完本文你将掌握如何让一个群里的某个成员看到专属命令菜单而其他人不受影响。一、类型定位七种 Bot 命令作用域之一在 Telegram Bot API 中作用域BotCommandScope定义了 Bot 命令列表对哪些用户生效。aiogram 的基类 bot_command_scope.py 明确列出当前支持的7 种作用域作用域类type值生效范围BotCommandScopeDefaultdefault所有用户默认BotCommandScopeAllPrivateChatsall_private_chats所有私聊BotCommandScopeAllGroupChatsall_group_chats所有群组/超级群组BotCommandScopeAllChatAdministratorsall_chat_administrators所有群聊管理员BotCommandScopeChatchat单个聊天内的所有用户BotCommandScopeChatAdministratorschat_administrators单个聊天内的管理员BotCommandScopeChatMemberchat_member单个聊天内的单个成员BotCommandScopeChatMember是其中粒度最细的一档它把命令菜单精确到哪个群哪个人而本文的关联文档 bot_command_scope_chat_member.rst 正是该类型在 API 参考中的正式条目通过 Sphinxautomodule指令自动生成类与字段文档。二、字段详解type、chat_id、user_idBotCommandScopeChatMember的全部内容实现在 aiogram/types/bot_command_scope_chat_member.py共三个字段且三个字段均为必填class BotCommandScopeChatMember(BotCommandScope): type: Literal[BotCommandScopeType.CHAT_MEMBER] BotCommandScopeType.CHAT_MEMBER chat_id: ChatIdUnion user_id: int2.1type作用域类型固定为chat_member字段声明为Literal[BotCommandScopeType.CHAT_MEMBER]且默认值就是BotCommandScopeType.CHAT_MEMBER即字符串chat_member。该枚举定义在 aiogram/enums/bot_command_scope_type.py 中与 Telegram API 文档保持一致。由于是Literal类型且带默认值实际使用时无需手动传入typeaiogram 会自动补全。这一点与后面要讲的判别式序列化直接相关。2.2chat_id目标群组标识chat_id的类型是ChatIdUnion其定义在 aiogram/types/chat_id_union.pyChatIdUnion: TypeAlias int | str即可以传入数字 ID群组/超级群组的唯一数字标识如-1001234567890字符串用户名目标超级群组的username形式仅超级群组支持以用户名定位。需要特别注意的是 Telegram API 的硬性限制频道私信Channel Direct Messages聊天和频道Channel聊天不受支持即chat_id不能指向频道类聊天。2.3user_id目标用户标识user_id是目标用户的唯一数字标识int。该用户必须是该群组/超级群组的成员——作用域天然只对群内成员有意义如果对非成员指定命令命令菜单不会对其生效。三、源码级原理判别式联合与序列化aiogram 并非把BotCommandScopeChatMember当作孤立的模型而是通过 pydantic 的**判别式联合discriminated union**把它和其他六种作用域统一收口。定义在 aiogram/types/bot_command_scope_union.pyBotCommandScopeUnion: TypeAlias Annotated[ BotCommandScopeDefault | BotCommandScopeAllPrivateChats | BotCommandScopeAllGroupChats | BotCommandScopeAllChatAdministrators | BotCommandScopeChat | BotCommandScopeChatAdministrators | BotCommandScopeChatMember, Field(discriminatortype), ]这里Field(discriminatortype)意味着当SetMyCommands.scope字段类型为BotCommandScopeUnion被序列化或反序列化时pydantic 会以type字段的值作为判别键自动路由到正确的子类。因此你构造BotCommandScopeChatMember(chat_id..., user_id...)时type自动为chat_member序列化后得到{type: chat_member, chat_id: ..., user_id: ...}收到 Telegram 返回的数据时type: chat_member也会被正确还原为BotCommandScopeChatMember实例。所有作用域类型都在 aiogram/types/init.py 中统一导出因此使用方直接from aiogram.types import BotCommandScopeChatMember即可无需关心模块内部路径。四、实战为群内单个成员定制命令菜单BotCommandScopeChatMember的典型应用场景是setMyCommands/getMyCommands这两个 API。在 aiogram 中它们分别对应 SetMyCommands 与 GetMyCommands 两个方法类并通过Bot实例封装为便捷方法见 aiogram/client/bot.py 的bot.set_my_commands(...)与 aiogram/client/bot.py 的bot.get_my_commands(...)。4.1 只给某个成员设置专属命令假设你的 Bot 管理着一个超级群组ID-1001234567890你希望只有用户 ID 为76543210的成员能看到/admin命令菜单其余成员不受影响import asyncio from aiogram import Bot from aiogram.types import BotCommand, BotCommandScopeChatMember async def main() - None: bot Bot(tokenYOUR_BOT_TOKEN) ok: bool await bot.set_my_commands( commands[ BotCommand(commandadmin, description打开管理面板), BotCommand(commandstats, description查看群统计), ], scopeBotCommandScopeChatMember( chat_id-1001234567890, # 目标超级群组数字 ID user_id76543210, # 目标成员 ), # language_code 可省略或指定为 zh / en 等两个字母的 ISO 639-1 代码 language_codezh, ) print(设置成功 if ok else 设置失败) await bot.session.close() if __name__ __main__: asyncio.run(main())要点说明commandsBotCommand列表最多 100 条。每条命令的command字段限 1–32 字符只能包含小写英文字母、数字和下划线description限 1–256 字符见 aiogram/types/bot_command.py。language_code可选参数两个字母的 ISO 639-1 语言代码。若省略该作用域命令会应用于该群内没有专属语言命令的所有相关用户指定后仅对该语言用户生效可实现多语言命令菜单并存。scope由于BotCommandScopeUnion的判别式机制直接把BotCommandScopeChatMember实例传入即可。4.2 查询某个成员当前看到的命令与之对应用getMyCommands可以反查某作用域下已设置的命令列表from aiogram.types import BotCommandScopeChatMember commands await bot.get_my_commands( scopeBotCommandScopeChatMember( chat_id-1001234567890, user_id76543210, ), ) # 返回 list[BotCommand]若未设置返回空列表当scope参数缺省时两者都默认使用BotCommandScopeDefault作用于所有用户这是 Telegram API 的默认行为定义见 SetMyCommands 与 GetMyCommands 的字段说明。4.3 与命令作用域的组合使用实际项目中常把多级作用域叠加使用实现默认全员可见特定成员额外可见的菜单策略from aiogram.types import ( BotCommand, BotCommandScopeChatMember, BotCommandScopeDefault, ) # 第一步对全员设置通用命令 await bot.set_my_commands( commands[BotCommand(commandstart, description开始)], scopeBotCommandScopeDefault(), ) # 第二步仅对某群内的某成员追加管理命令 await bot.set_my_commands( commands[BotCommand(commandadmin, description管理面板)], scopeBotCommandScopeChatMember(chat_id-1001234567890, user_id76543210), )此时该成员的命令菜单为通用命令专属命令的并集而其他成员只看到通用命令——这正是 Telegram 命令作用域从默认到具体逐级覆盖机制的实际应用。五、使用限制与注意事项结合 aiogram/types/bot_command_scope_chat_member.py 中字段注释与 Telegram API 约束使用时有几点需要牢记不支持频道chat_id不能是频道Channel或频道私信Channel Direct Messages聊天仅限普通群组/超级群组user_id必须是群成员作用域对象本身不做成员校验若目标用户不在群内命令不会对其生效三个字段全必填构造时必须同时提供chat_id与user_idtype有默认值可省略缺少任一必填字段会导致 pydantic 校验失败数字 ID 与用户名二选一chat_id用int传数字 ID、用str传username注意字符串形式只对超级群组有效命令数上限单个setMyCommands调用最多 100 条命令超限会请求失败。六、测试与验证aiogram 仓库为setMyCommands/getMyCommands提供了 MockedBot 级别的 API 测试可作为验证调用链的参考tests/test_api/test_methods/test_set_my_commands.py通过bot.add_result_for(SetMyCommands, okTrue, ...)模拟响应并断言bot.set_my_commands(commands[])返回Truetests/test_api/test_methods/test_get_my_commands.py验证bot.get_my_commands()返回list[BotCommand]。从源码结构可以看出Bot.set_my_commands内部实际是构造SetMyCommands方法对象并交给请求中间件执行aiogram/client/bot.pyscope对象在序列化时由BotCommandScopeUnion的判别式字段保证正确输出type: chat_member。因此当你传入BotCommandScopeChatMember时最终发给 Telegram 的 JSON 载荷形如{ commands: [{command: admin, description: 打开管理面板}], scope: { type: chat_member, chat_id: -1001234567890, user_id: 76543210 }, language_code: zh }结语BotCommandScopeChatMember是 aiogram 命令作用域体系中精度最高的类型通过chat_idint | str锁定群组、user_id锁定成员、type固定为chat_member配合BotCommandScopeUnion的判别式联合它在setMyCommands/getMyCommands调用链中实现一人一菜单的精准控制。无论是搭建带管理后台的社群 Bot还是实现按成员等级展示命令的复杂菜单体系掌握该作用域都是不可或缺的一环。赞分享后端即时通讯API设计【免费下载链接】aiogramaiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio项目地址https://gitcode.com/gh_mirrors/ai/aiogram点击查看免费下载相关推荐aiogram 中的 BotCommandScopeChatAdministrators为指定群组管理员单独设置机器人命令作用域aiogram 中的 BotCommandScopeChatAdministrators为指定群组管理员单独设置机器人命令作用域 BotCommandScop后端即时通讯API设计aiogram 中使用 setChatAdministratorCustomTitle为超级群组管理员设置自定义头衔的完整指南aiogram 中使用 setChatAdministratorCustomTitle为超级群组管理员设置自定义头衔的完整指南本文围绕 aiogram 框架后端即时通讯API设计Karmada karmadactl taint 命令详解为成员集群打污点并控制联邦调度Karmada karmadactl taint 命令详解为成员集群打污点并控制联邦调度本文围绕 Karmada 的 karmadactl taint 命令音视频桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

aiogram 中 BotCommandScopeChatMember 详解：为群组特定成员定制 Bot 命令作用域

相关推荐

7.89GB 文件不等于 8GB 显存能跑：Saluki 27B 部署前没人告诉你的内存真相

winapp CLI快速上手：10分钟从零跑通第一个带Windows包身份的应用

导弹烟雾火焰数据集解析：VOC与YOLO双格式目标检测训练指南

更多资讯

心脏病数据集分析预测实战：从数据清洗到模型部署的完整流程

从零到两万星：一套被AI助手推荐的开源AI编程教程设计复盘

Spring Boot + Vue打造果园水果预售系统：全链路设计与实践

双Richards方程双渗模型：破解优先流模拟难题的实战指南

PPT Master 逐页逐对象动画定制（Customize Animations）阶段实战指南：从 `animations.json` 编排到 Morph 确定性配对

Android 广播 - 组件通信

今日更新

Susi AI API实战指南：susi_alexa_skill如何用Node.js调用chat.json获取智能回答

换新电脑了？KeyStats 恢复码数据找回完全指南，端到端加密统计一键重建

重建二叉树：由前序与中序遍历序列还原二叉树的原理与 Java 实现（YCBlogs 剑指 Offer 精讲）

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？