Telegram 上的小程序

电报Telegram 上的交互式HTML5 小程序可以完全取代任何网站。它们支持无缝授权、通过多个支付提供商集成支付（开箱即用Google Pay和Apple Pay ）、向用户提供定制推送通知等等。

本文概述了使用 MTProto API 实现机器人小程序客户端的情况：有关小程序端 JS API 的概述，请参阅此处 »。

主要小程序

模式：

user#20b1422 flags:# self:flags.10?true contact:flags.11?true mutual_contact:flags.12?true deleted:flags.13?true bot:flags.14?true bot_chat_history:flags.15?true bot_nochats:flags.16?true verified:flags.17?true restricted:flags.18?true min:flags.20?true bot_inline_geo:flags.21?true support:flags.23?true scam:flags.24?true apply_min_photo:flags.25?true fake:flags.26?true bot_attach_menu:flags.27?true premium:flags.28?true attach_menu_enabled:flags.29?true flags2:# bot_can_edit:flags2.1?true close_friend:flags2.2?true stories_hidden:flags2.3?true stories_unavailable:flags2.4?true contact_require_premium:flags2.10?true bot_business:flags2.11?true bot_has_main_app:flags2.13?true id:long access_hash:flags.0?long first_name:flags.1?string last_name:flags.2?string username:flags.3?string phone:flags.4?string photo:flags.5?UserProfilePhoto status:flags.6?UserStatus bot_info_version:flags.14?int restriction_reason:flags.18?Vector<RestrictionReason> bot_inline_placeholder:flags.19?string lang_code:flags.22?string emoji_status:flags.30?EmojiStatus usernames:flags2.0?Vector<Username> stories_max_id:flags2.5?int color:flags2.8?PeerColor profile_color:flags2.9?PeerColor bot_active_users:flags2.12?int bot_verification_icon:flags2.14?long send_paid_messages_stars:flags2.15?long = User;webViewResultUrl#4d22ff98 flags:# fullsize:flags.1?true fullscreen:flags.2?true query_id:flags.0?long url:string = WebViewResult;botAppSettings#c99b1950 flags:# placeholder_path:flags.0?bytes background_color:flags.1?int background_dark_color:flags.2?int header_color:flags.3?int header_dark_color:flags.4?int = BotAppSettings; botInfo#4d8a0299 flags:# has_preview_medias:flags.6?true user_id:flags.0?long description:flags.1?string description_photo:flags.4?Photo description_document:flags.5?Document commands:flags.2?Vector<BotCommand> menu_button:flags.3?BotMenuButton privacy_policy_url:flags.7?string app_settings:flags.8?BotAppSettings verifier_settings:flags.9?BotVerifierSettings = BotInfo;---functions---messages.requestMainWebView#c9e01e7b flags:# compact:flags.7?true fullscreen:flags.8?true peer:InputPeer bot:InputUser start_param:flags.1?string theme_params:flags.0?DataJSON platform:string = WebViewResult;

主要小程序通过@botfather进行配置。

启用后，用户标志bot_has_main_app将被设置，并且机器人的个人资料页面上应该会显示“打开应用”按钮。

点击此按钮应该会打开主小程序，通过调用messages.requestMainWebView：无需向该方法传递 URL，因为主小程序 URL 是通过@botfather配置的。

应用程序还可以指定在加载屏幕期间使用的自定义背景、标题颜色和占位符 SVG 徽标，这些内容在botAppSettings构造函数中指定，该构造函数包含在userFull返回的botInfo构造函数中。

调用messages.requestMainWebView并获取webViewResultUrl结果后，客户端应使用返回的webViewResultUrlurl中包含的内容打开 webview。

机器人的个人资料页面还应显示照片和视频列表，预览主小程序提供的功能，有关如何配置和渲染它们的更多信息，请参阅主小程序预览。

主要小程序也会在应用内的迷你应用商店中推出 »。

点击主小程序深度链接时，也应该直接打开主小程序»；如果链接中的参数已设置且等于/ ，则必须设置该方法的compact/标志；链接中可能存在的任何内容也必须传递给该方法。fullscreenmodecompactfullscreenstart_param

主要小程序预览

botInfo#4d8a0299 flags:# has_preview_medias:flags.6?true user_id:flags.0?long description:flags.1?string description_photo:flags.4?Photo description_document:flags.5?Document commands:flags.2?Vector<BotCommand> menu_button:flags.3?BotMenuButton privacy_policy_url:flags.7?string app_settings:flags.8?BotAppSettings verifier_settings:flags.9?BotVerifierSettings = BotInfo;user#20b1422 flags:# self:flags.10?true contact:flags.11?true mutual_contact:flags.12?true deleted:flags.13?true bot:flags.14?true bot_chat_history:flags.15?true bot_nochats:flags.16?true verified:flags.17?true restricted:flags.18?true min:flags.20?true bot_inline_geo:flags.21?true support:flags.23?true scam:flags.24?true apply_min_photo:flags.25?true fake:flags.26?true bot_attach_menu:flags.27?true premium:flags.28?true attach_menu_enabled:flags.29?true flags2:# bot_can_edit:flags2.1?true close_friend:flags2.2?true stories_hidden:flags2.3?true stories_unavailable:flags2.4?true contact_require_premium:flags2.10?true bot_business:flags2.11?true bot_has_main_app:flags2.13?true id:long access_hash:flags.0?long first_name:flags.1?string last_name:flags.2?string username:flags.3?string phone:flags.4?string photo:flags.5?UserProfilePhoto status:flags.6?UserStatus bot_info_version:flags.14?int restriction_reason:flags.18?Vector<RestrictionReason> bot_inline_placeholder:flags.19?string lang_code:flags.22?string emoji_status:flags.30?EmojiStatus usernames:flags2.0?Vector<Username> stories_max_id:flags2.5?int color:flags2.8?PeerColor profile_color:flags2.9?PeerColor bot_active_users:flags2.12?int bot_verification_icon:flags2.14?long send_paid_messages_stars:flags2.15?long = User;botPreviewMedia#23e91ba3 date:int media:MessageMedia = BotPreviewMedia; bots.previewInfo#0ca71d64 media:Vector<BotPreviewMedia> lang_codes:Vector<string> = bots.PreviewInfo;---functions---bots.getPreviewMedias#a2a5594d bot:InputUser = Vector<BotPreviewMedia>;messages.uploadMedia#14967978 flags:# business_connection_id:flags.0?string peer:InputPeer media:InputMedia = MessageMedia;bots.getPreviewInfo#423ab3ad bot:InputUser lang_code:string = bots.PreviewInfo; bots.addPreviewMedia#17aeb75a bot:InputUser lang_code:string media:InputMedia = BotPreviewMedia; bots.editPreviewMedia#8525606f bot:InputUser lang_code:string media:InputMedia new_media:InputMedia = BotPreviewMedia; bots.deletePreviewMedia#2d0135b3 bot:InputUser lang_code:string media:Vector<InputMedia> = Bool; bots.reorderPreviewMedias#b627f3aa bot:InputUser lang_code:string order:Vector<InputMedia> = Bool;

在@botfather中启用主小程序后，机器人可以在其个人资料页面上显示本地化的预览媒体（照片和视频），提供应用程序功能的示例。

如果机器人拥有预览媒体，则会设置botInfo标志（botInfo包含在机器人的userFull文件中）。客户端应在用户打开机器人个人资料页面后调用bots.getPreviewMedias来获取并下载预览媒体。该方法会根据用户语言代码（在首次设置客户端时传递给initConnection的语言代码）自动选择每个预览的正确本地化版本。has_preview_medias

机器人所有者可以通过 API 直接编辑预览媒体。

要检查当前用户是否可以编辑机器人的预览媒体，请确保机器人用户bot_can_edit构造函数的 ` and`标志都已设置。bot_has_main_app

然后，机器人所有者应调用`bots.getPreviewInfo`
来获取之前配置的预览媒体。首次调用该方法时，传递一个空字符串lang_code以获取之前配置的默认预览媒体（如果当前用户语言没有预览，则用作备用方案），以及具有本地化预览的语言列表lang_codes；然后再次调用该方法以获取返回的每个语言的之前配置的预览lang_codes。

（注：理论上，非所有者也可以调用bots.getPreviewInfo，但它的行为始终与bots.getPreviewMediaslang_codes完全相同，无论传递什么参数，都只会返回当前语言的预览和一个空数组，因此请仅在您不是所有者时才lang_code使用bots.getPreviewMedias ）。

然后，使用bots.addPreviewMedia、bots.editPreviewMedia、bots.reorderPreviewMedia、bots.deletePreviewMedia ，像往常一样使用messages.uploadMedia上传媒体，为现有语言和新语言设置备用预览和本地化预览。

如上所述，每种语言都可以有一组不同的预览，这些预览可以独立编辑和重新排序。默认的备用语言的预览为空lang_code。

每个本地化键最多可以添加bot_preview_medias_max »个预览媒体。

键盘按钮小程序

模式：

replyKeyboardMarkup#85dd99d1 flags:# resize:flags.0?true single_use:flags.1?true selective:flags.2?true persistent:flags.4?true rows:Vector<KeyboardButtonRow> placeholder:flags.3?string = ReplyMarkup;keyboardButtonSimpleWebView#a0c0505c text:string url:string = KeyboardButton;messageActionWebViewDataSentMe#47dd8079 text:string data:string = MessageAction; messageActionWebViewDataSent#b4c38cb5 text:string = MessageAction;webViewResultUrl#4d22ff98 flags:# fullsize:flags.1?true fullscreen:flags.2?true query_id:flags.0?long url:string = WebViewResult;---functions---messages.requestSimpleWebView#413a3e73 flags:# from_switch_webview:flags.1?true from_side_menu:flags.2?true compact:flags.7?true fullscreen:flags.8?true bot:InputUser url:flags.3?string start_param:flags.4?string theme_params:flags.0?DataJSON platform:string = WebViewResult;messages.sendWebViewData#dc0242c8 bot:InputUser random_id:long button_text:string data:string = Updates;

当用户点击由replyKeyboardMarkup构造函数标识的回复键盘中包含的keyboardButtonSimpleWebView时，应通过调用messages.requestSimpleWebView并将按钮传递给参数来打开键盘按钮小应用程序。urlurl

调用messages.requestSimpleWebView并获取webViewResultUrl结果后，客户端应该使用返回的webViewResultUrlurl中包含的内容打开 webview。

键盘按钮小程序可以通过 MTProto API 以 JS 事件的方式将数据发送回机器人web_app_data_send»。

当客户端仅从键盘按钮小程序接收到web_app_data_sendJS 事件时，应调用messages.sendWebViewData方法，并传递以下参数：

bot- 机器人 ID
random_id- 使用唯一的随机 ID 来避免多次重复发送同一事件
button_text-用于打开简易迷你应用的keyboardButtonSimpleWebView的文本
datadata- JS 事件字段的内容。

请确保忽略web_app_data_send第一个事件之后发送的所有事件，`messages.sendWebViewData`方法只能调用一次。调用`messages.sendWebViewData`方法后，必须关闭 WebView。

这将为用户生成messageActionWebViewDataSent更新，并为机器人生成messageActionWebViewDataSentMe更新，其中包含事件数据。

内联按钮小程序

模式：

keyboardButtonWebView#13767230 text:string url:string = KeyboardButton;webViewResultUrl#4d22ff98 flags:# fullsize:flags.1?true fullscreen:flags.2?true query_id:flags.0?long url:string = WebViewResult;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;updateWebViewResultSent#1592b79d query_id:long = Update; webViewMessageSent#c94511c flags:# msg_id:flags.0?InputBotInlineMessageID = WebViewMessageSent;---functions---messages.requestWebView#269dc2c1 flags:# from_bot_menu:flags.4?true silent:flags.5?true compact:flags.7?true fullscreen:flags.8?true peer:InputPeer bot:InputUser url:flags.1?string start_param:flags.3?string theme_params:flags.2?DataJSON platform:string reply_to:flags.0?InputReplyTo send_as:flags.13?InputPeer = WebViewResult;messages.prolongWebView#b0d81a83 flags:# silent:flags.5?true peer:InputPeer bot:InputUser query_id:long reply_to:flags.0?InputReplyTo send_as:flags.13?InputPeer = Bool;messages.sendWebViewResultMessage#a4314f5 bot_query_id:string result:InputBotInlineResult = WebViewMessageSent;

内联按钮小程序的工作原理与内联机器人类似 »：它们代表用户向发起查询的聊天窗口发送消息。

当用户点击由replyInlineMarkup构造函数标识的内联键盘中包含的keyboardButtonWebView内联按钮时，应调用messages.requestWebView ，并将keyboardButtonWebView传递给该方法的参数。urlurl

然后，客户端应该使用返回的webViewResultUrlurl中包含的内容打开 webview。

加载 webview 后，直到web_app_close 事件将其关闭之前，用户客户端必须每 60 秒调用messages.prolongWebView：如果方法调用返回QUERY_ID_INVALID，则必须关闭 webview。

打开的 URL 片段参数已经包含有关用户的基本信息和一个参数，该参数由机器人小程序 JS 库query_id公开：然后可以将此参数传递给机器人（例如，在小程序本身中，通过 AJAX 查询或表单提交到托管小程序和机器人的服务器），然后机器人使用该参数调用messages.sendWebViewResultMessage，传递一个InputBotInlineResult构造函数，该构造函数将代表用户自动发送一条消息，消息中可以选择附加媒体，甚至还可以包含内联按钮。query_id

菜单按钮小程序

菜单按钮小程序的工作方式与内联按钮小程序类似 »：它们代表用户向点击机器人菜单按钮 »的聊天窗口发送消息。

菜单按钮小程序可以通过botMenuButton 菜单按钮 »打开：在这种情况下，应该设置messages.requestWebView标志，并且必须将botMenuButton字段传递给方法的参数。from_bot_menuurlurl

除了传递给messages.requestWebView的标志不同（如上所述）之外，整个流程与内联按钮小程序的流程相同。

附件菜单小程序

附件菜单小程序的工作方式与内联按钮小程序类似 »：它们代表用户向打开机器人附件菜单的聊天窗口发送消息 » 。

附件菜单小程序可以从附件菜单项打开» ：在这种情况下，调用messages.requestWebView时不应设置任何特殊标志。

附件菜单小程序也可以通过机器人附件菜单深度链接打开，在这种情况下，start_parameter应该将链接提供给messages.requestWebView。start_param如果存在，并且如果设置了参数且等于/ ，则必须设置compact/标志。fullscreenmodecompactfullscreen

除了传递给messages.requestWebView的标志不同（如上所述）之外，整个流程与内联按钮小程序的流程相同。

内联模式小程序

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;inlineBotWebView#b57295d5 text:string url:string = InlineBotWebView;webViewResultUrl#4d22ff98 flags:# fullsize:flags.1?true fullscreen:flags.2?true query_id:flags.0?long url:string = WebViewResult;---functions---messages.getInlineBotResults#514e999d flags:# bot:InputUser peer:InputPeer geo_point:flags.0?InputGeoPoint query:string offset:string = messages.BotResults;messages.requestSimpleWebView#413a3e73 flags:# from_switch_webview:flags.1?true from_side_menu:flags.2?true compact:flags.7?true fullscreen:flags.8?true bot:InputUser url:flags.3?string start_param:flags.4?string theme_params:flags.0?DataJSON platform:string = WebViewResult;

不要与内联按钮小应用混淆 »。

内联模式小程序可用于通过JS 事件响应用户的内联查询，生成一组自定义的内联结果。web_app_switch_inline_query

可以通过点击messages.botResults中包含的内联结果列表顶部的inlineBotWebView按钮来打开内联模式小程序。该列表由messages.getInlineBotResults返回。switch_webview

将该值传递url给messages.requestSimpleWebView，同时设置该from_switch_webview标志。

调用messages.requestSimpleWebView并获取webViewResultUrl结果后，客户端应该使用返回的webViewResultUrlurl中包含的内容打开 webview。

用户在小程序中完成选择后，应发出一个web_app_switch_inline_queryJS 事件 »，其中包含一个 JSON 对象，该对象具有以下字段：

query- 此内联查询将插入到聊天输入框中，位于机器人用户名之后。
它可以是空字符串，在这种情况下，只会插入机器人用户名，并触发一个空的内联查询。
chat_types- 一个字符串数组，包含users` <string>`bots、`<string>`、` <string>`、`<string>groups`等元素的组合channels。
如果该数组非空，客户端应提示用户选择指定类型的特定聊天，然后打开所选聊天，并在输入字段中插入机器人的用户名和指定的内联查询。
数组值指定用户可以选择的聊天类型。
如果为空，则使用当前聊天。

当收到来自小程序的web_app_switch_inline_queryJS 事件时，客户端应该向同一个机器人发出新的内联查询，使用新指定的参数query，可以在当前聊天中发出，也可以在新选择的聊天中发出，如字段所指定chat_types。

侧边菜单小应用

webViewResultUrl#4d22ff98 flags:# fullsize:flags.1?true fullscreen:flags.2?true query_id:flags.0?long url:string = WebViewResult;---functions---messages.requestSimpleWebView#413a3e73 flags:# from_switch_webview:flags.1?true from_side_menu:flags.2?true compact:flags.7?true fullscreen:flags.8?true bot:InputUser url:flags.3?string start_param:flags.4?string theme_params:flags.0?DataJSON platform:string = WebViewResult;

点击已安装的侧边菜单项 » 即可打开侧边菜单小应用。

此操作必须触发messages.requestSimpleWebView查询，并设置标志：客户端应使用返回的webViewResultUrl中包含的from_side_menu内容打开 webview。url

调用messages.requestSimpleWebView并获取webViewResultUrl结果后，客户端应该使用返回的webViewResultUrlurl中包含的内容打开 webview。

直接链接小程序

模式：

inputBotAppID#a920bd7a id:long access_hash:long = InputBotApp; inputBotAppShortName#908c0407 bot_id:InputUser short_name:string = InputBotApp;botAppNotModified#5da674b7 = BotApp; botApp#95fcd1d6 flags:# id:long access_hash:long short_name:string title:string description:string photo:Photo document:flags.0?Document hash:long = BotApp;messages.botApp#eb50adf5 flags:# inactive:flags.0?true request_write_access:flags.1?true has_settings:flags.2?true app:BotApp = messages.BotApp;webViewResultUrl#4d22ff98 flags:# fullsize:flags.1?true fullscreen:flags.2?true query_id:flags.0?long url:string = WebViewResult;---functions---messages.getBotApp#34fdc5c3 app:InputBotApp hash:long = messages.BotApp;messages.requestAppWebView#53618bce flags:# write_allowed:flags.0?true compact:flags.7?true fullscreen:flags.8?true peer:InputPeer app:InputBotApp start_param:flags.1?string theme_params:flags.2?DataJSON platform:string = WebViewResult;

打开小程序的另一种方法是使用小程序直接链接 »。

这些链接与其他所有小程序链接不同，因为它们不需要用户安装附件菜单，而且一个机器人可以提供多个小程序，这些小程序通过它们的short_name.

这些链接应按以下方式处理：

检查bot_username链接参数是否确实是机器人用户名，如果是，则
调用messages.getBotApp，并将inputBotAppShortName传递给short_name查询appname字符串参数。如果客户端之前已经遇到过来自同一机器人的具有此短名称的应用，则将hash缓存的botApp构造函数传递给messages.getBotApp。
如果返回messages.botApp构造函数，则通过调用messages.requestAppWebView打开小程序，从返回的 botApp 生成inputBotAppID构造函数，或者如果我们已经遇到过 bot app 并且返回了botAppNotModified ，则从先前缓存的信息生成 inputBotAppID 构造函数。idaccess_hash
- 如果客户端点击了 Telegram 聊天中的链接，则将聊天中的对等信息传递给peer；否则，则传递机器人的对等信息。
- 如果messages.botApp标志已设置，则request_write_access机器人会请求向用户发送消息的权限：通过提示和复选框向用户请求确认，如果用户同意，则write_allowed在调用messages.requestAppWebView时设置该标志。
- 如果设置了messages.botApp标志，则在打开小程序之前需要用户确认；如有需要，应在此提示中显示复选框。即使未设置该标志，当从无法显示完整链接的位置（例如messageEntityTextUrl文本链接、内联按钮等）打开链接时，也应始终要求用户确认。inactiverequest_write_access
  inactive
  
  如果打开小程序需要确认并且request_write_access已设置，则不要使用两个提示，只需使用一个带有可选复选框的提示即可request_write_access。
- 如果startapp查询字符串参数存在，则start_param在调用messages.requestAppWebView时将其传递给它。

最后，使用返回的webViewResultUrlurl中包含的内容打开 webview。

对外活动：迷你应用程序

小程序可以发送以开头的 Web 事件web_app_；有关小程序可以向客户端发送的事件的完整列表，请参阅 Web 事件文档» 。

即将发生的事件：客户端到小程序

迷你应用也可以通过公开一个方法来接收事件window.Telegram.WebView.receiveEvent("event_name", params)。

如果客户端调用该方法，则小程序可以从客户端接收的事件完整列表如下receiveEvent。

main_button_pressed

参数：null

当用户按下位于 webview 底部的 main 按钮时，客户端会发送此事件；仅当 main 按钮先前已通过web_app_setup_main_button事件 »配置时，才处理此事件。

back_button_pressed

参数：null

当用户按下（操作系统或用户界面）返回按钮时，客户端会发送此消息，前提是之前已通过web_app_setup_back_button事件启用了该功能。

settings_button_pressed

参数：null

当用户按下设置按钮时，客户端会发送此消息（如果之前已通过web_app_setup_settings_button事件启用该按钮）。

invoice_closed

参数：包含以下字段的 JSON 对象：

slug- 发票标识符（字符串）
status- 以下值之一（字符串）：
- cancelled– 用户在调用payments.sendPaymentForm之前关闭了发票弹出窗口而未付款。
- failed– 用户尝试付款，但付款失败：调用payments.sendPaymentForm返回了 RPC 错误，弹出窗口被关闭。
- pending– 付款仍在处理中：机器人将收到关于付款成功的后续服务消息。`payments.sendPaymentForm`已成功调用，并返回了`payments.paymentVerificationNeeded`。用户已完成该方法返回的所有其他验证表单，并且发票弹出窗口已关闭，但客户端尚未收到 `messageActionPaymentSent`服务消息。请注意，如果用户未能通过`payments.paymentVerificationNeeded`返回的额外验证（例如 3-D Secure），则不会将任何错误作为事件发送：状态将保持不变。
  failedpending
- paid– 发票已成功支付：客户完成了付款流程 »，发票弹出窗口已关闭，客户收到了messageActionPaymentSent服务消息。

由客户发送，用于报告从活动中获得的发票的付款状态web_app_open_invoice»。

viewport_changed

参数：一个包含以下字段的 JSON 对象：

height- 小程序可见区域的当前高度（不包括底部主按钮，如果可见）（整数）
is_state_stable- 如果为真，则表示视口当前正在调整大小（动画正在进行中），可能会触发更多此类事件。（布尔值）
is_expanded- 用户向上滑动后或小程序发出web_app_expand事件后，小程序是否展开到最大高度（布尔值）

当视口改变时发出。

theme_changed

参数：一个包含以下字段的 JSON 对象：

theme_params-主题参数对象 »(对象)

当小程序通过web_app_request_theme事件 »请求发出，或者当应用主题更改时发出。

主题参数

Bot 小程序可以根据以下主题参数进行主题化，这些参数以 JSON 对象的形式传递给theme_paramsmessages.requestSimpleWebView、messages.requestWebView和messages.requestAppWebView方法的参数。

此 JSON 对象具有以下键，其中包含要传递给小程序的颜色主题信息（十六进制字符串，RGB，无透明度）。

请点击这里»查看更多关于该物品内容的信息。

popup_closed

参数：一个 JSON 对象，其中包含一个可选的button_id字符串字段。

当用户按下按钮或取消先前web_app_open_popup事件引发的弹出窗口时发出 »。

write_access_requested

参数：一个包含以下字段的 JSON 对象：

status-allowed或者cancelled

客户端用于回复事件web_app_request_write_access»，指示用户是否允许机器人向用户发送消息（allowed）或未（cancelled）。

phone_requested

参数：一个包含以下字段的 JSON 对象：

status-sent或者cancelled

客户端用于回复事件web_app_request_phone»，表明用户是否已与机器人分享其电话号码（allowed）或未分享（cancelled）。

biometry_info_received

参数：一个包含以下字段的 JSON 对象：

available- 布尔值，如果为真，则表示当前设备支持生物识别认证。
type- 可选字符串，如果available为真则设置，包含生物特征认证类型，取值范围为：
- finger- 基于指纹的生物识别技术
- face- 基于面部的生物识别技术
- unknown- 未知类型的生物特征
access_requested- 布尔值，指示应用之前是否通过web_app_biometry_request_access事件请求过使用生物识别技术的权限 »
access_granted- 布尔值，指示用户是否已授予应用在web_app_biometry_request_access事件 »发生时使用生物识别技术的权限。
如果为 false 且access_requested为 true，则表示用户已拒绝应用使用生物识别技术的权限，在这种情况下，应用应弹出提示，通知用户必须更改生物识别设置才能使用生物识别技术；如果用户点击应用内的确认按钮，则必须发出web_app_biometry_open_settings 事件 » 。
token_saved- 布尔值，表示之前的web_app_biometry_update_token 事件是否已将令牌安全地存储在设备上。
device_id- 字符串，一个唯一的设备标识符，可用于将令牌与设备匹配。

供客户回复web_app_biometry_get_info事件 »或web_app_biometry_request_access事件 »。

biometry_token_updated

参数：一个包含以下字段的 JSON 对象：

status- 字符串，以下之一：
- updated- 如果令牌已成功更新。
- removed- 如果令牌已成功移除。
- failed- 如果生物特征认证失败，或者应用程序没有使用生物特征的权限（如果应用程序之前没有使用event »或event »初始化状态，还会发出biometry_info_received 事件 »事件）。web_app_biometry_get_infoweb_app_biometry_request_access

供客户回复事件web_app_biometry_update_token»。

biometry_auth_requested

参数：一个包含以下字段的 JSON 对象：

status- 字符串，可以是authorized或failed。
如果为failed真，则还会发出biometry_info_received 事件 »如果应用程序之前没有使用web_app_biometry_get_info事件 »或web_app_biometry_request_access事件 »初始化状态。
token- 可选字符串，如果status为真则设置，包含先前使用事件»authorized设置的令牌。web_app_biometry_update_token

客户端用于回复web_app_biometry_request_auth生物特征认证请求 »。

custom_method_invoked

参数：一个包含以下字段的 JSON 对象：

req_id来自req_id请求web_app_invoke_custom_method
result- 如果bots.invokeWebViewCustomMethod方法调用成功，则返回该方法响应中包含的 JSON 数据。
error- 如果方法调用失败，则显示 RPC 错误文本

供客户回复web_app_invoke_custom_method事件 »。

clipboard_text_received

参数：一个包含以下字段的 JSON 对象：

req_id来自req_id请求web_app_read_text_from_clipboard
data- 包含剪贴板内容的字符串（可选，如果未提供则视为请求失败）

供客户回复web_app_read_text_from_clipboard事件 »。

qr_text_received

参数：一个包含以下字段的 JSON 对象：

data- 包含已扫描二维码内容的字符串。

如果客户端通过原生二维码扫描器扫描了新的二维码，则发出此消息，该扫描器通过web_app_open_scan_qr_popup事件“»”打开。

scan_qr_popup_closed

参数：null或空对象

如果二维码扫描器弹出窗口因用户关闭或由于权限问题而完全无法打开，则客户端会发出此web_app_open_scan_qr_popup消息。

visibility_changed

参数：一个包含单个is_visible=true|false布尔字段的 JSON 对象。

迷你应用变为活动状态（true）或非活动状态（false），例如，从最小化状态打开/关闭或在标签页中选择/取消选择）。

secondary_button_pressed

参数：null

当用户按下位于 webview 底部的辅助按钮时，客户端会发送此事件。仅当辅助按钮先前已通过web_app_setup_secondary_button事件 »配置时，才处理此事件。

fullscreen_changed

参数：一个包含以下字段的 JSON 对象：

is_fullscreen- 布尔值，指示小程序当前是否处于全屏模式。

由客户端在回复web_app_request_fullscreen和web_app_exit_fullscreen事件时发送。

fullscreen_failed

参数：一个包含以下字段的 JSON 对象：

error- 指示错误的字符串，可以是以下之一：
- UNSUPPORTED此设备或平台不支持全屏模式
- ALREADY_FULLSCREEN- 小程序已处于全屏模式

如果在处理web_app_request_fullscreen和web_app_exit_fullscreen事件时发生故障，则由客户端发送。

accelerometer_started

参数：null

客户端响应web_app_start_accelerometer 事件发送 »如果加速度计跟踪已成功启动。

在小程序发出web_app_stop_accelerometer之前，客户端最多每毫秒也会发出accelerometer_changed 事件，refresh_rate其中包含加速度计读数。

accelerometer_failed

参数：包含以下字段的 JSON 对象：

error- 字符串，以下之一：
- UNSUPPORTED- 此设备或平台不支持加速度计跟踪。

客户端响应web_app_start_accelerometer 事件发送 »如果无法启动加速度计跟踪。

accelerometer_stopped

参数：null

客户端响应web_app_stop_accelerometer 事件发送 »如果加速度计跟踪已成功停止。

accelerometer_changed

参数：JSON 对象x，y包含X、Y 和 Z 轴的当前加速度z字段，以 m/s² 为单位。float

客户端会在调用web_app_start_accelerometer »后每隔几refresh_rate毫秒定期发送一次，直到调用web_app_stop_accelerometer为止。

gyroscope_started

参数：null

客户端响应web_app_start_gyroscope 事件发送 »如果陀螺仪跟踪已成功启动。

在小程序发出web_app_stop_gyroscope之前，客户端最多每毫秒也会发出gyroscope_changed 事件，refresh_rate其中包含陀螺仪读数。

gyroscope_failed

参数：包含以下字段的 JSON 对象：

error- 字符串，以下之一：
- UNSUPPORTED- 此设备或平台不支持陀螺仪跟踪。

客户端响应web_app_start_gyroscope 事件发送 »如果陀螺仪跟踪无法启动。

gyroscope_stopped

参数：null

客户端响应web_app_stop_gyroscope 事件发送 »如果陀螺仪跟踪已成功停止。

gyroscope_changed

参数：JSON 对象x，包含 X、Y 和 Z 轴的当前旋转速率（以 rad/s 为单位）y字段z。float

客户端会在调用web_app_start_gyroscope »后每隔几refresh_rate毫秒定期发送一次，直到调用web_app_stop_gyroscope为止。

device_orientation_started

参数：null

客户端响应web_app_start_device_orientation 事件发送 »如果设备方向跟踪已成功启动。

在小程序发出web_app_stop_device_orientation之前，客户端最多每毫秒也会发出一次 device_orientation 事件，refresh_rate其中包含设备方向读数。

device_orientation_failed

参数：包含以下字段的 JSON 对象：

error- 字符串，以下之一：
- UNSUPPORTED- 此设备或平台不支持设备方向跟踪。

客户端响应web_app_start_device_orientation 事件发送 »如果无法启动设备方向跟踪。

device_orientation_stopped

参数：null

客户端响应web_app_stop_device_orientation 事件发送 »如果设备方向跟踪已成功停止。

device_orientation_changed

参数：包含以下字段的 JSON 对象：

alpha- 绕 Z 轴的旋转角度，以弧度为单位测量。
beta- 绕 X 轴的旋转角度，以弧度为单位测量。
gamma- 绕 Y 轴的旋转角度，以弧度为单位测量。
absolute- 一个布尔值，指示设备是否以绝对值提供方向数据（即使请求了绝对数据，如果且仅当设备/平台不支持绝对方向跟踪时，也可能为 false）。

客户端会在调用web_app_start_device_orientation »后每隔几refresh_rate毫秒定期发送一次，直到调用web_app_stop_device_orientation为止。

home_screen_added

参数：null

客户端响应web_app_add_to_home_screen 事件发送 »如果快捷方式（已）成功添加。

如果当前平台没有办法确定快捷方式的安装状态，则可以不发出此事件。

home_screen_failed

参数：包含以下字段的 JSON 对象：

error- 字符串，以下之一：
- UNSUPPORTED- 此平台不支持快捷方式，或者快捷方式安装失败，或者无法报告状态。

如果无法添加快捷方式，则客户端会响应web_app_add_to_home_screen 事件发送此消息。

如果当前平台没有办法确定快捷方式的安装状态，则可以不发出此事件。

home_screen_checked

参数：包含以下字段的 JSON 对象：

status- 字符串，以下之一：
- unsupported– 该功能不受支持，无法将图标添加到主屏幕。
- unknown– 该功能受支持，可以添加图标，但无法确定图标是否已被添加。
- added– 该图标已添加到主屏幕，
- missed– 该图标尚未添加到主屏幕。

始终由客户端响应web_app_check_home_screen 事件而发送 »。

emoji_status_failed

参数：包含以下字段的 JSON 对象：

error- 字符串，以下之一：
- UNSUPPORTED– 该功能不受客户端支持。
- SUGGESTED_EMOJI_INVALID– 一个或多个表情符号标识符无效。
- DURATION_INVALID– 指定的持续时间无效。
- USER_DECLINED用户关闭了对话框，但未设置状态。
- SERVER_ERROR– 设置状态时发生服务器错误。
- UNKNOWN_ERROR发生未知错误。

如果表情符号状态无法设置，则客户端会响应web_app_set_emoji_status 事件发送此消息。

emoji_status_set

参数：null

客户端响应web_app_set_emoji_status 事件发送 »如果表情符号状态设置成功。

emoji_status_access_requested

参数：包含以下字段的 JSON 对象：

status- 字符串，以下之一：
- allowed用户已授予机器人编辑其表情符号状态的权限
- cancelled用户拒绝了请求，或者发生了错误。

由客户端响应web_app_request_emoji_status_access 事件发送 »。

file_download_requested

参数：一个包含以下字段的 JSON 对象：

status- 要么cancelled（用户中止了下载或 API 不允许下载），要么downloading（下载已成功开始）。

由客户端在小程序文件下载流程期间发出，由web_app_request_file_download »事件发起。

prepared_message_failed

参数：一个包含以下字段的 JSON 对象：

error- 包含messages.getPreparedInlineMessage返回的 RPC 错误文本，或者USER_DECLINED用户中止共享过程，或者MESSAGE_SEND_FAILED由于其他原因发送失败。

当共享准备消息流期间发生错误时，客户端会发出此消息，该消息流由web_app_send_prepared_message »事件发起。

prepared_message_sent

参数：null

当web_app_send_prepared_message »事件启动的共享准备消息流成功完成时，客户端会发出此消息。

safe_area_changed

参数：一个包含以下字段的 JSON 对象：

top- 顶部内边距（以像素为单位），表示屏幕顶部要避开的空间（整数）。
bottom- 底部内缩距（以像素为单位），表示屏幕底部要避开的空间（整数）。
left- 左侧内边距（以像素为单位），表示屏幕左侧要避开的空间（整数）。
right- 以像素为单位的右侧内边距，表示屏幕左侧要避开的空间（整数）。

当系统定义的安全区域内边距值发生任何变化时，或者当小程序使用web_app_request_safe_area明确请求时，客户端会发出此消息。

点击此处»了解更多信息。

content_safe_area_changed

参数：一个包含以下字段的 JSON 对象：

top- 顶部内边距（以像素为单位），表示内容区域顶部要避免的空间（整数）。
bottom- 底部内边距（以像素为单位），表示内容区域底部要避免的空间（整数）。
left- 左侧内边距（以像素为单位），表示内容区域左侧要避免的空间（整数）。
right- 以像素为单位的右侧内边距，表示内容区域左侧要避免的空间（整数）。

当任何内容定义的安全区域内边距值发生变化时，或者当小程序使用web_app_request_content_safe_area明确请求时，客户端会发出此消息。

点击此处»了解更多信息。

location_requested

参数：一个包含以下字段的 JSON 对象：

available- 布尔值，指示位置数据是否可用；如果为 false，则以下字段不得设置。
latitude- 浮点数，包含纬度（度）。
longitude- 浮点数，包含经度（度）。
altitude- 浮点数或空值，包含以米为单位的海拔高度，如果设备或平台不支持，则必须为空值。
course- 浮点数或 null，包含设备移动的方向（以度为单位），如果设备或平台不支持，则必须为 null。
speed- 浮点数或空值，包含设备的速度（单位为米/秒），如果设备或平台不支持，则必须为空值。
horizontal_accuracy- 浮点数或 null，包含以米为单位的纬度和经度值的精度，如果设备或平台不支持，则必须为 null。
vertical_accuracy- 浮点数或 null，包含以米为单位的高度值的精度，如果设备或平台不支持，则必须为 null。
course_accuracy- 浮点数或 null，包含课程值的精度（以度为单位），如果设备或平台不支持，则必须为 null。
speed_accuracy- 浮点数或空值，包含速度值的精度（单位为米/秒），如果设备或平台不支持，则必须为空。

响应web_app_request_location 事件而发出。

location_checked

参数：一个包含以下字段的 JSON 对象：

available- 布尔值，指示当前平台或设备上是否提供位置数据。
access_requested- 可选布尔值，如果为真则必须设置available，指示小程序是否已请求访问位置数据。
access_granted- 可选布尔值，如果设置，则true表示用户已授予小程序访问位置数据的权限。

响应web_app_check_location 事件而发出。

device_storage_key_saved

参数：一个包含以下字段的 JSON 对象：

req_id- 字符串，req_id来自请求的web_app_device_storage_save_key 事件

表示密钥已成功保存或删除。

响应web_app_device_storage_save_key 事件而发出。

device_storage_key_received

参数：一个包含以下字段的 JSON 对象：

req_id- 字符串，req_id来自请求的web_app_device_storage_get_key 事件
value- 字符串或 null，如果指定的键未设置，则为请求的值或无值。

返回请求的密钥。

响应web_app_device_storage_get_key 事件而发出。

device_storage_cleared

参数：一个包含以下字段的 JSON 对象：

req_id- 字符串，req_id来自请求的web_app_device_storage_clear 事件

表示存储空间已清空。

响应web_app_device_storage_clear 事件而发出。

device_storage_failed

参数：一个包含以下字段的 JSON 对象：

req_id- 字符串，req_id来自请求事件
error- 字符串，导致请求失败的错误信息。

响应web_app_device_storage_save_key、web_app_device_storage_get_key或web_app_device_storage_clear事件而发出。

secure_storage_key_saved

参数：一个包含以下字段的 JSON 对象：

req_id- 字符串，req_id来自请求的web_app_secure_storage_save_key 事件

表示密钥已成功保存或删除。

响应web_app_secure_storage_save_key 事件而发出。

secure_storage_key_received

参数：一个包含以下字段的 JSON 对象：

req_id- 字符串，req_id来自请求的web_app_secure_storage_get_key 事件
value- 字符串或 null，如果指定的键未设置，则为请求的值或无值。
can_restore- 布尔值，如果值为空则为 true ，但可以使用web_app_secure_storage_restore_key 事件value恢复该值。

返回请求的密钥。

响应web_app_secure_storage_get_key 事件而发出。

secure_storage_key_restored

参数：一个包含以下字段的 JSON 对象：

req_id- 字符串，req_id来自请求web_app_secure_storage_restore_key 事件
value- 字符串，恢复后的值

恢复所请求的密钥。

响应web_app_secure_storage_restore_key 事件而发出。

secure_storage_cleared

参数：一个包含以下字段的 JSON 对象：

req_id- 字符串，req_id来自请求的web_app_secure_storage_clear 事件

表示存储空间已清空。

响应web_app_secure_storage_clear 事件而发出。

secure_storage_failed

参数：一个包含以下字段的 JSON 对象：

req_id- 字符串，req_id来自请求事件
error- 字符串，表示阻止请求成功的错误；尤其适用UNSUPPORTED于不支持安全存储的平台。

响应web_app_secure_storage_save_key、web_app_secure_storage_get_key、web_app_secure_storage_restore_key或web_app_secure_storage_clear事件而发出。

Telegram 上的小程序

主要小程序

主要小程序预览

键盘按钮小程序

内联按钮小程序

菜单按钮 小程序

附件菜单 小程序

内联模式小程序

侧边菜单小应用

直接链接小程序

对外活动：迷你应用程序

即将发生的事件：客户端到小程序

main_button_pressed

back_button_pressed

settings_button_pressed

invoice_closed

viewport_changed

theme_changed

主题参数

popup_closed

write_access_requested

phone_requested

biometry_info_received

biometry_token_updated

biometry_auth_requested

custom_method_invoked

clipboard_text_received

qr_text_received

scan_qr_popup_closed

visibility_changed

secondary_button_pressed

fullscreen_changed

fullscreen_failed

accelerometer_started

accelerometer_failed

accelerometer_stopped

accelerometer_changed

gyroscope_started

gyroscope_failed

gyroscope_stopped

gyroscope_changed

device_orientation_started

device_orientation_failed

device_orientation_stopped

device_orientation_changed

home_screen_added

home_screen_failed

home_screen_checked

emoji_status_failed

emoji_status_set

emoji_status_access_requested

file_download_requested

prepared_message_failed

prepared_message_sent

safe_area_changed

content_safe_area_changed

location_requested

location_checked

device_storage_key_saved

device_storage_key_received

device_storage_cleared

device_storage_failed

secure_storage_key_saved

secure_storage_key_received

secure_storage_key_restored

secure_storage_cleared

secure_storage_failed

菜单按钮小程序

附件菜单小程序