★ FEATURED ARTICLE 后端即时通讯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 类型体系中的SuggestedPostParameters建议帖参数展开系统讲解它在 Telegram Bot API 中的定位、字段含义与取值范围、在各类发送方法中的接入方式以及配套的审批/拒绝与状态追踪流程。读完本文你将能在 aiogram 3.x 项目中创建带价格与定时发布约束的建议帖Suggested Post并完整走通机器人建议 → 频道管理员审批 → 定时发布/拒绝的闭环。什么是建议帖Suggested Post建议帖是 Telegram 频道协作流程中的一种机制机器人在**与频道关联的直接消息会话direct messages chat**中以普通消息的形式向频道管理员建议一篇将要发布的帖子。管理员可以在会话中直接批准或拒绝该建议批准后帖子可被定时或立即发布到频道。aiogram 对该机制的支持在 CHANGES.rst 中有完整记录主要包括新增SuggestedPostParameters类型用于描述建议帖的参数在各类发送方法中新增suggested_post_parameters参数使普通发送消息即成为建议帖新增ApproveSuggestedPost/DeclineSuggestedPost两个方法供机器人或管理员在直接消息会话中审批建议帖新增SuggestedPostInfo以及一组服务消息类型SuggestedPostApproved、SuggestedPostApprovalFailed、SuggestedPostDeclined、SuggestedPostPaid、SuggestedPostRefunded用于向机器人反馈建议帖的状态流转。SuggestedPostParameters 字段详解SuggestedPostParameters定义于 aiogram/types/suggested_post_parameters.py继承自TelegramObjectaiogram 所有 Telegram 对象的基类文档注释明确说明它包含机器人建议的一篇帖子的参数。class SuggestedPostParameters(TelegramObject): price: SuggestedPostPrice | None None send_date: DateTime | None None该类型只有两个可选字段字段签名与默认值如下表字段类型默认值含义priceSuggestedPostPrice \| NoneNone建议帖的提议价格省略则视为免费unpaid帖子send_dateDateTime \| NoneNone建议帖的提议发布时间省略则管理员可在 30 天内自行决定发布时间send_date的时间窗口约束send_date的类型是 aiogram/types/custom.py 中定义的DateTime它是一个经过 pydanticPlainSerializer标注的datetime别名赋值 Pythondatetime对象后序列化时会自动转换为 Unix 时间戳整数秒发送给 Telegram API无需手工转换。该字段存在严格的未来时间窗口约束定义于 suggested_post_parameters.py 的 docstring若指定则时间必须在未来 300 秒至**未来 2678400 秒30 天**之间若省略则帖子可以在 30 天内由批准它的用户自行决定何时发布。这一约束与审批方法ApproveSuggestedPost中的send_date约束保持一致见下文意味着提议时间和实际批准发布的时间都不允许超出 30 天这一上限。price与 SuggestedPostPriceprice字段指向SuggestedPostPrice类型定义于 aiogram/types/suggested_post_price.py描述建议帖的价格class SuggestedPostPrice(TelegramObject): currency: str amount: int字段类型必填约束currencystr是目前必须是XTRTelegram Stars或TONTON grams之一amountint是以货币最小单位计价的金额Stars 价格为 5100000nanograms 价格为 1000000010000000000000两点实践要点amount使用最小单位计价。Stars 的最小单位即 1 StarTON 的最小单位是 nanogram1 TON 10⁹ nanograms因此设置amount100表示 100 Stars价格范围在源码 docstring 中已明确Stars 必须在 5 到 100000 之间nanograms 必须在 10000000 到 10000000000000 之间超出范围会违反 Telegram API 约束。如何在发送方法中创建建议帖建议帖不是独立方法而是通过在普通发送方法上附加suggested_post_parameters参数实现的。该参数在 aiogram/methods/send_message.py 中有典型定义suggested_post_parameters: SuggestedPostParameters | None None A JSON-serialized object containing the parameters of the suggested post to send; for direct messages chats only. If the message is sent as a reply to another suggested post, then that suggested post is automatically declined关键约束来自各方法 docstring仅用于直接消息会话direct messages chats即与频道关联的私聊会话而非频道本身或群组若发送的消息是回复另一条建议帖则被回复的那条建议帖会被自动拒绝declined。在 aiogram 3.x 的当前源码中该参数已广泛接入几乎所有发送类方法包括但不限于send_message、send_photo、send_video、send_animation、send_audio、send_document、send_sticker、send_voice、send_video_note、send_location、send_contact、send_dice、send_venue、send_invoice、send_live_photo、send_paid_media、send_rich_message以及copy_message、forward_message。同时aiogram/client/bot.py 中对应的bot.send_*便捷方法以及 aiogram/types/message.py 中Message上的reply_*快捷方法例如reply_animation见 message.py均透传了suggested_post_parameters参数开发者可以直接在 Handler 中通过message.reply_photo(...)的方式快速发起建议帖。此外处理加群申请的ChatJoinRequest也提供了answer()快捷方法见 aiogram/types/chat_join_request.py其签名同样包含suggested_post_parameters允许机器人在响应加群申请的同时附带建议帖。基础示例发送一条免费建议帖from aiogram import Bot, Dispatcher, types bot Bot(tokenYOUR_TOKEN) dp Dispatcher() # 在直接消息会话中建议一条普通帖子无价格、无定时 dp.message() async def suggest_post(message: types.Message): sent await message.reply_text( 这是建议发布到频道的公告文案, suggested_post_parameterstypes.SuggestedPostParameters(), )这里传入空的SuggestedPostParameters()表示免费帖子、发布时间由管理员自行决定。示例带 Stars 定价与定时发布的建议帖from datetime import datetime, timedelta, timezone suggested_post_parameters types.SuggestedPostParameters( pricetypes.SuggestedPostPrice( currencyXTR, # Telegram Stars amount50, # 50 Stars ), # 建议在 1 小时后发布需在未来 300 秒 ~ 30 天窗口内 send_datedatetime.now(timezone.utc) timedelta(hours1), ) sent await message.reply_text( 付费频道预告每周一更新的独家内容, suggested_post_parameterssuggested_post_parameters, )由于DateTime序列化会自动将datetime转为 Unix 时间戳代码中只需使用标准库datetime/timedelta即可满足 300 秒30 天的窗口要求。建议帖的审批与拒绝流程当建议帖进入直接消息会话后拥有相应管理权限的一方可以批准或拒绝。aiogram 提供了两个对应方法类与 bot 封装方法。ApproveSuggestedPost批准发布方法类定义于 aiogram/methods/approve_suggested_post.py参数类型说明chat_idint目标直接消息会话的唯一标识message_idint待批准的建议帖消息标识send_dateDateTimeUnion \| None期望的发布时间Unix 时间戳若创建建议帖时已指定则可省略指定时不得晚于未来 2678400 秒30 天方法要求机器人持有对应频道会话的can_post_messages管理员权限成功时返回True。在 aiogram/client/bot.py 中封装为异步便捷方法async def approve_suggested_post( chat_id: int, message_id: int, send_date: DateTimeUnion | None None ) - bool: call ApproveSuggestedPost(chat_idchat_id, message_idmessage_id, send_datesend_date) return await self(call)DeclineSuggestedPost拒绝建议帖方法类定义于 aiogram/methods/decline_suggested_post.pybot 封装见 bot.py参数类型说明chat_idint目标直接消息会话的唯一标识message_idint待拒绝的建议帖消息标识commentstr \| None给建议帖创建者的拒绝理由0128 字符拒绝方法要求机器人持有can_manage_direct_messages管理员权限成功时返回True。# 拒绝建议帖并附上理由 await bot.decline_suggested_post( chat_idchat_id, message_idmessage_id, comment文案需要修改请调整后重新提交, )完整审批示例处理建议帖的回复消息结合 Message 服务消息字段可以在收到suggested_post_approved等服务消息或通过Message关联信息后执行审批dp.message() async def handle_suggested_post(message: types.Message): # 当机器人收到建议帖时例如通过 ChatJoinRequest 场景或消息里的建议帖标记 # 可结合业务逻辑决定批准或拒绝 await message.bot.approve_suggested_post( chat_idmessage.chat.id, message_idmessage.message_id, send_datedatetime.now(timezone.utc) timedelta(hours2), )注意审批的前提是建议帖出现在直接消息会话中且机器人具备对应频道的can_post_messages权限实际业务中常由频道管理员触发审批例如通过回调按钮。建议帖状态追踪与配套类型为了帮助机器人感知建议帖的后续状态aiogram 提供了一组配套类型SuggestedPostInfo定义于 aiogram/types/suggested_post_info.py包含建议帖当前状态信息字段类型说明statestr建议帖状态目前可为pending待处理、approved已批准、declined已拒绝priceSuggestedPostPrice \| None建议帖的价格省略则为免费send_dateDateTime \| None建议的发布时间省略则可在 30 天内由批准方决定服务消息类型根据 CHANGES.rst建议帖相关的服务消息已作为Message的可选字段接入suggested_post_approved→SuggestedPostApprovedaiogram/types/suggested_post_approved.pysuggested_post_approval_failed→SuggestedPostApprovalFailedaiogram/types/suggested_post_approval_failed.pysuggested_post_declined→SuggestedPostDeclinedaiogram/types/suggested_post_declined.pysuggested_post_paid→SuggestedPostPaidaiogram/types/suggested_post_paid.pysuggested_post_refunded→SuggestedPostRefundedaiogram/types/suggested_post_refunded.py。在 Handler 中可以通过消息的这些字段判断建议帖当前状态例如dp.message() async def on_suggested_post_status(message: types.Message): if message.suggested_post_approved: # 建议帖已获批可进行后续业务如通知用户 ... elif message.suggested_post_declined: # 建议帖被拒绝 ... elif message.suggested_post_paid: # 建议帖已被付费 ...底层实现与类型体系说明从源码结构看SuggestedPostParameters的__init__签名suggested_post_parameters.py由 aiogram 的butcher工具自动生成仅用于提供类型检查与 IDE 补全支持运行时则由 pydantic 完成字段校验与序列化。这一点与 aiogram 中其他所有TelegramObject派生类型的处理方式一致。同时aiogram 对建议帖审批方法提供了完整测试覆盖例如 tests/test_api/test_methods/test_approve_suggested_post.py 通过MockedBot验证了bot.approve_suggested_post(chat_id-42, message_id42)的调用链与返回值tests/test_api/test_methods/test_decline_suggested_post.py 对拒绝方法做了同样的验证。开发者可以参考这些测试理解参数如何被序列化并发送到 Telegram API。小结与注意事项SuggestedPostParameters是建议帖机制的参数载体由price与send_date两个可选字段构成二者均可省略免费帖、发布时间由批准方决定建议帖只能通过直接消息会话发送不能直接在频道内发起send_date必须落在未来 300 秒30 天窗口内price仅支持XTR与TON两种货币且金额有明确的上下限审批用approve_suggested_post需can_post_messages权限拒绝用decline_suggested_post需can_manage_direct_messages权限拒绝时可附带 0128 字符的说明通过Message上的suggested_post_approved/suggested_post_declined/suggested_post_paid/suggested_post_refunded/suggested_post_approval_failed服务消息字段机器人可以感知建议帖的完整生命周期。相关类型与方法的完整 API 参考文档位于 docs/api/types/suggested_post_parameters.rst 及同目录下的suggested_post_price、suggested_post_info、approve_suggested_post、decline_suggested_post等文档页可结合本文继续深入查阅。赞分享后端即时通讯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 中的 SuggestedPostApprovalFailed频道建议帖子审批失败服务消息解析与实战aiogram 中的 SuggestedPostApprovalFailed频道建议帖子审批失败服务消息解析与实战 导读 SuggestedPostAppro后端即时通讯API设计aiogram 中 SuggestedPostInfo 类型详解建议帖状态、定价与审批流程实战aiogram 中 SuggestedPostInfo 类型详解建议帖状态、定价与审批流程实战 在 Telegram Bot API 中建议帖Sugge后端即时通讯API设计aiogram 中 declineSuggestedPost 的完整实战指南拒绝频道直发消息中的建议帖aiogram 中 declineSuggestedPost 的完整实战指南拒绝频道直发消息中的建议帖 本指南以 aiogram 对 Telegram Bot后端即时通讯API设计上一篇磁盘空间总是不够免费开源重复文件清理工具 Czkawka5 分钟找回几十 G下一篇高效部署方案3步实现lx-music-desktop容器化实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
