企业官网建设流程全解析

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

本文围绕 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，继承自TelegramObject（aiogram 所有 Telegram 对象的基类），文档注释明确说明它"包含机器人建议的一篇帖子的参数"。

class SuggestedPostParameters(TelegramObject): price: SuggestedPostPrice | None = None send_date: DateTime | None = None

该类型只有两个可选字段，字段签名与默认值如下表：

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与 SuggestedPostPrice

price字段指向SuggestedPostPrice类型，定义于 aiogram/types/suggested_post_price.py，描述建议帖的价格：

class SuggestedPostPrice(TelegramObject): currency: str amount: int

两点实践要点：

1. amount使用最小单位计价。Stars 的最小单位即 1 Star，TON 的最小单位是 nanogram（1 TON = 10⁹ nanograms），因此设置amount=100表示 100 Stars；
2. 价格范围在源码 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(token="YOUR_TOKEN") dp = Dispatcher() # 在直接消息会话中建议一条普通帖子（无价格、无定时） @dp.message() async def suggest_post(message: types.Message): sent = await message.reply_text( "这是建议发布到频道的公告文案", suggested_post_parameters=types.SuggestedPostParameters(), )

这里传入空的SuggestedPostParameters()表示"免费帖子、发布时间由管理员自行决定"。

示例：带 Stars 定价与定时发布的建议帖

from datetime import datetime, timedelta, timezone suggested_post_parameters = types.SuggestedPostParameters( price=types.SuggestedPostPrice( currency="XTR", # Telegram Stars amount=50, # 50 Stars ), # 建议在 1 小时后发布（需在未来 300 秒 ~ 30 天窗口内） send_date=datetime.now(timezone.utc) + timedelta(hours=1), ) sent = await message.reply_text( "付费频道预告：每周一更新的独家内容", suggested_post_parameters=suggested_post_parameters, )

由于DateTime序列化会自动将datetime转为 Unix 时间戳，代码中只需使用标准库datetime/timedelta即可满足 300 秒～30 天的窗口要求。

建议帖的审批与拒绝流程

当建议帖进入直接消息会话后，拥有相应管理权限的一方可以批准或拒绝。aiogram 提供了两个对应方法类与 bot 封装方法。

ApproveSuggestedPost（批准发布）

方法类定义于 aiogram/methods/approve_suggested_post.py：

方法要求机器人持有对应频道会话的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_id=chat_id, message_id=message_id, send_date=send_date) return await self(call)

DeclineSuggestedPost（拒绝建议帖）

方法类定义于 aiogram/methods/decline_suggested_post.py，bot 封装见 bot.py：

拒绝方法要求机器人持有can_manage_direct_messages管理员权限，成功时返回True。

# 拒绝建议帖并附上理由 await bot.decline_suggested_post( chat_id=chat_id, message_id=message_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_id=message.chat.id, message_id=message.message_id, send_date=datetime.now(timezone.utc) + timedelta(hours=2), )

注意：审批的前提是建议帖出现在直接消息会话中，且机器人具备对应频道的can_post_messages权限；实际业务中常由频道管理员触发审批（例如通过回调按钮）。

建议帖状态追踪与配套类型

为了帮助机器人感知建议帖的后续状态，aiogram 提供了一组配套类型：

SuggestedPostInfo

定义于 aiogram/types/suggested_post_info.py，包含建议帖当前状态信息：

服务消息类型

根据 CHANGES.rst，建议帖相关的服务消息已作为Message的可选字段接入：

• suggested_post_approved→SuggestedPostApproved（aiogram/types/suggested_post_approved.py）；
• suggested_post_approval_failed→SuggestedPostApprovalFailed（aiogram/types/suggested_post_approval_failed.py）；
• suggested_post_declined→SuggestedPostDeclined（aiogram/types/suggested_post_declined.py）；
• suggested_post_paid→SuggestedPostPaid（aiogram/types/suggested_post_paid.py）；
• suggested_post_refunded→SuggestedPostRefunded（aiogram/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_id=42)的调用链与返回值；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权限），拒绝时可附带 0～128 字符的说明；
• 通过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设计