机器人内联查询

用户可以通过聊天窗口中的文本输入框直接与机器人进行内联查询互动。本文将介绍使用 MTProto API 的完整内联机器人流程。

有关使用 HTTP 机器人 API 的简化说明，请参见此处 »。

1. 进行内联查询

messages.botResults#e021f2f6 flags:# gallery:flags.0?true query_id:long next_offset:flags.1?string switch_pm:flags.2?InlineBotSwitchPM switch_webview:flags.3?InlineBotWebView results:Vector<BotInlineResult> cache_time:int users:Vector<User> = messages.BotResults;---functions---messages.getInlineBotResults#514e999d flags:# bot:InputUser peer:InputPeer geo_point:flags.0?InputGeoPoint query:string offset:string = messages.BotResults;

在图形客户端中，当用户以 <command> 开头发送消息时@，客户端应该：

使用缓存的内联机器人最高同行评级来显示常用内联机器人的列表。
如果用户从最近使用的机器人列表中选择一个机器人，或者：
输入完整的用户名，后跟一个空格，如果该用户名解析为有效的机器人，则判定为有效。
调用messages.getInlineBotResults方法，并传入以下参数：
- bot- 机器人同伴
- peer- 用户发起查询的聊天窗口（或对于GIF 搜索和其他对配置中指定的内置机器人的查询，则为 inputPeerEmpty）
- geo_point- 如果机器人需要基于位置的内联结果，则获取用户的当前地理位置（bot_inline_geo机器人用户构造函数的标志将被设置）。
- query- 用户在机器人用户名后输入的内容
- offset- 如果用户滚动浏览超过第一个len(results)结果，并且next_offset设置了字段，则应使用此偏移量重复执行内联查询。

2. 回答内联查询

inputBotInlineMessageMediaAuto#3380c786 flags:# invert_media:flags.3?true message:string entities:flags.1?Vector<MessageEntity> reply_markup:flags.2?ReplyMarkup = InputBotInlineMessage; inputBotInlineMessageText#3dcd7a87 flags:# no_webpage:flags.0?true invert_media:flags.3?true message:string entities:flags.1?Vector<MessageEntity> reply_markup:flags.2?ReplyMarkup = InputBotInlineMessage; inputBotInlineMessageMediaGeo#96929a85 flags:# geo_point:InputGeoPoint heading:flags.0?int period:flags.1?int proximity_notification_radius:flags.3?int reply_markup:flags.2?ReplyMarkup = InputBotInlineMessage; inputBotInlineMessageMediaVenue#417bbf11 flags:# geo_point:InputGeoPoint title:string address:string provider:string venue_id:string venue_type:string reply_markup:flags.2?ReplyMarkup = InputBotInlineMessage; inputBotInlineMessageMediaContact#a6edbffd flags:# phone_number:string first_name:string last_name:string vcard:string reply_markup:flags.2?ReplyMarkup = InputBotInlineMessage; inputBotInlineMessageGame#4b425864 flags:# reply_markup:flags.2?ReplyMarkup = InputBotInlineMessage;inputBotInlineResult#88bf9319 flags:# id:string type:string title:flags.1?string description:flags.2?string url:flags.3?string thumb:flags.4?InputWebDocument content:flags.5?InputWebDocument send_message:InputBotInlineMessage = InputBotInlineResult; inputBotInlineResultPhoto#a8d864a7 id:string type:string photo:InputPhoto send_message:InputBotInlineMessage = InputBotInlineResult; inputBotInlineResultDocument#fff8fdc4 flags:# id:string type:string title:flags.1?string description:flags.2?string document:InputDocument send_message:InputBotInlineMessage = InputBotInlineResult; inputBotInlineResultGame#4fa417f2 id:string short_name:string send_message:InputBotInlineMessage = InputBotInlineResult;updateBotInlineQuery#496f379c flags:# query_id:long user_id:long query:string geo:flags.0?GeoPoint peer_type:flags.1?InlineQueryPeerType offset:string = Update;---functions---messages.setInlineBotResults#bb12a419 flags:# gallery:flags.0?true private:flags.1?true query_id:long results:Vector<InputBotInlineResult> cache_time:int next_offset:flags.2?string switch_pm:flags.3?InlineBotSwitchPM switch_webview:flags.4?InlineBotWebView = Bool;

机器人可以使用messages.setInlineBotResults来响应传入的updateBotInlineQuery更新。就像它的机器人 API 对应方法一样，该方法可用于向用户发送一组内联结果；有关 MTProto 方法参数的更多信息，请参阅构造函数页面 »。

一般来说，该方法接受一个InputBotInlineResult构造函数的向量，选择该构造函数后，会生成一条消息，消息中可以选择性地附加媒体，甚至还可以添加内联按钮。

2.1. 使用预先准备好的内联消息

inlineQueryPeerTypeSameBotPM#3081ed9d = InlineQueryPeerType; inlineQueryPeerTypePM#833c0fac = InlineQueryPeerType; inlineQueryPeerTypeChat#d766c50a = InlineQueryPeerType; inlineQueryPeerTypeMegagroup#5ec4be43 = InlineQueryPeerType; inlineQueryPeerTypeBroadcast#6334ee9a = InlineQueryPeerType; inlineQueryPeerTypeBotPM#e3b2d0c = InlineQueryPeerType;messages.botPreparedInlineMessage#8ecf0511 id:string expire_date:int = messages.BotPreparedInlineMessage;messages.preparedInlineMessage#ff57708d query_id:long result:BotInlineResult peer_types:Vector<InlineQueryPeerType> cache_time:int users:Vector<User> = messages.PreparedInlineMessage;---functions---messages.savePreparedInlineMessage#f21f7f2f flags:# result:InputBotInlineResult user_id:InputUser peer_types:flags.0?Vector<InlineQueryPeerType> = messages.BotPreparedInlineMessage;messages.getPreparedInlineMessage#857ebdb8 bot:InputUser id:string = messages.PreparedInlineMessage;

内联结果也可以由小程序预先生成。

首先，与小程序关联的机器人使用messages.savePreparedInlineMessage保存准备好的消息，指定消息、将使用该消息的用户 ID（即当前正在查看 Web 应用程序的用户）以及可以共享该消息的对等类型。
然后，准备好的内联消息 ID 通过 web_app_send_prepared_message web 事件传递给用户的客户端»。
然后，将该 ID与拥有该 Web 应用的机器人的标识符一起传递给messages.getPreparedInlineMessage
，以获取预先准备好的内联消息。3.1) 如果该方法返回任何 RPC 错误，则发出prepared_message_failed 事件，并将error消息设置为 RPC 错误信息，并中止该进程。3.2
) 如果该方法成功，则向用户显示预览，允许他们选择目标聊天。
如果用户中止该过程，则发出prepared_message_failed 事件，并将error设置为USER_DECLINED。
如果用户选择聊天，则按此处指定的方式发送消息 »。5.1
) 如果发送失败，则发出prepared_message_failed 事件，并将error设置为MESSAGE_SEND_FAILED。5.2
) 如果发送成功，则发出prepared_message_sent 事件。

3. 发送内联查询结果

botInlineMessageMediaAuto#764cf810 flags:# invert_media:flags.3?true message:string entities:flags.1?Vector<MessageEntity> reply_markup:flags.2?ReplyMarkup = BotInlineMessage; botInlineMessageText#8c7f65e2 flags:# no_webpage:flags.0?true invert_media:flags.3?true message:string entities:flags.1?Vector<MessageEntity> reply_markup:flags.2?ReplyMarkup = BotInlineMessage; botInlineMessageMediaGeo#51846fd flags:# geo:GeoPoint heading:flags.0?int period:flags.1?int proximity_notification_radius:flags.3?int reply_markup:flags.2?ReplyMarkup = BotInlineMessage; botInlineMessageMediaVenue#8a86659c flags:# geo:GeoPoint title:string address:string provider:string venue_id:string venue_type:string reply_markup:flags.2?ReplyMarkup = BotInlineMessage; botInlineMessageMediaContact#18d1cdc2 flags:# phone_number:string first_name:string last_name:string vcard:string reply_markup:flags.2?ReplyMarkup = BotInlineMessage;botInlineResult#11965f3a flags:# id:string type:string title:flags.1?string description:flags.2?string url:flags.3?string thumb:flags.4?WebDocument content:flags.5?WebDocument send_message:BotInlineMessage = BotInlineResult; botInlineMediaResult#17db940b flags:# id:string type:string photo:flags.0?Photo document:flags.1?Document title:flags.2?string description:flags.3?string send_message:BotInlineMessage = BotInlineResult;messages.botResults#e021f2f6 flags:# gallery:flags.0?true query_id:long next_offset:flags.1?string switch_pm:flags.2?InlineBotSwitchPM switch_webview:flags.3?InlineBotWebView results:Vector<BotInlineResult> cache_time:int users:Vector<User> = messages.BotResults;---functions---messages.sendInlineBotResult#c0cf7646 flags:# silent:flags.5?true background:flags.6?true clear_draft:flags.7?true hide_via:flags.11?true peer:InputPeer reply_to:flags.0?InputReplyTo random_id:long query_id:long id:string schedule_date:flags.10?int send_as:flags.13?InputPeer quick_reply_shortcut:flags.17?InputQuickReplyShortcut allow_paid_stars:flags.21?long = Updates;

用户客户端应以列表形式显示查询过程中获得的messages.botResults，并确保处理可能出现的机器人超时（以 RPC 错误的形式），方法是直接不显示任何内容。resultsBOT_RESPONSE_TIMEOUT

如果messages.botResults或messages.botResults标志已填充，则应在结果列表顶部显示一个按钮，单击该按钮时，不会将内联结果发送到聊天，而是将用户切换到与机器人的私人聊天（switch_pm）或内联模式小程序（）。switch_webviewswitch_pmswitch_webview

如果用户选择的是BotInlineResult常规results列表中的特定选项，则应调用messages.sendInlineBotResult方法，并传递以下参数：

来自或query_idmessages.botResultsmessages.preparedInlineMessage
所选id结果
peer将所选结果发送到哪里

生成的消息将包含一个via_bot_id字段，用于表明该结果是由生成内联结果的机器人生成的。
图形客户端应在消息标题中显示机器人@username，允许用户点击该机器人，并@username在文本栏中自动插入内容以启动内联查询。

4. 在线反馈

inputBotInlineMessageID#890c3d89 dc_id:int id:long access_hash:long = InputBotInlineMessageID;updateBotInlineSend#12f12a07 flags:# user_id:long query:string geo:flags.0?GeoPoint id:string msg_id:flags.1?InputBotInlineMessageID = Update;

如果启用了反馈收集，当用户选择并发送内联结果时，机器人可能会收到updateBotInlineSend通知。

即使将概率设置为 100%，由于缓存机制，也可能无法报告所有内联结果（请参阅“回答回调查询”cache_time中的参数）。此外，收集反馈信息也可能导致热门机器人出现负载问题，因此在这种情况下，请将概率设置调低。

无论如何，反馈收集应该只用于统计目的，而不是功能性目的。

updateBotInlineSend将包含：

id- 所选结果的 ID
msg_id- 已发送内联消息的 ID
user_id选择该结果的用户的 ID
query用于获取结果的查询字符串
geo- 对于需要基于位置的内联搜索结果的机器人，需要用户的位置信息

5. 编辑已发送的内联消息

updateInlineBotCallbackQuery#691e9052 flags:# query_id:long user_id:long msg_id:InputBotInlineMessageID chat_instance:long data:flags.0?bytes game_short_name:flags.1?string = Update;inputBotInlineMessageID#890c3d89 dc_id:int id:long access_hash:long = InputBotInlineMessageID;---functions---messages.editInlineBotMessage#83557dba flags:# no_webpage:flags.1?true invert_media:flags.16?true id:InputBotInlineMessageID message:flags.11?string media:flags.14?InputMedia reply_markup:flags.2?ReplyMarkup entities:flags.3?Vector<MessageEntity> = Bool;

机器人可以编辑发送的内联消息，例如响应按钮按下回调查询。

只需将updateInlineBotCallbackQuery中指定的inputBotInlineMessageID连同新消息一起传递给messages.editInlineBotMessage，并确保将查询发送到指定的数据中心。inputBotInlineMessageID.dc_id