企业官网建设流程全解析

• 后端
• 即时通讯
• API设计

本篇技术指南聚焦 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_reply决定机器人能否在企业账户的私聊会话里"开口说话"，can_read_messages决定其能否主动消化会话状态，而后两项则控制消息的删除边界（仅限自己发送的，还是全部）。在实现客服/自动回复类企业机器人时，应优先检查can_reply与can_read_messages，二者为True时才应尝试主动回复与标记已读。

2.2 账户资料编辑类权限

这组权限对应 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 资产类权限

这是企业机器人"资产管理"能力的核心权限组。与之对应的方法包括 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 管理类权限

对应的方法包括 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.1（2025 年 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.0（2025 年 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完整描述了机器人与某个企业账户之间的连接关系，结构如下：

在 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_reply=True等参数），然后断言bot.get_business_connection()的返回与注入对象相等，可作为编写企业连接相关测试的参考模板。

五、在更新流与调度器中的角色

企业连接的建立、断开或权限编辑会通过business_connection更新事件推送给机器人。在 aiogram 中：

• 更新载体为Update.business_connection字段（见 aiogram/types/update.py），注释明确该更新在"机器人连接/断开企业账户，或用户编辑了现有连接"时触发；
• 路由器Router为它注册了独立的事件观察者self.business_connection = TelegramEventObserver(router=self, event_name="business_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(level=logging.INFO) TOKEN = "YOUR_BOT_TOKEN_HERE" bot = Bot(token=TOKEN, default=DefaultBotProperties(parse_mode=ParseMode.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())

关键点说明：

1. 不要假设rights非空：Telegram 在部分场景（如连接被禁用）可能不随更新下发权限对象，务必判空处理；
2. 权限检查优先于方法调用：企业机器人调用set_business_account_*、礼品与 Stars 相关、Stories 相关 API 前，都应先确认对应权限位为True，否则请求会被 Telegram 拒绝；
3. business_connection_id贯穿整个会话：从business_message、edited_business_message、deleted_business_messages等更新中都能取到连接 ID，可用它把同一企业账户的消息流关联起来。

七、模型实现细节：pydantic 配置与 IDE 支持

BusinessBotRights的字段行为由TelegramObject的 pydantic 配置决定（见 aiogram/types/base.py）：

• use_enum_values=True：枚举字段序列化为其原始值，便于与 Telegram JSON 无缝对接；
• extra="allow"：允许携带未知字段，Telegram 新增字段时旧版 aiogram 解析也不会崩溃；
• validate_assignment=True：实例属性赋值同样触发校验；
• frozen=True：模型实例不可变，体现 Telegram 对象"只读快照"的语义；
• populate_by_name=True、arbitrary_types_allowed=True、defer_build=True、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_reply=True, can_read_messages=True, can_delete_sent_messages=False, can_manage_stories=True, )

八、与托管机器人（Managed Bot）的权限区分

需要注意区分两套概念：BusinessBotRights描述的是企业账户场景下机器人对某个企业账户的权限；而托管机器人（Managed Bot）场景下，机器人"管理另一个机器人"，其权限通过独立的方法控制：

• aiogram/methods/get_managed_bot_token.py 与 aiogram/methods/replace_managed_bot_token.py：获取 / 轮换托管机器人的 token；
• aiogram/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设计