后端即时通讯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 官方 API 参考文档 Story以aiogram.types.story.Story类型为核心完整讲解其字段定义、源码实现机制以及与post_story/edit_story/delete_story/repost_story四个方法之间的调用关系。读完后你将能够在 aiogram 3.x 中正确处理Story对象的序列化与反序列化并为受管业务账号managed business account编写带富文本、可点击区域的完整故事发布代码。Story 类型官方文档中的核心定义docs/api/types/story.rst通过 Sphinx 的automodule指令自动生成 aiogram.types.story 模块的 API 页面:member-order: bysource、:undoc-members: True并排除model_config、model_fields两个 Pydantic 内部成员。其渲染出的核心内容即Story类的定义This object represents a story.该对象表示一条故事在 aiogram/types/story.py 中Story仅有两个字段的声明式定义class Story(TelegramObject): This object represents a story. chat: Chat Chat that posted the story # 发布该故事的聊天通常是对应业务账号的账号 ID id: int Unique identifier for the story in the chat # 该故事在所属聊天内的唯一标识两个字段都是必填项字段类型说明chatChat发布该故事的聊天对象从源码结构看它携带完整聊天信息ID、类型、标题等可进一步用于调用repost_story的from_chat_id参数idint故事在其所属聊天范围内的唯一 ID是edit_story与delete_story定位目标故事的关键值得注意的源码细节TYPE_CHECKING块内由butcher工具自动生成了一个__init__方法标注 “DO NOT EDIT MANUALLY!!!”它仅存在于类型检查阶段用于在没有额外 Pydantic 插件的 IDE 中提供参数补全和类型提示运行时并不依赖它实例化仍走 Pydantic 的标准流程。底层机制Story 继承自 TelegramObjectStory继承的 TelegramObject 是整个aiogram.types命名空间的基类其model_config决定了包括Story在内的所有 Telegram 对象的行为特征frozenTrue对象不可变Story实例创建后不能重新赋值字段extraallow允许未知字段透传保证 Telegram Bot API 新增字段时旧版本客户端不会反序列化失败use_enum_valuesTrue枚举字段以字符串值存储validate_assignmentTrue配合MutableTelegramObject的frozenFalse使用赋值时校验populate_by_nameTrue同时支持字段名与别名填充。此外基类还定义了一个modebefore的模型校验器remove_unset会在字段校验前剔除UNSET哨兵值——这是parse_mode/protect_content等使用Default哨兵机制的方法参数在构造请求体时的必要处理。理解这一层机制就能明白为什么Story等响应类型既严格必填字段缺失会报错又宽容未知字段不会丢失。所有 Story 相关类型均已在 aiogram/types/init.py 与 aiogram/types/init.py 中统一导出可直接from aiogram.types import Story, StoryArea, InputStoryContentPhoto使用。谁产生 Story四个业务账号故事管理方法Story不是通过 Update 推送进来的被动对象——在 aiogram 的 Bot 客户端 中它由四个can_manage_stories权限下的业务账号方法作为返回值产生方法源文件返回值用途post_storypost_story.pyStory以受管业务账号名义发布新故事edit_storyedit_story.pyStory编辑已发布的故事内容、文案与可点击区域repost_storyrepost_story.pyStory将同一机器人管理的另一个业务账号的故事转载至当前业务账号delete_storydelete_story.pybool删除机器人此前发布的某个故事四个方法都以business_connection_id业务连接唯一标识定位操作对象post_story的完整参数列表见 aiogram/client/bot.py 中的方法签名如下async def post_story( self, business_connection_id: str, content: InputStoryContentUnion, # 故事内容InputStoryContentPhoto 或 InputStoryContentVideo active_period: int, # 归档时长秒必须为 6*3600、12*3600、86400 或 2*86400 caption: str | None None, # 说明文字实体解析后 0-2048 字符 parse_mode: str | Default | None ..., # 富文本解析模式 caption_entities: list[MessageEntity] | None None, # 与 parse_mode 二选一的实体列表 areas: list[StoryArea] | None None, # 可点击区域列表 post_to_chat_page: bool | None None, # True 时故事过期后仍保留可访问 protect_content: bool | Default | None ..., # 保护内容不被转发与截屏 request_timeout: int | None None, ) - Story:其中active_period是被 Telegram 侧强约束的枚举式取值只能取 6 小时、12 小时、1 天或 2 天四个值之一。edit_story相比post_story去掉了active_period/post_to_chat_page/protect_content这些属性在创建时确定增加了story_id用于定位目标故事repost_story则通过from_chat_idfrom_story_id指明源账号与源故事且要求两个业务账号同属一个机器人管理、源故事必须是该机器人发布或转载的。故事内容类型InputStoryContent 联合类型content参数的静态类型是 InputStoryContentUnion它是带Field(discriminatortype)判别字段的 Pydantic 联合类型由两种具体类型组成InputStoryContentPhototype固定为photophoto为图片文件标识。文档明确图片必须为1080x1920且不超过10 MB且图片不可复用、只能作为新文件上传——因此通过multipart/form-data上传时应使用attach://file_attach_name引用InputStoryContentVideotype固定为video视频要求720x1280、H.265 编码、MPEG4 容器、每秒一个关键帧、不超过30 MB可选参数包括duration0-60 秒、cover_frame_timestamp静态封面帧时间戳默认 0.0与is_animation无声音频时传True。判别联合的意义在于无论是从 Bot 请求体序列化还是在类型层面从响应反序列化Pydantic 都能依据type字段自动选中正确的子类无需手写类型分派逻辑。可点击区域StoryArea 及其五种类型post_story/edit_story的areas参数接收 StoryArea 列表描述故事媒体上的可点击区域。StoryArea由两个字段组成position: StoryAreaPosition与type: StoryAreaTypeUnion。StoryAreaPosition 全部使用百分比/角度制描述矩形区域共六个必填浮点字段字段含义x_percentage/y_percentage区域中心点的横/纵坐标分别为媒体宽度/高度的百分比width_percentage/height_percentage区域矩形的宽/高分别为媒体宽度/高度的百分比rotation_angle矩形顺时针旋转角度度取值 0-360corner_radius_percentage矩形圆角半径为媒体宽度的百分比type的静态类型 StoryAreaTypeUnion 同样是discriminatortype判别联合对应 StoryAreaTypeType 枚举的五个取值类型类附加字段单条故事的数量上限linkStoryAreaTypeLinkurlHTTP 或tg://链接3 个locationStoryAreaTypeLocationlatitude、longitude、可选address10 个suggested_reactionStoryAreaTypeSuggestedReactionreaction_type、可选is_dark/is_flipped5 个weatherStoryAreaTypeWeathertemperature摄氏度、emoji、background_colorARGB 颜色值3 个unique_giftStoryAreaTypeUniqueGiftname礼品唯一名称1 个每个具体类型的type字段都被声明为Literal[StoryAreaTypeType.XXX]并带有枚举默认值序列化时天然输出正确的判别字符串。实战示例构造带可点击区域的照片故事综合以上类型与参数约束一次典型的post_story调用如下示例遵循测试用例 test_post_story.py 的写法风格from aiogram import Bot from aiogram.types import ( InputStoryContentPhoto, StoryArea, StoryAreaPosition, StoryAreaTypeLink, ) bot Bot(token...) story await bot.post_story( business_connection_idAgACAgIAA..., # 来自 get_business_connection 的连接 ID contentInputStoryContentPhoto( photoattach://story_photo, # 通过 multipart 上传的文件引用 ), active_period6 * 3600, # 6 小时后归档 caption**新品上架** 点击查看活动详情, parse_modeHTML, areas[ StoryArea( positionStoryAreaPosition( x_percentage50.0, y_percentage80.0, width_percentage60.0, height_percentage15.0, rotation_angle0.0, corner_radius_percentage5.0, ), typeStoryAreaTypeLink(urlhttps://example.com/promo), ) ], ) # story: Storystory.chat 为发布聊天story.id 可用于后续 edit_story / delete_story / repost_story调用成功后返回值即本文开头介绍的Story对象用story.chat.id可作为repost_story的from_chat_id用story.id作为edit_story/delete_story的story_id构成“发布 → 编辑 → 跨账号转载 → 删除”的完整生命周期闭环。测试验证与参考路径仓库使用MockedBot对四个方法做了单元测试验证了请求构造与结果类型的对应关系如 test_repost_story.py 断言repost_story返回与预设一致的Story实例test_delete_story.py 断言返回True。如需继续深入可参考以下仓库路径类型定义aiogram/types/story.py、aiogram/types/story_area.py、aiogram/types/input_story_content_photo.py、aiogram/types/input_story_content_video.py方法实现aiogram/methods/post_story.py、aiogram/methods/edit_story.py、aiogram/methods/repost_story.py、aiogram/methods/delete_story.py客户端入口aiogram/client/bot.py枚举与联合类型aiogram/enums/story_area_type_type.py、aiogram/types/story_area_type_union.py官方 API 文档页docs/api/types/story.rst、docs/api/methods/post_story.rst需要提醒的适用前提上述故事管理能力要求机器人与业务账号建立business_connection并具备can_manage_stories权限且各媒体格式1080x1920 照片、720x1280 H.265 视频、大小上限与区域数量上限均由 Telegram Bot 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 中 postStory 方法详解用管理型企业账户发布 Telegram 故事aiogram 中 postStory 方法详解用管理型企业账户发布 Telegram 故事 postStory 是 aiogram 提供的 Telegram后端即时通讯API设计aiogram 中 EditStory 方法详解编辑已发布商业账号 Story 的完整实战指南aiogram 中 EditStory 方法详解编辑已发布商业账号 Story 的完整实战指南 导读 editStory 是 Telegram Bot API后端即时通讯API设计aiogram deleteStory 方法详解删除企业账号 Story 的三种调用方式与底层实现aiogram deleteStory 方法详解删除企业账号 Story 的三种调用方式与底层实现 deleteStory 是 Telegram Bot AP后端即时通讯API设计上一篇Hermes Workspace Swarm2 控制平面Control Plane设计与实现解析Aurora 路由中枢、可见布线层与运维节点卡片下一篇FeHelper 简易 Postman浏览器内一站式 HTTP 接口调试与 Mock 联调实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
