后端即时通讯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 Bot API 最核心的数据模型——aiogram.types.message.Message对应官方 API 的Message对象展开。它既是机器人接收一切更新事件的载体也是几乎所有发送-响应交互的出发点。读完本文你将掌握 Message 的完整字段体系消息身份、来源、媒体内容、服务消息、支付与礼物、回执信息、content_type/html_text/md_text等派生属性的底层判定逻辑、以及reply()/answer()/edit_text()/delete()等 60 个快捷方法的自动参数填充机制与适用边界并能在实际 Bot 代码中正确、高效地使用它们。本文所有代码与字段说明均以仓库内 aiogram/types/message.py5356 行为事实依据相关 API 参考页为 docs/api/types/message.rst。一、Message 是什么从 API 参考页到源码类定义docs/api/types/message.rst是 Sphinx 的automodule指令页面其全部成员字段、属性、方法由 aiogram/types/message.py 中的Message类定义与 docstring 自动生成。因此理解 Message 的最佳入口就是直接阅读该类的源码。Message类继承自MaybeInaccessibleMessage定义见 aiogram/types/maybe_inaccessible_message.py后者描述了可能对 Bot 不可访问的消息联合Message普通可访问消息InaccessibleMessage见 aiogram/types/inaccessible_message.py已删除或不可访问的消息其date恒为0可用该字段区分两类消息。在 Bot 运行时Message对象主要由Update中的message、edited_message、channel_post等字段承载并在消息处理器的message参数中直接可用。它是基于 Pydantic 的不可变数据模型必填字段仅有message_id、date、chat三个其余上百个字段均为可空的可选字段。二、字段全景身份、来源、媒体、服务消息与业务新特性Message 字段按语义可划分为如下几组字段名、类型、含义均直接取自 aiogram/types/message.py1. 消息身份与归属必填 线程字段类型说明message_idint聊天内唯一消息标识临时消息ephemeral message为 0此时消息在真正发出前不可用dateDateTimeUnix 时间戳恒为正数表示有效日期chatChat消息所属聊天message_thread_idint \| None消息所属的线程/论坛主题标识仅超级群组和私聊可用direct_messages_topicDirectMessagesTopic \| None直接消息聊天主题的信息is_topic_messagebool \| None是否发送到论坛超级群组或私聊中的主题2. 发送者与来源from_user别名from发送者User频道消息可能为空为兼容旧版若消息由聊天名义发送非频道聊天中该字段是一个伪发送者。sender_chat以聊天名义发送时如匿名管理员的超级群组、自动转发到讨论组的关联频道。sender_boost_count发送者提升boost聊天时增加的次数。sender_business_bot代表商业账户实际发送消息的 Bot仅出站消息。sender_tag超级群组中发送者的标签或自定义头衔。guest_query_id访客查询唯一标识配合AnswerGuestQuery方法回复非空时消息属于召唤访客 Bot 的聊天。business_connection_id接收消息的商业连接标识非空表示消息属于相应商业账户的聊天。forward_originMessageOriginUnion转发消息的原始信息。via_bot转发/发送消息所经由的 Bot。edit_date最后编辑时间Unix。3. 回执与引用信息reply_to_messageMessage同聊天同线程内的被回复消息注意该嵌套对象不再包含进一步的reply_to_message回复临时消息时该字段可能被省略。external_replyExternalReplyInfo跨聊天/跨主题的被回复消息信息。quoteTextQuote回复中引用原文的部分。reply_to_story被回复的 Story。reply_to_checklist_task_id/reply_to_poll_option_id被回复的清单任务 / 投票选项标识。4. 媒体内容字段互斥出现文本与链接text、entitieslist[MessageEntity]、link_preview_options、effect_id消息特效媒体animation、audio、document、live_photo、paid_media、photolist[PhotoSize]、sticker、story、video、video_note、voice说明文字caption、caption_entities、show_caption_above_media、has_media_spoiler其余交互内容checklist、contact、dice、game、poll、venue、location。值得注意的兼容性规则设置animation时document也会同时设置设置live_photo时photo也会同时设置设置venue时location也会同时设置。源码中content_type属性按固定优先级判定详见第四节测试用例test_live_photo_takes_precedence_over_phototests/test_api/test_types/test_message.py正是对这一规则验证。5. 群组服务消息与迁移new_chat_members、left_chat_member、new_chat_title、new_chat_photo、delete_chat_photo、group_chat_created、supergroup_chat_created、channel_chat_created、message_auto_delete_timer_changed、migrate_to_chat_id、migrate_from_chat_id群组迁移为超级群组、pinned_message、chat_owner_left、chat_owner_changed。其中supergroup_chat_created与channel_chat_created只能出现在reply_to_message中因为 Bot 无法在其创建时成为成员。6. 支付、礼物、投票与各类服务消息支付类invoice、successful_payment、refunded_payment、paid_star_count、direct_message_price_changed、paid_message_price_changed、is_paid_post付费帖子 24 小时内不可删除、不可编辑。礼物类gift、unique_gift、gift_upgrade_sent。分享类users_shared、user_shared、chat_shared、write_access_allowed、passport_data。论坛类forum_topic_created/edited/closed/reopened、general_forum_topic_hidden/unhidden。抽奖类giveaway_created、giveaway、giveaway_winners、giveaway_completed。其他服务消息proximity_alert_triggered、boost_added、chat_background_set、video_chat_scheduled/started/ended/participants_invited、web_app_data、connected_website、checklist_tasks_done、checklist_tasks_added、managed_bot_created、poll_option_added、poll_option_deleted、suggested_post_approved/approval_failed/declined/paid/refunded、rich_message富格式消息、community_chat_added/removed/joined。临时消息字段receiver_user接收者、ephemeral_message_id临时消息标识删除或过期后可被复用。7. 已弃用字段以下字段在 Bot API 7.0 中弃用源码通过json_schema_extra{deprecated: True}标记见 aiogram/types/message.pyforward_date、forward_from、forward_from_chat、forward_from_message_id、forward_sender_name、forward_signature、user_shared。它们仍可解析以保持向后兼容新开发应改用forward_origin等新字段。三、派生属性content_type、html_text 与 md_text1.content_type一条消息到底是什么content_type是一个propertyaiogram/types/message.py通过顺序检查各字段是否非空来判定消息类型返回值是 aiogram/enums/content_type.py 中ContentType枚举的字符串值如text、photo、new_chat_members。任何字段都未命中时返回ContentType.UNKNOWN。判定优先级自源码可推断为text→audio→animation→document→game→live_photo→photo→sticker→video→video_note→voice→checklist→contact→venue→location→ 各类服务消息字段 →rich_message→ 社区相关字段最后兜底UNKNOWN。测试 tests/test_api/test_types/test_message.py 用一个消息-类型参数化矩阵逐一验证该属性且test_for_content_type_tests同文件 L1197-L1212断言矩阵覆盖了ContentType枚举的全部非ANY成员保证任何消息都能被正确分类。实际使用中可用message.content_type ContentType.PHOTO或if message.photo:两种方式分支处理。2.html_text与md_text把实体还原成标记文本当文本消息携带entities如bold、italic、code时原始text是不含标记的纯文本。html_text与md_text属性通过_unparse_entities()aiogram/types/message.py调用TextDecoration.unparse()把实体还原为 HTML / Markdown 标记message Message( message_id42, chatChat(id42, typeprivate), datedatetime.datetime.now(), texttest, entities[MessageEntity(typebold, offset0, length4)], ) message.html_text # btest/b message.md_text # *test*这一行为由test_html_text参数化测试固定tests/test_api/test_types/test_message.py。注意该属性优先取text/entities其次取caption/caption_entities即对媒体消息也能还原说明文字。四、快捷方法从回复一条消息到操控一条消息Message类最大的亮点是把高频的以消息为上下文的操作内联成方法每个方法都是对应 API 方法的快捷方式Shortcut源码中注明DO NOT EDIT MANUALLY, auto-generated viabutcher。其核心机制是自动填充目标方法所需的chat_id、message_thread_id仅当is_topic_message、business_connection_id、reply_parameters、ephemeral_message_parameters等属性并断言chat必须存在assert self.chat is not None随后返回带Bot上下文的方法对象.as_(self._bot)交由 Dispatcher 执行。1. 回复类reply_*与answer_*回复类方法覆盖绝大多数发送能力命名规则为reply_type自动附带reply_parameters与answer_type不自动回复可显式传reply_parameters/ephemeral_message_parameters文本reply()/answer()对应SendMessage1-4096 字符见 aiogram/types/message.py媒体reply_photo/answer_photo、reply_audio、reply_animation、reply_video、reply_video_note、reply_voice、reply_document、reply_sticker、reply_media_group、reply_paid_media/answer_paid_mediaTelegram Stars 付费媒体1-25000 Stars其他reply_location、reply_venue、reply_contact、reply_poll、reply_dice、reply_game、reply_invoice、reply_rich/answer_rich富格式消息例如 aiogram/types/message.py 中reply_animation构造SendAnimation时自动填入五个上下文属性。所有方法均支持parse_mode、caption、caption_entities、disable_notification、protect_content、reply_markup等通用参数其中parse_mode、protect_content等大量参数采用Default(parse_mode)这类惰性默认值——即在未显式指定时由 Bot 级默认配置aiogram/client/default.py接管实现Bot 统一解析格式、单条消息可覆盖的分层配置。2. 编辑类edit_*系列edit_text()编辑文本/富文本/游戏消息对应EditMessageText注意未由 Bot 发送且无内联键盘的商业消息仅可在发送后 48 小时内编辑aiogram/types/message.py。edit_media()编辑动画、音频、文档、照片、视频内联消息不可上传新文件只能使用file_id或 URL。edit_caption()、edit_reply_markup()、delete_reply_markup()等价于传reply_markupNone的编辑。edit_live_location()/stop_live_location()实时位置编辑与停止live_period内可反复编辑0x7FFFFFFF表示可永久更新。临时消息编辑edit_ephemeral_text()、edit_ephemeral_caption()、edit_ephemeral_media()、edit_ephemeral_reply_markup()这些方法额外断言receiver_user与ephemeral_message_id必须存在。3. 转发、复制与发送副本forward()转发任意类型消息对应ForwardMessage服务消息与受保护内容不可转发自动填充from_chat_id/message_id。copy_to()基于官方copyMessage的复制对应CopyMessage返回MessageId服务消息、付费媒体、抽奖与发票消息不可复制测验投票仅在correct_option_ids已知时可复制。send_copy()历史更悠久的发送副本aiogram/types/message.py。源码 docstring 明确指出它并不调用 API 的copyMessage方法而是按消息类型分流文本→SendMessage携带原entities与link_preview_options、照片→SendPhoto取photo[-1]即最大尺寸、音频/动画/文档/视频等→对应的 Send 方法复用原file_id与caption、掷骰子→SendDice骰子点数无法控制、Story→ForwardMessage无法处理的类型抛出TypeError(This type of message cant be copied.)。相比copy_to它返回发送后的完整Message而非MessageId。4. 管理类删除、置顶、反应与访客回复delete()删除消息对应DeleteMessage限制包括消息必须为 48 小时内发送、群组/频道创建类服务消息不可删除、私聊骰子消息须超过 24 小时、Bot 需相应管理员权限等。pin()/unpin()置顶/取消置顶群组需can_pin_messages、频道需can_edit_messages权限。react()设置消息反应对应SetMessageReactionBot 最多设置一个非付费反应付费反应禁止使用。answer_guest_query()回复访客消息对应AnswerGuestQuery断言guest_query_id必须存在成功返回SentGuestMessage。get_url(force_privateFalse, include_thread_idFalse)生成消息链接详见下节。五、get_url()生成可分享的消息链接get_url()aiogram/types/message.py依据聊天类型返回消息的t.me链接私聊private与普通群组group返回None不可分享频道/超级群组有username且未强制私有https://t.me/username/message_id无 username 或force_privateTruehttps://t.me/c/shifted_id/message_idshifted_id为去掉-100前缀的聊天 IDinclude_thread_idTrue且消息属于论坛主题时https://t.me/username/thread_id/message_id。测试 tests/test_api/test_methods/test_get_url.py 用参数化用例全面覆盖了聊天类型、username 有无、强制私有、主题消息等 28 种组合是理解该方法的权威参考。六、as_reply_parameters()与临时消息回复链的底层实现所有reply_*方法都依赖as_reply_parameters()aiogram/types/message.py构建ReplyParameters。其关键逻辑在于区分普通消息与临时消息普通消息message_idself.message_idchat_idself.chat.id临时消息ephemeral_message_id非空message_idNone、chat_idNone改用ephemeral_message_id定位。as_ephemeral_message_parameters()同文件 L910-L925则只对临时消息且存在from_user时返回EphemeralMessageParameters携带receiver_user_id普通消息返回None。callback_query_id与replace_callback_query_message属于回调查询而非消息故作为方法参数显式传入。相应行为由测试test_as_reply_parameters/test_as_reply_parameters_ephemeral/test_reply_to_ephemeral_message_is_ephemeral等固定tests/test_api/test_types/test_message.py回复临时消息的回复本身也必须是临时消息对普通消息使用answer()并显式传入ephemeral_message_parameters即可发送不引用原消息的临时回复。此外test_reply_does_not_expose_deprecated_receiver_user_id同文件 L1299-L1306确认receiver_user_id已由ephemeral_message_parameters取代不再暴露为快捷方法参数。七、实战示例在处理器中组合运用from aiogram import F, Router from aiogram.enums import ContentType from aiogram.types import Message router Router() router.message(F.text) async def text_handler(message: Message) - None: # 1. 派生属性判定类型、还原标记文本 assert message.content_type ContentType.TEXT print(message.html_text) # 含实体的 HTML 文本 # 2. reply()自动填充 chat_id / reply_parameters静默回复 await message.reply(f你说了{message.text}, disable_notificationTrue) # 3. edit_text()编辑自己的消息 sent await message.answer(稍等正在处理…) await sent.edit_text(处理完成 ✅) router.message(F.photo) async def photo_handler(message: Message) - None: # 4. reply_photo()把收到的照片原样回发最大尺寸 await message.reply_photo(message.photo[-1].file_id, caption收到你的照片) # 5. get_url()生成频道/群组消息链接 if url : message.get_url(force_privateFalse, include_thread_idTrue): print(消息链接:, url)要点回顾字段判定content_type按优先级顺序判定live_photo优先于photo回复与回答reply_*自动引用原消息answer_*更自由显式reply_parameters/ephemeral_message_parameters编辑约束非 Bot 发送的商业消息 48 小时编辑窗口删除 48 小时窗口骰子消息 24 小时复制语义copy_to走官方copyMessagesend_copy走类型分流的本地实现临时消息message_id为 0回执改用ephemeral_message_id回复临时消息的回复仍为临时消息。参考资源API 文档页docs/api/types/message.rst类源码aiogram/types/message.py联合基类aiogram/types/maybe_inaccessible_message.py、aiogram/types/inaccessible_message.py类型枚举aiogram/enums/content_type.py单元测试tests/test_api/test_types/test_message.py、tests/test_api/test_methods/test_get_url.py赞分享后端即时通讯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 forwardMessage 实战指南Bot 方法、方法对象与 Message.forward 快捷转发全解析aiogram forwardMessage 实战指南Bot 方法、方法对象与 Message.forward 快捷转发全解析 在 aiogram 3.x 中后端即时通讯API设计aiogram sendGame 发送游戏消息完整指南Bot 方法、方法对象与快捷调用全解析aiogram sendGame 发送游戏消息完整指南Bot 方法、方法对象与快捷调用全解析 本篇技术指南围绕 aiogram 框架中 sendGame 后端即时通讯API设计axios 响应对象Response Schema完全解析字段结构、状态码判定与类型系统axios 响应对象Response Schema完全解析字段结构、状态码判定与类型系统 axios 的每一个请求最终都会兑现为一个结构固定的响应对象它网络后端前端上一篇探秘高效能浏览器启动器chrlauncher下一篇5个技巧快速解决手写体OCR识别难题PaddleOCR终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考