mirror of
https://github.com/MarshalX/telegram-crawler.git
synced 2024-11-28 19:23:11 +01:00
356 lines
32 KiB
HTML
356 lines
32 KiB
HTML
<!DOCTYPE html>
|
|
<html class="">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>Web events</title>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta property="description" content="How telegram apps interact with webpages">
|
|
<meta property="og:title" content="Web events">
|
|
<meta property="og:image" content="">
|
|
<meta property="og:description" content="How telegram apps interact with webpages">
|
|
<link rel="icon" type="image/svg+xml" href="/img/website_icon.svg?4">
|
|
<link rel="apple-touch-icon" sizes="180x180" href="/img/apple-touch-icon.png">
|
|
<link rel="icon" type="image/png" sizes="32x32" href="/img/favicon-32x32.png">
|
|
<link rel="icon" type="image/png" sizes="16x16" href="/img/favicon-16x16.png">
|
|
<link rel="alternate icon" href="/img/favicon.ico" type="image/x-icon" />
|
|
<link href="/css/bootstrap.min.css?3" rel="stylesheet">
|
|
|
|
<link href="/css/telegram.css?236" rel="stylesheet" media="screen">
|
|
<style>
|
|
</style>
|
|
</head>
|
|
<body class="preload">
|
|
<div class="dev_page_wrap">
|
|
<div class="dev_page_head navbar navbar-static-top navbar-tg">
|
|
<div class="navbar-inner">
|
|
<div class="container clearfix">
|
|
<ul class="nav navbar-nav navbar-right hidden-xs"><li class="navbar-twitter"><a href="https://twitter.com/telegram" target="_blank" data-track="Follow/Twitter" onclick="trackDlClick(this, event)"><i class="icon icon-twitter"></i><span> Twitter</span></a></li></ul>
|
|
<ul class="nav navbar-nav">
|
|
<li><a href="//telegram.org/">Home</a></li>
|
|
<li class="hidden-xs"><a href="//telegram.org/faq">FAQ</a></li>
|
|
<li class="hidden-xs"><a href="//telegram.org/apps">Apps</a></li>
|
|
<li class="active"><a href="/api">API</a></li>
|
|
<li class=""><a href="/mtproto">Protocol</a></li>
|
|
<li class=""><a href="/schema">Schema</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="container clearfix">
|
|
<div class="dev_page">
|
|
<div id="dev_page_content_wrap" class=" ">
|
|
<div class="dev_page_bread_crumbs"><ul class="breadcrumb clearfix"><li><a href="/api" >API</a></li><i class="icon icon-breadcrumb-divider"></i><li><a href="/api/web-events" >Web events</a></li></ul></div>
|
|
<h1 id="dev_page_title">Web events</h1>
|
|
|
|
<div id="dev_page_content"><!-- scroll_nav -->
|
|
|
|
<p>When interacting with HTML5 games, websites of payment gateways and <a href="/api/bots/webapps">bot mini apps</a>, Telegram apps should expose APIs to allow receiving data and events from the websites.</p>
|
|
<h3><a class="anchor" href="#event-apis" id="event-apis" name="event-apis"><i class="anchor-icon"></i></a>Event APIs</h3>
|
|
<p>Games, payment gateways and <a href="/api/bots/webapps">bot mini apps</a> can generate events that are meant to be received by the Telegram apps.
|
|
Typically events are generated by using the <code>postEvent</code> method of the <a href="https://github.com/TelegramMessenger/GamingCommunication/blob/master/games.js">GamingCommunication library</a>, or by the <a href="/bots/webapps#initializing-mini-apps">bot mini apps library</a>.<br>
|
|
The <code>postEvent</code> function will try sending the event to the Telegram app in a number of different ways.</p>
|
|
<h4><a class="anchor" href="#webviewproxy" id="webviewproxy" name="webviewproxy"><i class="anchor-icon"></i></a>WebviewProxy</h4>
|
|
<p>In mobile apps, the event receiver API should be typically exposed as a <code>window.TelegramWebviewProxy</code> object with a <code>postEvent</code> method.</p>
|
|
<pre><code>window.TelegramWebviewProxy.postEvent(eventType, eventData)</code></pre>
|
|
<h4><a class="anchor" href="#windowexternal" id="windowexternal" name="windowexternal"><i class="anchor-icon"></i></a>window.external</h4>
|
|
<p>Alternatively, a <code>window.external.notify</code> method can be exposed, accepting a string JSON payload with the event type and payload:</p>
|
|
<pre><code>window.external.notify(JSON.stringify({eventType: eventType, eventData: eventData}));</code></pre>
|
|
<h4><a class="anchor" href="#postmessage-api" id="postmessage-api" name="postmessage-api"><i class="anchor-icon"></i></a>postMessage API</h4>
|
|
<p>Finally, web MTProto clients that need to open a game, open a <a href="/api/bots/webapps">bot mini app</a> or process a payment in an iframe can use the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage">postMessage API</a> to receive events from iframes.<br>
|
|
The GamingCommunication and bot mini apps libraries by default will use <code>'*'</code> as <code>targetOrigin</code>, sending messages to parent pages regardless of the origin of the embedder.</p>
|
|
<pre><code>window.parent.postMessage(JSON.stringify({eventType: eventType, eventData: eventData}), targetOrigin);</code></pre>
|
|
<h3><a class="anchor" href="#event-types" id="event-types" name="event-types"><i class="anchor-icon"></i></a>Event types</h3>
|
|
<p><code>eventType</code> is a simple string indicating the event type, and <code>eventData</code> is a payload with an object that will be parsed by the Telegram app.</p>
|
|
<h4><a class="anchor" href="#web-app-close" id="web-app-close" name="web-app-close"><i class="anchor-icon"></i></a><code>web_app_close</code></h4>
|
|
<p>No event payload. </p>
|
|
<p>Emitted by <a href="/api/bots/webapps">bot mini apps</a> when the mini app webview should be closed.</p>
|
|
<h4><a class="anchor" href="#web-app-open-popup" id="web-app-open-popup" name="web-app-open-popup"><i class="anchor-icon"></i></a><code>web_app_open_popup</code></h4>
|
|
<p>Event data: a JSON object with the following fields (which should be properly validated by the client).</p>
|
|
<ul>
|
|
<li><code>title</code> - Title for the popup (optional string, max 64 characters)</li>
|
|
<li><code>message</code> - Message of the popup (string, max 256 characters)</li>
|
|
<li><code>buttons</code> - An array of the following objects (array of 1-3 objects)<ul>
|
|
<li><code>type</code> - Button type (string, one of <code>ok</code>, <code>close</code>, <code>cancel</code>, <code>default</code>, <code>destructive</code> (in this case, the button must be red))</li>
|
|
<li><code>text</code> - Button text (string, optional for <code>ok</code>, <code>close</code> and <code>cancel</code> types)</li>
|
|
<li><code>id</code> - Button ID (unique string)</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>Emitted by <a href="/api/bots/webapps">bot mini apps</a> to open a native pop-up over the webview.</p>
|
|
<p>By default, buttons should be displayed on one row.<br>
|
|
If the mini app provides two buttons that can't fit horizontally on one row, display each button on a separate row.<br>
|
|
If the mini app provides three buttons, always display each button on a separate row. </p>
|
|
<ul>
|
|
<li>If the user presses any of the buttons, call <code>window.Telegram.WebView.receiveEvent("popup_closed", {"button_id": "<button id>"})</code></li>
|
|
<li>If the user cancels the interaction without pressing any of the specified buttons, call <code>window.Telegram.WebView.receiveEvent("popup_closed", {})</code></li>
|
|
</ul>
|
|
<p>Disable handling of this event if a popup is already being displayed, re-enable handling only after the <code>popup_closed</code> response event is emitted.<br>
|
|
While handling is enabled, maximum 3 consecutive valid events of this type can be handled in a timespan of 3 seconds, ignore excess events. </p>
|
|
<h4><a class="anchor" href="#web-app-request-write-access" id="web-app-request-write-access" name="web-app-request-write-access"><i class="anchor-icon"></i></a><code>web_app_request_write_access</code></h4>
|
|
<p>Event data: <code>null</code></p>
|
|
<p>Emitted by <a href="/api/bots/webapps">bot mini apps</a> to ask permission from the user to send them messages. </p>
|
|
<p>Upon receiving this event, clients should first invoke <a href="/method/bots.canSendMessage">bots.canSendMessage</a>, to check whether they have already granted the bot permission to write them in some way. </p>
|
|
<ul>
|
|
<li>If the method returns <a href="/constructor/boolTrue">boolTrue</a>, a <a href="/api/bots/webapps#write-access-requested">write_access_requested event »</a> with <code>{"status": "allowed"}</code> should be sent to the Mini App.</li>
|
|
<li>Otherwise, if the method returns <a href="/constructor/boolFalse">boolFalse</a>, a prompt should be shown to the user, indicating that the bot is asking permission to send messages to them.<br>
|
|
If the user accepts, invoke <a href="/method/bots.allowSendMessage">bots.allowSendMessage</a>, and if the method call succeeds emit a <a href="/api/bots/webapps#write-access-requested">write_access_requested event »</a> with <code>{"status": "allowed"}</code>.<br>
|
|
Otherwise, if the user refuses or the <a href="/method/bots.allowSendMessage">bots.allowSendMessage</a> call fails, emit a <a href="/api/bots/webapps#write-access-requested">write_access_requested event »</a> with <code>{"status": "cancelled"}</code>.</li>
|
|
</ul>
|
|
<h4><a class="anchor" href="#web-app-request-phone" id="web-app-request-phone" name="web-app-request-phone"><i class="anchor-icon"></i></a><code>web_app_request_phone</code></h4>
|
|
<p>Event data: <code>null</code></p>
|
|
<p>Emitted by <a href="/api/bots/webapps">bot mini apps</a> to ask the user to share their phone number as a contact.</p>
|
|
<p>Upon receiving this event, clients should show a prompt to the user, indicating that the bot is asking them to share their phone number (optionally also asking the user to unblock the bot, if it's currently blocked). </p>
|
|
<p>If they accept, the user's phone number should be shared by sending a contact to the bot (unblocking it first, if it's currently blocked by the user); if all RPC queries (to unblock the bot, to send the message) succeed, a <a href="/api/bots/webapps#write-access-requested">phone_requested event »</a> should be sent with <code>{"status": "sent"}</code>. </p>
|
|
<p>If the user refuses or any intermdiate method call fails, a <a href="/api/bots/webapps#write-access-requested">phone_requested event »</a> should be sent with <code>{"status": "cancelled"}</code>. </p>
|
|
<h4><a class="anchor" href="#web-app-invoke-custom-method" id="web-app-invoke-custom-method" name="web-app-invoke-custom-method"><i class="anchor-icon"></i></a><code>web_app_invoke_custom_method</code></h4>
|
|
<p>Event data: a JSON object with the following fields:</p>
|
|
<ul>
|
|
<li><code>req_id</code> - A string with the ID of the current request</li>
|
|
<li><code>method</code> - A string, containing the name of the called custom method</li>
|
|
<li><code>params</code> - An object containing the parameters of the method call</li>
|
|
</ul>
|
|
<p>Emitted by <a href="/api/bots/webapps">bot mini apps</a> to make custom method calls to Telegram's servers on behalf of the user. </p>
|
|
<p>This event should trigger a <a href="/method/bots.invokeWebViewCustomMethod">bots.invokeWebViewCustomMethod</a> request, passing the <code>method</code> to <code>custom_method</code>, and the <code>params</code> to <code>params</code>. </p>
|
|
<p>Upon receiving a reply, a <a href="/api/bots/webapps#custom-method-invoked">custom_method_invoked event »</a> should be emitted, with the following fields:</p>
|
|
<ul>
|
|
<li><code>req_id</code> - The <code>req_id</code> from the <code>web_app_invoke_custom_method</code> object</li>
|
|
<li><code>result</code> - The JSON data contained in the response of the <a href="/method/bots.invokeWebViewCustomMethod">bots.invokeWebViewCustomMethod</a> method, if the method call succeeded</li>
|
|
<li><code>error</code> - The text of the RPC error, if the method call failed</li>
|
|
</ul>
|
|
<h4><a class="anchor" href="#web-app-read-text-from-clipboard" id="web-app-read-text-from-clipboard" name="web-app-read-text-from-clipboard"><i class="anchor-icon"></i></a><code>web_app_read_text_from_clipboard</code></h4>
|
|
<p>Event data: a JSON object with the following fields:</p>
|
|
<ul>
|
|
<li><code>req_id</code> - A string with the ID of the current request</li>
|
|
</ul>
|
|
<p>Emitted by <a href="/api/bots/webapps">bot mini apps</a> to obtain the contents of the system clipboard. </p>
|
|
<p>Only for Mini Apps owned by bots added to the <a href="/api/bots/attach">attachment menu</a>, regardles of how the Mini App itself was launched, this event should trigger a <a href="/api/bots/webapps#clipboard-text-received">clipboard_text_received event »</a> with the following payload: </p>
|
|
<ul>
|
|
<li><code>req_id</code> - The <code>req_id</code> from the <code>web_app_read_text_from_clipboard</code> request</li>
|
|
<li><code>data</code> - A string with the clipboard contents</li>
|
|
</ul>
|
|
<p>Note that this method can be called only in response to a user interaction with the Mini App interface (e.g. a click inside the Mini App or on the main or settings button).<br>
|
|
Note that user interactions must have a TTL of 10 seconds: events of this type must be ignored and a <a href="/api/bots/webapps#clipboard-text-received">clipboard_text_received event »</a> with the correct <code>req_id</code> and no <code>data</code> field must be sent if the last Mini App user interaction (as described above) happened more than 10 seconds ago. </p>
|
|
<p>A <a href="/api/bots/webapps#clipboard-text-received">clipboard_text_received event »</a> with the correct <code>req_id</code> and no <code>data</code> field must also be sent if the bot is not installed in the <a href="/api/bots/attach">attachment menu</a>.</p>
|
|
<h4><a class="anchor" href="#web-app-open-scan-qr-popup" id="web-app-open-scan-qr-popup" name="web-app-open-scan-qr-popup"><i class="anchor-icon"></i></a><code>web_app_open_scan_qr_popup</code></h4>
|
|
<p>Event data: a JSON object with the following fields:</p>
|
|
<ul>
|
|
<li><code>text</code> - Optional string, containing the text to be displayed under the 'Scan QR' heading, 0-64 characters. </li>
|
|
</ul>
|
|
<p>Emitted by <a href="/api/bots/webapps">bot mini apps</a> to prompt the client to open the native QR code scanner and start continuously scanning for QR codes. </p>
|
|
<p>A <a href="/api/bots/webapps#qr-text-received"><code>qr_text_received</code> event »</a> should be emitted every time a new QR code is scanned, until the user closes the popup via the UI or the Mini App closes the popup with a <a href="#web-app-close-scan-qr-popup">web_app_close_scan_qr_popup</a> event.</p>
|
|
<p>Closing the popup should emit a <a href="/api/bots/webapps#scan-qr-popup-closed"><code>scan_qr_popup_closed</code> event »</a>; the same event should be emitted if the scan QR code popup cannot be opened due to permission issues. </p>
|
|
<h4><a class="anchor" href="#web-app-close-scan-qr-popup" id="web-app-close-scan-qr-popup" name="web-app-close-scan-qr-popup"><i class="anchor-icon"></i></a><code>web_app_close_scan_qr_popup</code></h4>
|
|
<p>Event data: <code>null</code></p>
|
|
<p>Emitted by <a href="/api/bots/webapps">bot mini apps</a> to prompt the client to close the native QR code scanner opened using <a href="#web-app-open-scan-qr-popup">web_app_open_scan_qr_popup</a>. </p>
|
|
<p>The <a href="/api/bots/webapps#scan-qr-popup-closed"><code>scan_qr_popup_closed</code> event »</a> event should <em>not</em> be emitted if the QR code popup is closed using this event. </p>
|
|
<h4><a class="anchor" href="#web-app-setup-closing-behavior" id="web-app-setup-closing-behavior" name="web-app-setup-closing-behavior"><i class="anchor-icon"></i></a><code>web_app_setup_closing_behavior</code></h4>
|
|
<p>Event data: a JSON object with a boolean <code>need_confirmation</code>.</p>
|
|
<p>If equal to <code>true</code>, the client should require user confirmation with a "Changes that you made may not be saved." popup with "Cancel"/"Close anyway" buttons before closing the webview, to avoid accidentally aborting a sensitive operation; otherwise no confirmation should be requested. </p>
|
|
<h4><a class="anchor" href="#web-app-set-background-color" id="web-app-set-background-color" name="web-app-set-background-color"><i class="anchor-icon"></i></a><code>web_app_set_background_color</code></h4>
|
|
<p>Event data: a JSON object with a string <code>color</code> with a hex RGB color. </p>
|
|
<p>Used to set the mini app background and lower overscroll color. </p>
|
|
<h4><a class="anchor" href="#web-app-set-header-color" id="web-app-set-header-color" name="web-app-set-header-color"><i class="anchor-icon"></i></a><code>web_app_set_header_color</code></h4>
|
|
<p>Event data: a JSON object with the following fields:</p>
|
|
<ul>
|
|
<li><code>color_key</code> - A string with one of the following values:<ul>
|
|
<li><code>bg_color</code> - The <code>bg_color</code> from the <a href="/api/bots/webapps#theme-parameters">theme parameters</a> should be used.</li>
|
|
<li><code>secondary_bg_color</code> - The <code>secondary_bg_color</code> from the <a href="/api/bots/webapps#theme-parameters">theme parameters</a> should be used.</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>color</code> - A color in hex RGB format (<code>#ffffff</code>).</li>
|
|
</ul>
|
|
<p>The two fields are mutually exclusive, if none of the two fields are provided the default header color is used.</p>
|
|
<p>Used to set the mini app header and upper overscroll color. </p>
|
|
<h4><a class="anchor" href="#web-app-data-send" id="web-app-data-send" name="web-app-data-send"><i class="anchor-icon"></i></a><code>web_app_data_send</code></h4>
|
|
<p>Event data: a JSON object with a string <code>data</code> field. </p>
|
|
<p>Used <strong>only</strong> by <a href="/api/bots/webapps#keyboard-button-mini-apps">keyboard button mini apps</a> to send back data to the bot as specified <a href="/api/bots/webapps#keyboard-button-mini-apps">here »</a>. The Mini App will be closed. </p>
|
|
<h4><a class="anchor" href="#web-app-switch-inline-query" id="web-app-switch-inline-query" name="web-app-switch-inline-query"><i class="anchor-icon"></i></a><code>web_app_switch_inline_query</code></h4>
|
|
<p>Event data: a JSON object with the following keys:</p>
|
|
<ul>
|
|
<li><code>query</code> - The inline query that will be inserted in the chat's input field, after the bot's username.<br>
|
|
May be an empty string, in which case just the bot's username will be inserted, triggering an empty inline query.</li>
|
|
<li><code>chat_types</code> - An array of strings, containing a combination of <code>users</code>, <code>bots</code>, <code>groups</code>, <code>channels</code>.<br>
|
|
If non-empty, the client should prompt the user to choose a specific chat of the specified type(s), then open the chosen chat and inserts the bot's username and the specified inline query in the input field.<br>
|
|
The array values specify which types of chats the user will be able to choose from.<br>
|
|
If empty, the current chat is used. </li>
|
|
</ul>
|
|
<p>Used by <a href="/api/bots/webapps#inline-mode-mini-apps">inline mode mini apps</a> to send back data to the bot as specified <a href="/api/bots/webapps#inline-mode-mini-apps">here »</a>. The Mini App will be closed. </p>
|
|
<h4><a class="anchor" href="#web-app-trigger-haptic-feedback" id="web-app-trigger-haptic-feedback" name="web-app-trigger-haptic-feedback"><i class="anchor-icon"></i></a><code>web_app_trigger_haptic_feedback</code></h4>
|
|
<p>Event data: a JSON object with the following fields:</p>
|
|
<ul>
|
|
<li><code>type</code> - One of the following values (string):<ul>
|
|
<li><code>impact</code> - An impact occurred.</li>
|
|
<li><code>notification</code> - A task or action has succeeded, failed, or produced a warning.</li>
|
|
<li><code>selection_change</code> - The user has changed a selection.</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>impact_style</code> - Only for <code>impact</code> feedbacks, one of the following values (string):<ul>
|
|
<li><code>light</code> - Indicates a collision between small or lightweight UI objects</li>
|
|
<li><code>medium</code> - Indicates a collision between medium-sized or medium-weight UI objects</li>
|
|
<li><code>heavy</code> - Indicates a collision between large or heavyweight UI objects</li>
|
|
<li><code>rigid</code> - Indicates a collision between hard or inflexible UI objects</li>
|
|
<li><code>soft</code> - Indicates a collision between soft or flexible UI objects</li>
|
|
</ul>
|
|
</li>
|
|
<li><code>notification_type</code> - Only for <code>notification</code> feedbacks, one of the folowing values (string):<ul>
|
|
<li><code>error</code> - Indicates that a task or action has failed</li>
|
|
<li><code>success</code> - Indicates that a task or action has completed successfully</li>
|
|
<li><code>warning</code> - Indicates that a task or action produced a warning</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p>Used to trigger haptic feedback for a user interaction in a webapp.</p>
|
|
<h4><a class="anchor" href="#web-app-open-link" id="web-app-open-link" name="web-app-open-link"><i class="anchor-icon"></i></a><code>web_app_open_link</code></h4>
|
|
<p>Event data: a JSON object with the following fields:</p>
|
|
<ul>
|
|
<li><code>url</code> - The URL to open</li>
|
|
<li><code>try_instant_view</code> - Optional boolean, if set, equal to <code>true</code> and the scheme of the URL is either <code>http</code> or <code>https</code>, the link should be opened in <a href="/methods#working-with-instant-view-pages">Instant View mode</a> if possible. </li>
|
|
</ul>
|
|
<p>Used to open a link in an external browser (or in a new tab for browser clients). The Mini App will not be closed. </p>
|
|
<p>Note that this method can be called only in response to a user interaction with the Mini App interface (e.g. a click inside the Mini App or on the main or settings button).<br>
|
|
After opening the URL, further events of this type should be ignored until the user interacts again with the Mini App interface (as above).<br>
|
|
Note that user interactions must have a TTL of 1 second: events of this type must be ignored if the last Mini App user interaction happened more than 1 second ago.</p>
|
|
<h4><a class="anchor" href="#web-app-open-tg-link" id="web-app-open-tg-link" name="web-app-open-tg-link"><i class="anchor-icon"></i></a><code>web_app_open_tg_link</code></h4>
|
|
<p>Event data: a JSON object with a string <code>path_full</code> field, containing the path+query component of a <a href="/api/links">t.me deep link</a> (<code>url = 'https://t.me' + path_full</code>). </p>
|
|
<p>Used to open a <a href="/api/links">t.me deep link</a>. The Mini App must be closed.</p>
|
|
<h4><a class="anchor" href="#web-app-open-invoice" id="web-app-open-invoice" name="web-app-open-invoice"><i class="anchor-icon"></i></a><code>web_app_open_invoice</code></h4>
|
|
<p>Event data: a JSON object with a string <code>slug</code> field, containing an <a href="/api/links#invoice-links">invoice deep link</a>.</p>
|
|
<p>Used to initiate <a href="/api/payments">payment of an invoice »</a>, by opening an invoice popup over the Mini App: the Mini App itself must not be closed. </p>
|
|
<p>The payment status must be reported back to the mini app using <a href="/api/bots/webapps#invoice-closed">invoice_closed</a>.</p>
|
|
<h4><a class="anchor" href="#web-app-expand" id="web-app-expand" name="web-app-expand"><i class="anchor-icon"></i></a><code>web_app_expand</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Expands the mini app to the maximum available height.<br>
|
|
The mini app must also be expanded when the user swipes up on the webview. </p>
|
|
<p>This event must be ignored <em>during</em> a user swipe down, used to reduce the webview.</p>
|
|
<h4><a class="anchor" href="#web-app-request-viewport" id="web-app-request-viewport" name="web-app-request-viewport"><i class="anchor-icon"></i></a><code>web_app_request_viewport</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Used by mini apps to request information about the viewport, clients should emit a <a href="/api/bots/webapps#viewport-changed">viewport_changed event</a>.</p>
|
|
<h4><a class="anchor" href="#web-app-request-theme" id="web-app-request-theme" name="web-app-request-theme"><i class="anchor-icon"></i></a><code>web_app_request_theme</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Used by mini apps to request information about the current theme, clients should emit a <a href="/api/bots/webapps#theme-changed">theme_changed event</a>.</p>
|
|
<h4><a class="anchor" href="#web-app-ready" id="web-app-ready" name="web-app-ready"><i class="anchor-icon"></i></a><code>web_app_ready</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Emitted by mini apps when they are fully loaded, signaling to client apps that the loading spinner placeholder can be removed. </p>
|
|
<p>Note that there is no guarantee that this event will be emitted when the mini app is fully loaded: clients should remove the loading spinner upon receiving this event or when the page finishes loading (native webview/iframe event), whichever event comes first.</p>
|
|
<h4><a class="anchor" href="#web-app-setup-main-button" id="web-app-setup-main-button" name="web-app-setup-main-button"><i class="anchor-icon"></i></a><code>web_app_setup_main_button</code></h4>
|
|
<p>Event payload: JSON object with the following fields:</p>
|
|
<ul>
|
|
<li><code>is_visible</code> - Whether the main button is visible (boolean, false by default)</li>
|
|
<li><code>is_active</code> - Whether the main button is active (boolean, true by default)</li>
|
|
<li><code>text</code> - Button text (string, if <code>trim(text)</code> is empty the button must be hidden)</li>
|
|
<li><code>color</code> - Button color in hex RGB format (string, defaults to the <a href="/api/bots/webapps#theme-parameters"><code>button_color</code> theme parameter</a>)</li>
|
|
<li><code>text_color</code> - Button text color in hex RGB format (string, defaults to the <a href="/api/bots/webapps#theme-parameters"><code>button_text_color</code> theme parameter</a>)</li>
|
|
<li><code>is_progress_visible</code> - Indicates whether the button should display a loading indicator (boolean, false by default)</li>
|
|
</ul>
|
|
<p>Configures the main button, located immediately below the webview: when the user presses it a <a href="/api/bots/webapps#main-button-pressed"><code>main_button_pressed</code> event should be emitted by the client</a>. </p>
|
|
<p>Some clients implement a horizontal media type tab bar located at the bottom of the screen, opened when the user clicks on the attachment menu button: this tab bar contains a horizontal list of buttons used to attach media of a certain type and to open installed <a href="/api/bots/attach">attachment menu mini apps</a>.<br>
|
|
In clients that implements a tab bar, iff the user opens a mini app through a tab bar button and the mini app emits a <code>web_app_setup_main_button</code> with <code>is_visible=true</code>, the main button should be displayed (replacing the tab bar) only after the first tap inside of the webview, to prevent bots from immediately blocking the tab bar. </p>
|
|
<p>Otherwise, the main button can be displayed right away with no user interaction when receiving a <code>web_app_setup_main_button</code> event with <code>is_visible=true</code>. </p>
|
|
<h4><a class="anchor" href="#web-app-setup-back-button" id="web-app-setup-back-button" name="web-app-setup-back-button"><i class="anchor-icon"></i></a><code>web_app_setup_back_button</code></h4>
|
|
<p>Event data: a JSON object with an <code>is_visible</code> boolean field.</p>
|
|
<p>Determines whether to show or hide the back button: when the user presses it a <a href="/api/bots/webapps#back-button-pressed"><code>back_button_pressed</code> event should be emitted by the client</a>.<br>
|
|
Note that on supported platforms, the OS back button can be used instead of a custom back button: in this case, if <code>is_visible</code> is true pressing the OS back button should emit a <a href="/api/bots/webapps#back-button-pressed"><code>back_button_pressed</code> event</a>, otherwise the webview should be closed.</p>
|
|
<h4><a class="anchor" href="#web-app-setup-settings-button" id="web-app-setup-settings-button" name="web-app-setup-settings-button"><i class="anchor-icon"></i></a><code>web_app_setup_settings_button</code></h4>
|
|
<p>Event data: a JSON object with an <code>is_visible</code> boolean field.</p>
|
|
<p>Determines whether to show or hide the settings button: when the user presses it a <a href="/api/bots/webapps#settings-button-pressed"><code>settings_button_pressed</code> event should be emitted by the client</a>. </p>
|
|
<h4><a class="anchor" href="#payment-form-submit" id="payment-form-submit" name="payment-form-submit"><i class="anchor-icon"></i></a><code>payment_form_submit</code></h4>
|
|
<p>Event payload: JSON object with <code>credentials</code> and <code>title</code> fields.</p>
|
|
<ul>
|
|
<li><code>title</code> is the censored credit card title. </li>
|
|
<li><code>credentials</code> is a service-specific JSON object with information about the payment credentials provided by the user to the payment system. </li>
|
|
</ul>
|
|
<p><strong>Neither Telegram, nor bots will have access to your credit card information.</strong><br>
|
|
Credit card details will be handled only by the payment system, see the <a href="/api/payments">payment documentation for more info »</a>. </p>
|
|
<h4><a class="anchor" href="#share-score" id="share-score" name="share-score"><i class="anchor-icon"></i></a><code>share_score</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Will be called by games when the user explicitly clicks on the <strong>share score</strong> button to share the game, along with their score.<br>
|
|
Typically done by using <a href="/method/messages.forwardMessages">messages.forwardMessages</a> on the game message with the <code>with_my_score</code> flag. </p>
|
|
<h4><a class="anchor" href="#share-game" id="share-game" name="share-game"><i class="anchor-icon"></i></a><code>share_game</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Will be called by games when the user explicitly clicks on the <strong>share game</strong> button to share the game, without sharing their score.<br>
|
|
Typically done by using <a href="/method/messages.forwardMessages">messages.forwardMessages</a> on the game message without the <code>with_my_score</code> flag, or by sharing the game's <a href="/api/links#game-links">deep link</a>.</p>
|
|
<h4><a class="anchor" href="#game-over" id="game-over" name="game-over"><i class="anchor-icon"></i></a><code>game_over</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Can be called by games when the user loses a game.</p>
|
|
<h4><a class="anchor" href="#game-loaded" id="game-loaded" name="game-loaded"><i class="anchor-icon"></i></a><code>game_loaded</code></h4>
|
|
<p>No event payload.</p>
|
|
<p>Can be called by games once the game fully loads.</p>
|
|
<h4><a class="anchor" href="#resize-frame" id="resize-frame" name="resize-frame"><i class="anchor-icon"></i></a><code>resize_frame</code></h4>
|
|
<p>Event payload: JSON object with <code>height</code> field.</p>
|
|
<p>Called by supported pages inside of <a href="https://instantview.telegram.org">IV</a> iframe embeds, indicates the new size of the embed frame.</p></div>
|
|
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
<div class="footer_wrap">
|
|
<div class="footer_columns_wrap footer_desktop">
|
|
<div class="footer_column footer_column_telegram">
|
|
<h5>Telegram</h5>
|
|
<div class="footer_telegram_description"></div>
|
|
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
|
|
</div>
|
|
|
|
<div class="footer_column">
|
|
<h5><a href="//telegram.org/faq">About</a></h5>
|
|
<ul>
|
|
<li><a href="//telegram.org/faq">FAQ</a></li>
|
|
<li><a href="//telegram.org/privacy">Privacy</a></li>
|
|
<li><a href="//telegram.org/press">Press</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="footer_column">
|
|
<h5><a href="//telegram.org/apps#mobile-apps">Mobile Apps</a></h5>
|
|
<ul>
|
|
<li><a href="//telegram.org/dl/ios">iPhone/iPad</a></li>
|
|
<li><a href="//telegram.org/android">Android</a></li>
|
|
<li><a href="//telegram.org/dl/web">Mobile Web</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="footer_column">
|
|
<h5><a href="//telegram.org/apps#desktop-apps">Desktop Apps</a></h5>
|
|
<ul>
|
|
<li><a href="//desktop.telegram.org/">PC/Mac/Linux</a></li>
|
|
<li><a href="//macos.telegram.org/">macOS</a></li>
|
|
<li><a href="//telegram.org/dl/web">Web-browser</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="footer_column footer_column_platform">
|
|
<h5><a href="/">Platform</a></h5>
|
|
<ul>
|
|
<li><a href="/api">API</a></li>
|
|
<li><a href="//translations.telegram.org/">Translations</a></li>
|
|
<li><a href="//instantview.telegram.org/">Instant View</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="footer_columns_wrap footer_mobile">
|
|
<div class="footer_column">
|
|
<h5><a href="//telegram.org/faq">About</a></h5>
|
|
</div>
|
|
<div class="footer_column">
|
|
<h5><a href="//telegram.org/blog">Blog</a></h5>
|
|
</div>
|
|
<div class="footer_column">
|
|
<h5><a href="//telegram.org/apps">Apps</a></h5>
|
|
</div>
|
|
<div class="footer_column">
|
|
<h5><a href="/">Platform</a></h5>
|
|
</div>
|
|
<div class="footer_column">
|
|
<h5><a href="//telegram.org/press">Press</a></h5>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<script src="/js/main.js?47"></script>
|
|
<script src="/js/jquery.min.js?1"></script>
|
|
<script src="/js/bootstrap.min.js?1"></script>
|
|
|
|
<script>window.initDevPageNav&&initDevPageNav();
|
|
backToTopInit("Go up");
|
|
removePreloadInit();
|
|
</script>
|
|
</body>
|
|
</html>
|
|
|