后端即时通讯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点击查看免费下载sendVenue是 Telegram Bot API 中用于向用户发送地点卡片Venue的核心方法在 aiogram 中对应aiogram.methods.send_venue.SendVenue这个类型安全的方法对象同时通过bot.send_venue()与各种answer_venue/reply_venue快捷键对外暴露。本文以 docs/api/methods/send_venue.rst 为主线结合仓库源码深入讲解 SendVenue 的完整参数体系、四种调用方式、底层请求机制与自动填充逻辑帮助你在自己的 Telegram Bot 中准确发送带坐标、地址和第三方平台标识的地点消息。方法概述与返回值SendVenue对应 Bot API 的sendVenue方法用于向指定聊天发送一个地点信息。调用成功后返回一个Message对象即所发送的地点消息本身该消息的venue字段会携带完整的Venue信息。从源码看方法对象的定义位于 aiogram/methods/send_venue.pyclass SendVenue(TelegramMethod[Message]): __returning__ Message __api_method__ sendVenue其中__api_method__声明了发送到 Telegram 服务端的方法名__returning__声明了响应反序列化后的类型框架会根据这两个类属性自动完成请求构造与响应解析。与地点消息相关的核心类型Venue定义在 aiogram/types/venue.py包含字段字段类型说明locationLocation地点坐标不能是实时位置titlestr地点名称addressstr地点地址foursquare_id/foursquare_typestr | NoneFoursquare 地点标识与类型google_place_id/google_place_typestr | NoneGoogle Places 地点标识与类型四种标准调用方式原文档将 SendVenue 的使用归纳为四种模式下面逐一展开并结合源码说明。1. 作为 Bot 方法直接调用最直接的方式是通过Bot实例上的异步方法result: Message await bot.send_venue(...)该方法的签名定义在 aiogram/client/bot.py。其内部实现非常简洁——构造一个SendVenue方法对象后经由await self(call, request_timeoutrequest_timeout)交给 Bot 的__call__执行async def send_venue(self, chat_id, latitude, longitude, title, address, ...) - Message: call SendVenue(chat_idchat_id, latitudelatitude, ...) return await self(call, request_timeoutrequest_timeout)Bot 的__call__aiogram/client/bot.py会把方法对象交给当前配置的会话session发送到 Telegram 服务器因此你还可以通过request_timeout参数单独控制本次请求的超时时间。2. 作为独立方法对象调用SendVenue本身是一个 pydantic 模型对象可以从方法模块或方法包中导入# 直接导入方法类 from aiogram.methods.send_venue import SendVenue # 或者使用便捷别名 from aiogram.methods import SendVenue result: Message await bot(SendVenue(...))这种方法即对象的设计让请求可复用、可组合、可延迟执行。方法对象继承自TelegramMethodaiogram/methods/base.py它同时继承了BotContextController与 pydantic 的BaseModel。值得注意的底层机制是__await__魔术方法aiogram/methods/base.pydef __await__(self): bot self._bot if not bot: raise RuntimeError( This method is not mounted to a any bot instance, please call it explicilty with bot instance await bot(method)\n or mount method to a bot instance method.as_(bot) and then call it await method ) return self.emit(bot).__await__()这意味着方法对象可以直接await——但前提是它已经绑定到某个 Bot 实例。绑定通过BotContextController.as_()完成aiogram/client/context_controller.py例如method SendVenue(...) method.as_(bot) result: Message await method # 绑定后可直接 await # 或者每次显式指定 bot result: Message await bot(SendVenue(...))如果既未绑定又没有显式传入 botawait时会抛出RuntimeError提示你显式调用await bot(method)或先method.as_(bot)。这也是 aiogram 方法对象统一遵循的调用约定。3. 在 Webhook 处理器中作为回复返回在基于 Webhook 的架构中处理器可以直接返回一个方法对象由框架代为执行并将结果作为 Webhook 响应return SendVenue(...)实现这一能力的是 Webhook 响应构建逻辑。以 aiohttp 实现为例aiogram/webhook/aiohttp_server.pydispatcher.feed_webhook_update返回的结果若为TelegramMethod实例框架会自动将其发送给 Telegram否则返回空 JSON 响应。这种模式常用于收到消息后立即回一个地点卡片的场景。4. 从收到的对象调用快捷键Shortcutaiogram 为常见业务对象提供了现成的快捷键免去手动填充chat_id、message_thread_id等上下文信息的麻烦。原文档列出的快捷键包括Message.answer_venue/Message.reply_venue在收到消息后回发地点ChatJoinRequest.answer_venue/ChatJoinRequest.answer_venue_pm回复入群申请ChatMemberUpdated.answer_venue成员状态变更时回复InaccessibleMessage.answer_venue/InaccessibleMessage.reply_venue这些快捷键的签名与send_venue基本一致区别在于自动填充的字段。以Message.reply_venueaiogram/types/message.py为例其实现会断言消息包含chat信息然后自动填充chat_id取self.chat.idmessage_thread_id仅当self.is_topic_message即论坛主题消息时取当前主题 IDbusiness_connection_id透传当前消息的业务连接 IDreply_parameters通过self.as_reply_parameters()生成ephemeral_message_parameters通过self.as_ephemeral_message_parameters()生成ChatJoinRequest.answer_venue_pm则自动使用self.user_chat_id作为目标聊天aiogram/types/chat_join_request.py从而直接把地点发给发起申请的私聊会话。SendVenue 完整参数详解根据 aiogram/methods/send_venue.py 的字段定义SendVenue共包含 23 个参数其中 5 个为必填。必填参数参数类型说明chat_idChatIdUnion目标聊天的唯一标识可以是数字 ID也可以是形如username的机器人/超级群组/频道用户名latitudefloat地点纬度longitudefloat地点经度titlestr地点名称addressstr地点地址ChatIdUnion是 aiogram 对int | str的联合类型封装见 aiogram/types/chat_id_union.py因此chat_id同时接受整数 ID 与username字符串。可选参数目标定位类参数类型说明business_connection_idstr | None代表该业务连接发送消息时的业务连接唯一标识message_thread_idint | None论坛主题Topic的消息线程 ID仅对开启主题模式的超级群组生效direct_messages_topic_idint | None发送到直聊会话时所需的直聊主题 ID第三方平台标识类参数类型说明foursquare_idstr | None该地点的 Foursquare 标识foursquare_typestr | None已知的 Foursquare 地点类型例如arts_entertainment/default、arts_entertainment/aquarium、food/icecreamgoogle_place_idstr | None该地点的 Google Places 标识google_place_typestr | NoneGoogle Places 地点类型支持的类型见 Google 官方 Supported Types 文档传入foursquare_id/google_place_id后Telegram 客户端可以在地点卡片中直接展示该平台的地点详情页链接传入类型标识则能让客户端正确归类展示图标。消息呈现与推送类参数类型说明disable_notificationbool | None静默发送用户只会收到无声音的通知protect_contentbool | Default | None保护消息内容不被转发和保存默认值为Default(protect_content)表示跟随 Bot 级别的默认配置allow_paid_broadcastbool | None传True可突破广播频率限制最高每秒 1000 条每条消息扣除 0.1 Telegram Stars从 Bot 余额中扣减message_effect_idstr | None附加到消息上的消息特效标识仅对私聊生效suggested_post_parametersSuggestedPostParameters | None直聊会话专用发送建议帖子的参数对象若此消息是对另一条建议帖子的回复则原建议帖子会被自动拒绝reply_parametersReplyParameters | None描述要回复的目标消息reply_markupReplyMarkupUnion | None附加界面选项内联键盘、自定义回复键盘、移除回复键盘或强制用户回复的指令ephemeral_message_parametersEphemeralMessageParameters | None发送临时消息的参数对象其中protect_content的Default(protect_content)是 aiogram 特有的延迟解析机制——它不会在构造方法对象时立即确定布尔值而是等到实际发送时读取 Bot 实例上的默认配置该哨兵值的移除逻辑见 aiogram/methods/base.py 中的remove_unset模型校验器这让你可以在 Bot 层面统一设置保护策略再按需在单次调用中覆盖。临时消息类已弃用参数类型说明receiver_user_idint | None传出临时消息的接收用户标识仅限群组/超级群组不保证用户一定能收到。API:10.3 起标记为deprecatedcallback_query_idstr | None触发该临时消息的回调查询标识。API:10.3 起标记为deprecated回复类已弃用API:7.0 起参数类型说明allow_sending_without_replybool | None即使找不到被回复的消息也照常发送reply_to_message_idint | None作为回复时原消息的 ID这四个弃用参数在源码中通过Field(None, json_schema_extra{deprecated: True})标注见 aiogram/methods/send_venue.py迁移路径是reply_to_message_id与allow_sending_without_reply由reply_parameters取代临时消息相关能力由ephemeral_message_parameters及其配套参数取代。实战示例发送一张地点卡片结合 tests/test_api/test_methods/test_send_venue.py 中的官方测试用例一个最小可运行示例为from aiogram import Bot bot Bot(tokenYOUR_BOT_TOKEN) result: Message await bot.send_venue( chat_id42, latitude3.14, longitude3.14, titleCupboard Under the Stairs, addressUnder the stairs, 4 Privet Drive, Little Whinging, Surrey, England, Great Britain, )该测试通过MockedBot.add_result_for(SendVenue, ...)预置了一个返回Message其venue字段携带完整Venue对象的模拟响应然后断言bot.send_venue(...)的返回值与预置结果一致——这也从侧面验证了send_venue→SendVenue→Message的完整链路。在你的真实代码中result.message_id、result.venue等字段即为发送成功后返回的实体信息。在处理器内使用快捷键的典型写法router.message() async def on_message(message: Message): # 自动填充 chat_id、reply_parameters 等上下文 await message.answer_venue( latitude31.2304, longitude121.4737, title上海人民广场, address上海市黄浦区人民大道, google_place_idChIJ..., google_place_typeestablishment, )如果希望用户点击后跳转到地图应用可以在reply_markup中附加一个带url的内联键盘按钮InlineKeyboardMarkup组成完整的地点推荐卡片。使用要点与最佳实践坐标精度latitude/longitude使用 WGS84 坐标系浮点数Telegram 客户端会在地图组件中直接渲染该坐标请确保经纬度对应真实位置。优先使用快捷键凡是已有Message、ChatJoinRequest等上下文对象的场景优先使用answer_venue/reply_venue系列快捷键它们会自动填充chat_id、message_thread_id、reply_parameters等易错字段避免发错会话或漏填回复上下文。平台标识二选一或并存foursquare_id与google_place_id可同时传入客户端会优先展示可用的一方若都不传地点卡片仅展示坐标、标题与地址。Webhook 返回式写法在return SendVenue(...)的写法中方法对象由框架代为执行因此无需手动绑定 Bot——框架在构造响应时会注入当前请求对应的 Bot 实例。弃用参数迁移新代码不要使用reply_to_message_id、allow_sending_without_reply等已弃用字段统一改用reply_parameters临时消息场景则改用ephemeral_message_parameters与receiver_user_id的现行语义。总结sendVenue在 aiogram 中是一等公民的方法对象既可以await bot.send_venue(...)直接调用也可以构造SendVenue对象延迟执行、在 Webhook 中直接返回更可以通过Message、ChatJoinRequest等对象的answer_venue/reply_venue快捷键免手写上下文。其 23 个参数覆盖了从基础坐标地址、Foursquare / Google Places 第三方标识到静默通知、内容保护、付费广播、消息特效、建议帖子与临时消息等进阶能力。掌握了这套调用方式与参数语义你就可以在任何 aiogram 场景中稳定、精准地发送地点卡片。赞分享后端即时通讯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 发送富文本消息Rich Message实战指南SendRichMessage 方法全解析aiogram 发送富文本消息Rich Message实战指南SendRichMessage 方法全解析 sendRichMessage 是 Telegr后端即时通讯API设计aiogram 发送地图位置消息sendLocation 方法与实时位置Live Location实战指南aiogram 发送地图位置消息sendLocation 方法与实时位置Live Location实战指南 在 Telegram Bot API 中 s后端即时通讯API设计aiogram 中 answerWebAppQuery 方法全解Web App 结果回传与消息发送实战指南aiogram 中 answerWebAppQuery 方法全解Web App 结果回传与消息发送实战指南 本文围绕 aiogram 中 answerWebA后端即时通讯API设计上一篇Agent Zero 通知系统完全指南后端 Python 与前端 Alpine.js 的 Toast 通知与持久化实战下一篇Flipper Zero 与 HackRF 复现 LRS 餐厅寻呼机信号RAW 波形生成、曼彻斯特编码与 467.750 MHz 发射实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考