后端即时通讯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点击查看免费下载SwitchInlineQueryChosenChat是 aiogram 中用于表示切换到指定类型聊天中的内联模式按钮的 Telegram API 类型当用户点击这类内联键盘按钮时Telegram 会弹出聊天选择器但只允许选择开发者预先指定的聊天类型私聊用户、私聊机器人、群组或频道并在所选聊天的输入框中插入机器人的用户名与可选的默认内联查询。本文将以 docs/api/types/switch_inline_query_chosen_chat.rst 为核心结合 aiogram 的源码实现完整讲解该类型的全部字段、它与其他switch_inline_query_*按钮的差异以及基于InlineKeyboardMarkup、InlineKeyboardBuilder和富媒体消息按钮三种落地写法帮助你精准控制内联模式的唤起范围。SwitchInlineQueryChosenChat 是什么在 aiogram 中SwitchInlineQueryChosenChat 定义在aiogram.types.switch_inline_query_chosen_chat模块中继承自TelegramObject。它的官方定位是一个内联按钮用于将当前用户切换到所选聊天中的内联模式并带有可选的默认内联查询。其典型交互流程是用户在你的机器人对话中点击带有switch_inline_query_chosen_chat属性的内联按钮Telegram 展示一个聊天选择器且只列出符合条件的聊天例如只列群组和超级群组用户选定聊天后Telegram 自动打开该聊天并在输入框中预先填入你的机器人用户名 指定查询文本用户直接回车即可触发你的机器人处理该内联查询。这种机制常用于邀请其他群聊使用本机器人能力分享到指定类型会话等场景相比不限定类型的切换按钮它能把选择范围收敛到业务真正需要的会话类型上。与三种内联切换按钮的区别InlineKeyboardButton与RichMessageButton中与内联切换相关的字段共有三个理解差异是正确选型的前提字段行为适用场景switch_inline_query用户从任意聊天中选择一个并打开插入 bot 用户名 指定查询不限聊天类型的通用分享switch_inline_query_current_chat直接在当前聊天输入框中插入 bot 用户名 指定查询不弹出选择器引导用户在当前会话中立即使用内联模式switch_inline_query_chosen_chat弹出选择器但只允许选择指定类型的聊天需要约束目标会话类型的定向引流三者均允许查询文本为空——为空时输入框只插入机器人的用户名。字段详解根据 SwitchInlineQueryChosenChat 的源码定义该类型共包含 5 个字段全部为可选字段字段类型默认值含义querystr \| NoneNone插入输入框的默认内联查询文本留空则只插入 bot 用户名allow_user_chatsbool \| NoneNone为True时可选择与用户的私聊allow_bot_chatsbool \| NoneNone为True时可选择与机器人的私聊allow_group_chatsbool \| NoneNone为True时可选择群组与超级群组allow_channel_chatsbool \| NoneNone为True时可选择频道其中四个allow_*开关彼此独立可以任意组合。例如只设allow_group_chatsTrue则选择器里只会出现群组和超级群组allow_group_chatsTrue与allow_channel_chatsTrue同时开启则群组与频道均可选。需要注意这些开关都是白名单式的未开启的类型不会出现在选择器中。query字段的取值直接影响用户看到的内联查询内容queryNone或留空字符串输入框只插入bot_username用户自行输入查询内容querysearch输入框插入bot_username search用户可直接回车触发。源码实现从 TelegramObject 到字段校验类继承与 Pydantic 配置SwitchInlineQueryChosenChat 继承自 TelegramObject。TelegramObject基于 Pydantic 模型并配置了frozenTrue模型实例不可变保证序列化前后对象一致extraallow允许接收 Telegram 后续新增的未知字段增强向后兼容性validate_assignmentTrue赋值时重新校验类型populate_by_nameTrue与arbitrary_types_allowedTrue兼容按字段名构造与自定义类型use_enum_valuesTrue枚举字段序列化为原始值。SwitchInlineQueryChosenChat本身的__init__由butcher自动生成见源码中TYPE_CHECKING代码块仅用于 IDE 类型提示运行时的构造与校验完全由 Pydantic 完成。因此在 aiogram 中你可以直接以关键字参数方式实例化from aiogram.types import SwitchInlineQueryChosenChat chosen_chat SwitchInlineQueryChosenChat( queryshare, allow_user_chatsTrue, allow_group_chatsTrue, )所有字段默认值为None构造时可以只指定需要的开关未指定的类型自动不可选。在按钮类型中的接入位置SwitchInlineQueryChosenChat本身不会直接出现在消息里它必须作为按钮的属性被 Telegram 解析。在 aiogram 中它被接入两个按钮类InlineKeyboardButton 的switch_inline_query_chosen_chat: SwitchInlineQueryChosenChat | None字段第 41 行RichMessageButton 的switch_inline_query_chosen_chat: SwitchInlineQueryChosenChat | None字段第 39 行。按钮类中同时存在url、callback_data、web_app、switch_inline_query等互斥字段构造时除text外必须且只能指定一种按钮行为类型switch_inline_query_chosen_chat即是其中一种行为。实战一直接构造 InlineKeyboardMarkup最直接的方式是把SwitchInlineQueryChosenChat嵌套进 InlineKeyboardButton 和 InlineKeyboardMarkup 中再通过reply_markup参数随消息发送import asyncio from aiogram import Bot from aiogram.types import ( InlineKeyboardButton, InlineKeyboardMarkup, SwitchInlineQueryChosenChat, ) API_TOKEN YOUR_BOT_TOKEN async def main() - None: bot Bot(API_TOKEN) # 只允许选择群组/超级群组并附带默认查询 help markup InlineKeyboardMarkup( inline_keyboard[ [ InlineKeyboardButton( text在群组中使用本机器人, switch_inline_query_chosen_chatSwitchInlineQueryChosenChat( queryhelp, allow_group_chatsTrue, ), ), InlineKeyboardButton( text私聊使用, switch_inline_query_chosen_chatSwitchInlineQueryChosenChat( allow_user_chatsTrue, ), ), ], ], ) await bot.send_message( chat_idCHAT_ID, text点击下方按钮选择目标聊天并直接使用内联模式, reply_markupmarkup, ) asyncio.run(main())InlineKeyboardMarkup.inline_keyboard的类型为list[list[InlineKeyboardButton]]即每行是一个按钮列表多个按钮放在同一行会自动横向排布。实战二使用 InlineKeyboardBuilder 构建对于动态构造或需要分行的键盘aiogram 提供了 InlineKeyboardBuilder其button()方法直接接受switch_inline_query_chosen_chat关键字参数见 keyboard.py 第 314 行并最终通过_button()内部方法构造出InlineKeyboardButton实例keyboard.py 第 242-252 行from aiogram.types import SwitchInlineQueryChosenChat from aiogram.utils.keyboard import InlineKeyboardBuilder builder InlineKeyboardBuilder() builder.button( text邀请到群组, switch_inline_query_chosen_chatSwitchInlineQueryChosenChat( querystart, allow_group_chatsTrue, ), ) builder.button( text邀请到频道, switch_inline_query_chosen_chatSwitchInlineQueryChosenChat( querystart, allow_channel_chatsTrue, ), ) # 两按钮各占一行 builder.adjust(1) markup builder.as_markup()InlineKeyboardBuilder继承自泛型KeyboardBuilder默认max_width8、max_buttons100可通过adjust()控制每行按钮数通过as_markup()得到最终的InlineKeyboardMarkup。相关的构建器行为在 tests/test_utils/test_keyboard.py 中有系统性的单元测试覆盖包括按钮类型校验、行宽校验与attach合并等。实战三在富媒体消息按钮中使用aiogram 对 Telegram 的富媒体消息RichMessage同样提供了对应类型 RichMessageButton其按钮行为字段与InlineKeyboardButton基本一致也支持switch_inline_query_chosen_chatfrom aiogram.types import ( RichMessageButton, RichTextParagraph, SwitchInlineQueryChosenChat, ) button RichMessageButton( textRichTextParagraph(text在群组中使用), switch_inline_query_chosen_chatSwitchInlineQueryChosenChat( queryhelp, allow_group_chatsTrue, ), )与InlineKeyboardButton不同的是RichMessageButton的text字段类型为RichTextUnion富文本并且当按钮使用stylelink时仅允许作为回调按钮使用内联切换按钮应使用普通样式。使用限制与注意事项根据 InlineKeyboardButton 与 RichMessageButton 字段的文档注释使用switch_inline_query_chosen_chat时需注意不支持频道直聊消息Not supported for messages sent in channel direct messages chats即频道讨论群式的直聊场景下该按钮无效不支持商业账号名义发送的消息...and on behalf of a business account即通过商业账号Business Account发送的消息中不可使用互斥性一个按钮只能声明一种行为switch_inline_query_chosen_chat与url、callback_data、switch_inline_query等字段不能同时设置类型白名单语义四个allow_*字段默认均为None需要显式设置True才会允许对应类型的聊天出现在选择器中query内容约束query是在目标聊天输入框中预填的内联查询文本应与你的 InlineQuery 处理逻辑中定义的命令格式保持一致否则用户回车后可能得不到预期结果。测试与验证仓库中虽然没有针对SwitchInlineQueryChosenChat的独立测试文件但按钮与键盘的整体行为已有测试覆盖tests/test_utils/test_keyboard.py验证InlineKeyboardBuilder的按钮类型校验、行宽上限、attach合并与as_markup输出tests/test_api/test_types/test_message.py验证消息的reply_markup与edit_reply_markup场景下键盘的构造与传递如第 1617-1650 行的test_edit_reply_markup。你可以参照这些测试的模式为自己组合出的SwitchInlineQueryChosenChat场景编写端到端验证。小结SwitchInlineQueryChosenChat是 aiogram 中把内联模式切换从任意聊天收敛到指定聊天类型的标准工具。它的核心在于 5 个可选字段的组合query决定预填查询内容四个allow_*开关决定可选聊天类型。在 InlineKeyboardButton 或 RichMessageButton 上直接嵌套该对象或通过 InlineKeyboardBuilder 的button(switch_inline_query_chosen_chat...)便捷构造即可在私聊、群组、频道等不同会话形态间实现精准的定向引流与功能唤起。赞分享后端即时通讯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 中 getChatGifts 方法详解查询聊天礼物与 OwnedGifts 类型体系aiogram 中 getChatGifts 方法详解查询聊天礼物与 OwnedGifts 类型体系 本文围绕 aiogram 的 get_chat_gift后端即时通讯API设计Micro框架HTTP响应内容协商Accept头与格式选择终极指南Micro框架HTTP响应内容协商Accept头与格式选择终极指南 在现代Web开发中内容协商是构建灵活API的关键技术。Micro框架通过智能的HTTP响后端即时通讯API设计k-skill lotto-results:第三方商标在查询型技能中的合规使用边界与实现佐证k skill lotto results:第三方商标在查询型技能中的合规使用边界与实现佐证 本文围绕 lotto results 技能的商标法律声明 http后端即时通讯API设计上一篇ComfyUI-Manager多通道优先级设置节点源选择策略下一篇CircuitJS1桌面版专业电路仿真的完整离线解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考