<p>When interacting with HTML5 games, websites of payment gateways and <ahref="/api/bots/webapps">bot web apps</a>, Telegram apps should expose APIs to allow receiving data and events from the websites.</p>
<p>Games, payment gateways and <ahref="/api/bots/webapps">bot web 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 <ahref="https://github.com/TelegramMessenger/GamingCommunication/blob/master/games.js">GamingCommunication library</a>, or by the <ahref="/bots/webapps#initializing-web-apps">bot web apps library</a>.<br>
<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>
<p>Finally, web MTProto clients that need to open a game, open a <ahref="/api/bots/webapps">bot web app</a> or process a payment in an iframe can use the <ahref="https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage">postMessage API</a> to receive events from iframes.<br>
The GamingCommunication and bot web 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>
<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>
<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 <ahref="/api/bots/webapps">bot web apps</a> when to open a native pop-up over the webview.</p>
<p>By default, buttons should be displayed on one row.<br>
If the web app provides two buttons that can't fit horizontally on one row, display each button on a separate row.<br>
If the web 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>
<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>
<p>Event data: a JSON object with a string <code>color_key</code>, with of the following values:</p>
<ul>
<li><code>bg_color</code> - The <code>bg_color</code> from the <ahref="/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 <ahref="/api/bots/webapps#theme-parameters">theme parameters</a> should be used.</li>
</ul>
<p>Used to set the web app header and upper overscroll color. </p>
<p>Event data: a JSON object with a string <code>data</code> field. </p>
<p>Used by <ahref="/api/bots/webapps#simple-web-apps">simple webapps</a> to send back data to the bot as specified <ahref="/api/bots/webapps#simple-web-apps">here »</a>. The Web App will be closed. </p>
<p>Event data: a JSON object with a string <code>url</code> field. </p>
<p>Used to open a link in an external browser (or in a new tab for browser clients). The Web App will not be closed. </p>
<p>Note that this method can be called only in response to the user interaction with the Web App interface (e.g. a click inside the Web App or on the main button).<br>
After opening the URL, further events of this type should be ignored until the user interacts again with the Web App interface (as above).<br>
Note that user interactions must have a TTL of 10 seconds: events of this type must be ignored if the last Web App user interaction happened more than 10 seconds ago.</p>
<p>Event data: a JSON object with a string <code>path_full</code> field, containing the path+query component of a <ahref="/api/links">t.me deep link</a> (<code>url = 'https://t.me' + path_full</code>). </p>
<p>Used to open a <ahref="/api/links">t.me deep link</a>. The Web App must be closed.</p>
<p>Event data: a JSON object with a string <code>slug</code> field, containing an <ahref="/api/links#invoice-links">invoice deep link</a>.</p>
<p>Used to initiate <ahref="/api/payments">payment of an invoice »</a>, by opening an invoice popup over the Web App: the Web App itself must not be closed. </p>
<p>The payment status must be reported back to the web app using <ahref="/api/bots/webapps#invoice-closed">invoice_closed</a>.</p>
<p>Used by web apps to request information about the viewport, clients should emit a <ahref="/api/bots/webapps#viewport-changed">viewport_changed event</a>.</p>
<p>Used by web apps to request information about the current theme, clients should emit a <ahref="/api/bots/webapps#theme-changed">theme_changed event</a>.</p>
<p>Emitted by web 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 web 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>
<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 <ahref="/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 <ahref="/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 <ahref="/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 <ahref="/api/bots/attach">attachment menu web apps</a>.<br>
In clients that implements a tab bar, iff the user opens a web app through a tab bar button and the web 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>
<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 <ahref="/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 <ahref="/api/bots/webapps#back-button-pressed"><code>back_button_pressed</code> event</a>, otherwise the webview should be closed.</p>
<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 <ahref="/api/payments">payment documentation for more info »</a>. </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 <ahref="/method/messages.forwardMessages">messages.forwardMessages</a> on the game message with the <code>with_my_score</code> flag. </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 <ahref="/method/messages.forwardMessages">messages.forwardMessages</a> on the game message without the <code>with_my_score</code> flag, or by sharing the game's <ahref="/api/links#game-links">deep link</a>.</p>
<p>Event payload: JSON object with <code>height</code> field.</p>
<p>Called by supported pages inside of <ahref="https://instantview.telegram.org">IV</a> iframe embeds, indicates the new size of the embed frame.</p></div>
