aiogram 中的 BusinessBotRights：全面解析 Telegram 企业账户机器人权限模型

后端即时通讯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 框架中用于描述企业账户Business Account机器人权限的核心类型BusinessBotRights。文章基于 docs/api/types/business_bot_rights.rst 对应的模块文档结合 aiogram/types/business_bot_rights.py 及其关联的BusinessConnection、更新分发、中间件与测试用例源码逐字段讲解 15 项权限的含义、废弃字段的迁移方案并给出在企业账户机器人实战中接收连接更新、读取权限并派发处理的完整方案。读完本文你将能准确理解并落地使用 Telegram Bot API 的企业账户机器人权限体系。一、BusinessBotRights 是什么BusinessBotRights是 aiogram 中对 Telegram Bot APIBusinessBotRights对象的类型建模用于描述一个企业机器人business bot被授予的权限集合。它不是一个方法参数而是一个承载 15 个布尔权限位的数据对象通常随企业账户连接BusinessConnection一起返回由 Telegram 服务器根据企业主在客户端中实际授予的权限动态填充。在 aiogram 中该类型定义于 aiogram/types/business_bot_rights.py继承自TelegramObject后者是BotContextController与 pydanticBaseModel的组合见 aiogram/types/base.py并已通过 aiogram/types/init.py 导出到包顶层因此可直接从aiogram.types导入。从源码结构看该类型的所有字段全部声明为bool | None None即每一项权限都是可选的布尔值只有企业主显式授予的权限才会为True未授予或未知的权限保持None这与 Telegram 官方可选字段、缺省省略的 JSON 语义完全一致。消费方代码应将None与False区分对待——None表示该项权限信息未随连接下发而非明确的禁止。二、15 个权限字段逐一详解BusinessBotRights的字段覆盖了企业机器人可触及的四类能力消息处理、账户资料编辑、礼品与 Stars 资产管理、Stories 管理。下面按功能域分组讲解语义以 aiogram/types/business_bot_rights.py 中的字段文档为准。2.1 消息处理类权限字段名类型含义can_replybool \| None机器人是否可以在最近 24 小时内有新进消息的私聊中发送和编辑消息can_read_messagesbool \| None机器人是否可以将收到的私聊消息标记为已读can_delete_sent_messagesbool \| None机器人是否可以删除由机器人自己发送的消息can_delete_all_messagesbool \| None机器人是否可以删除受管聊天managed chats中的所有私聊消息这四项构成企业机器人消息生命周期的基础权限can_reply决定机器人能否在企业账户的私聊会话里开口说话can_read_messages决定其能否主动消化会话状态而后两项则控制消息的删除边界仅限自己发送的还是全部。在实现客服/自动回复类企业机器人时应优先检查can_reply与can_read_messages二者为True时才应尝试主动回复与标记已读。2.2 账户资料编辑类权限字段名类型含义can_edit_namebool \| None机器人是否可以编辑企业账户的名与姓can_edit_biobool \| None机器人是否可以编辑企业账户的简介biocan_edit_profile_photobool \| None机器人是否可以编辑企业账户的头像can_edit_usernamebool \| None机器人是否可以编辑企业账户的用户名这组权限对应 aiogram/methods 目录中的set_business_account_name、set_business_account_bio、set_business_account_profile_photo、set_business_account_username等 API 方法。只有当BusinessBotRights中对应权限为True时调用这些方法修改企业账户资料才是被允许的。因此收到business_connection更新后的第一件事就是先解析rights判断能改什么再决定是否向企业主展示对应的管理功能。2.3 礼品与 Telegram Stars 资产类权限字段名类型含义can_change_gift_settingsbool \| None机器人是否可以修改企业账户关于礼品的隐私设置can_view_gifts_and_starsbool \| None机器人是否可以查看企业账户拥有的礼品与Telegram Stars数量can_convert_gifts_to_starsbool \| None机器人是否可以将企业账户拥有的普通礼品转换为 Telegram Starscan_transfer_and_upgrade_giftsbool \| None机器人是否可以转让和升级企业账户拥有的礼品can_transfer_starsbool \| None机器人是否可以将企业账户收到的 Telegram Stars 转入自己的账户或用它们来升级、转让礼品这是企业机器人资产管理能力的核心权限组。与之对应的方法包括 aiogram/methods/convert_gift_to_stars.py、aiogram/methods/transfer_gift.py、aiogram/methods/upgrade_gift.py、aiogram/methods/transfer_business_account_stars.py 等。注意can_transfer_stars的语义比较特殊它允许机器人把 Stars转移给自己而不是留在企业账户涉及资金流向因此在实际使用中应格外谨慎仅在明确需要结算场景时才申请该权限。2.4 Stories 管理类权限字段名类型含义can_manage_storiesbool \| None机器人是否可以代表企业账户发布、编辑和删除 Stories对应的方法包括 aiogram/methods/post_story.py、aiogram/methods/edit_story.py、aiogram/methods/delete_story.py 与 aiogram/methods/repost_story.py。三、废弃字段can_delete_outgoing_messages在 15 个字段中有一个字段带有显式的弃用标记can_delete_outgoing_messages: bool | None Field(None, json_schema_extra{deprecated: True})该字段的文档注释明确指出它已在API:9.12025 年 7 月 3 日的 Bot API 变更中被废弃见 aiogram/types/business_bot_rights.py。其语义机器人是否可以删除自己发送的消息与can_delete_sent_messages完全重叠因此新的实现应一律使用can_delete_sent_messages不再读取can_delete_outgoing_messages。同理作为其历史前置版本的BusinessConnection.can_reply字段也已在 API:9.02025 年 4 月 11 日被废弃改由BusinessConnection.rights即BusinessBotRights对象统一承载权限见 aiogram/types/business_connection.py。值得留意的是aiogram 仍保留这些废弃字段并以json_schema_extra{deprecated: True}标注是为了向后兼容已上线的存量代码——旧代码继续读写这些字段不会立刻报错但框架生成的 JSON Schema 会明确标记其为废弃项。四、BusinessBotRights 在 BusinessConnection 中的位置BusinessBotRights不是孤立存在的类型它作为BusinessConnection的rights字段被引用见 aiogram/types/business_connection.py。BusinessConnection完整描述了机器人与某个企业账户之间的连接关系结构如下字段类型含义idstr企业连接的唯一标识userUser创建该连接的企业账户用户user_chat_idint与企业主私聊的聊天标识该数值可能超过 32 位有效位需用 64 位整数或双精度浮点存储dateDateTime连接建立的时间Unix 时间戳is_enabledbool连接是否处于活跃状态rightsBusinessBotRights \| None企业机器人的权限即本文主题对象在 bot 客户端层面aiogram 通过bot.get_business_connection(business_connection_id...)主动拉取连接详情见 aiogram/client/bot.py其底层调用GetBusinessConnection方法对象定义于 aiogram/methods/get_business_connection.py。框架自带的单元测试 tests/test_api/test_methods/test_get_business_connection.py 展示了完整的模拟调用方式用MockedBot预先注入返回结果构造BusinessConnection实例并直接传入can_replyTrue等参数然后断言bot.get_business_connection()的返回与注入对象相等可作为编写企业连接相关测试的参考模板。五、在更新流与调度器中的角色企业连接的建立、断开或权限编辑会通过business_connection更新事件推送给机器人。在 aiogram 中更新载体为Update.business_connection字段见 aiogram/types/update.py注释明确该更新在机器人连接/断开企业账户或用户编辑了现有连接时触发路由器Router为它注册了独立的事件观察者self.business_connection TelegramEventObserver(routerself, event_namebusiness_connection)见 aiogram/dispatcher/router.py同时还有配套的business_message、edited_business_message、deleted_business_messages观察者用户上下文中间件UserContextMiddleware在解析事件上下文时对event.business_connection会取出user与id填充到EventContext见 aiogram/dispatcher/middlewares/user_context.py从而使处理器内可以通过event.from_user/ 事件上下文便捷地拿到企业主身份与business_connection_id。这意味着处理business_connection更新时aiogram 已经把企业主用户对象和连接 ID 从更新对象中解包好你无需手动从Update中逐层取数。六、实战处理 business_connection 更新并读取权限综合以上机制一个完整的接收企业连接更新 → 读取权限 → 按权限派发功能的处理器如下参考 examples/echo_bot.py 的入口风格编写import logging from aiogram import Bot, Dispatcher, F from aiogram.client.default import DefaultBotProperties from aiogram.enums import ParseMode from aiogram.types import BusinessConnection, BusinessMessagesDeleted, Message, Update logging.basicConfig(levellogging.INFO) TOKEN YOUR_BOT_TOKEN_HERE bot Bot(tokenTOKEN, defaultDefaultBotProperties(parse_modeParseMode.HTML)) dp Dispatcher() dp.business_connection() async def on_business_connection(connection: BusinessConnection) - None: # connection.rights 即为 BusinessBotRights 对象 rights connection.rights logging.info( business connection %s enabled%s, connection.id, connection.is_enabled, ) if rights is None: logging.warning(rights not provided for connection %s, connection.id) return # 消息处理能力 if rights.can_reply: # 可以在最近 24 小时有消息的私聊中发送/编辑消息 pass if rights.can_read_messages: # 可以标记私聊消息为已读 pass if rights.can_delete_sent_messages: # 可以删除自己发送的消息 pass if rights.can_delete_all_messages: # 可以删除受管聊天的所有私聊消息 pass # 账户资料编辑能力 if rights.can_edit_name: # 可调用 set_business_account_name 修改企业账户名 pass if rights.can_edit_bio: # 可调用 set_business_account_bio 修改简介 pass if rights.can_edit_profile_photo: # 可调用 set_business_account_profile_photo 修改头像 pass if rights.can_edit_username: # 可调用 set_business_account_username 修改用户名 pass # 礼品与 Stars 资产能力 if rights.can_view_gifts_and_stars: # 可调用 get_business_account_gifts / get_business_account_star_balance pass if rights.can_convert_gifts_to_stars: # 可调用 convert_gift_to_stars pass if rights.can_transfer_and_upgrade_gifts: # 可调用 transfer_gift / upgrade_gift pass if rights.can_transfer_stars: # 可调用 transfer_business_account_stars pass # Stories 管理能力 if rights.can_manage_stories: # 可调用 post_story / edit_story / delete_story pass dp.business_message() async def on_business_message(message: Message) - None: # 企业账户会话中收到的新消息message.business_connection_id 关联连接 ID logging.info(business message from %s: %s, message.from_user, message.text) dp.deleted_business_messages() async def on_deleted_business_messages(deleted: BusinessMessagesDeleted) - None: # 企业账户会话中消息被删除 logging.info(deleted in connection %s, deleted.business_connection_id) dp.update() async def on_other_updates(update: Update) - None: # 其余更新统一兜底 pass async def main() - None: await dp.start_polling(bot) if __name__ __main__: import asyncio asyncio.run(main())关键点说明不要假设rights非空Telegram 在部分场景如连接被禁用可能不随更新下发权限对象务必判空处理权限检查优先于方法调用企业机器人调用set_business_account_*、礼品与 Stars 相关、Stories 相关 API 前都应先确认对应权限位为True否则请求会被 Telegram 拒绝business_connection_id贯穿整个会话从business_message、edited_business_message、deleted_business_messages等更新中都能取到连接 ID可用它把同一企业账户的消息流关联起来。七、模型实现细节pydantic 配置与 IDE 支持BusinessBotRights的字段行为由TelegramObject的 pydantic 配置决定见 aiogram/types/base.pyuse_enum_valuesTrue枚举字段序列化为其原始值便于与 Telegram JSON 无缝对接extraallow允许携带未知字段Telegram 新增字段时旧版 aiogram 解析也不会崩溃validate_assignmentTrue实例属性赋值同样触发校验frozenTrue模型实例不可变体现 Telegram 对象只读快照的语义populate_by_nameTrue、arbitrary_types_allowedTrue、defer_buildTrue、protected_namespaces()则分别保障字段别名兼容、复杂类型支持与延迟构建。此外文件末尾有一段标注# DO NOT EDIT MANUALLY!!!、由butcher工具自动生成的__init__签名见 aiogram/types/business_bot_rights.py。它只存在于TYPE_CHECKING分支中运行时不会生效唯一目的是让 IDE 与类型检查器在不安装额外插件的情况下也能获得完整的构造参数补全与类型提示。因此直接以关键字参数实例化是受支持的写法from aiogram.types import BusinessBotRights rights BusinessBotRights( can_replyTrue, can_read_messagesTrue, can_delete_sent_messagesFalse, can_manage_storiesTrue, )八、与托管机器人Managed Bot的权限区分需要注意区分两套概念BusinessBotRights描述的是企业账户场景下机器人对某个企业账户的权限而托管机器人Managed Bot场景下机器人管理另一个机器人其权限通过独立的方法控制aiogram/methods/get_managed_bot_token.py 与 aiogram/methods/replace_managed_bot_token.py获取 / 轮换托管机器人的 tokenaiogram/methods/get_managed_bot_access_settings.py 与 aiogram/methods/set_managed_bot_access_settings.py读取 / 修改托管机器人的访问限制is_access_restricted与最多 10 个added_user_ids返回/接收的是BotAccessSettings对象见 aiogram/types/bot_access_settings.py与BusinessBotRights是两个不同的权限模型。从源码结构看BusinessBotRights属于企业账户连接这条功能线与BusinessConnection、Update.business_connection联动而托管机器人权限属于BotAccessSettings这条功能线与managed_bot更新联动见 aiogram/types/managed_bot_updated.py。在阅读 aiogram 源码或排查权限问题时先分清这两个模型能少走不少弯路。总结BusinessBotRights是 aiogram 中企业机器人权限的标准化载体15 个可选布尔字段覆盖消息处理、资料编辑、礼品与 Stars 资产、Stories 四大能力域随BusinessConnection.rights下发并可通过business_connection更新事件在调度器中直接消费。本文基于 docs/api/types/business_bot_rights.rst 与 aiogram/types/business_bot_rights.py 的完整字段文档辅以 aiogram/types/business_connection.py、aiogram/dispatcher/router.py、aiogram/dispatcher/middlewares/user_context.py 与 tests/test_api/test_methods/test_get_business_connection.py 等仓库证据给出了从更新接收到权限判定的完整实现路径。开发企业账户机器人时请牢记三点以rights为准判断能力边界、不再使用废弃字段、在调用资料/资产/Stories 相关 API 前先做权限位检查。赞分享后端即时通讯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 企业账户 Telegram Stars 转账指南TransferBusinessAccountStars 方法深度解析aiogram 企业账户 Telegram Stars 转账指南TransferBusinessAccountStars 方法深度解析 本文基于 aiogra后端即时通讯API设计aiogram 中 postStory 方法详解用管理型企业账户发布 Telegram 故事aiogram 中 postStory 方法详解用管理型企业账户发布 Telegram 故事 postStory 是 aiogram 提供的 Telegram后端即时通讯API设计aiogram getBusinessConnection 实战指南查询 Telegram 业务账户连接状态与权限aiogram getBusinessConnection 实战指南查询 Telegram 业务账户连接状态与权限 本文以 aiogram 框架为主线深入讲后端即时通讯API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考