Web events

When interacting with HTML5 games and the websites of payment gateways, Telegram apps should expose APIs to allow receiving data and events from the websites.

Event APIs

Games and payment gateways can generate events that are meant to be received by the Telegram apps.
Typically events are generated by using the postEvent method of the GamingCommunication library.
The postEvent function will try sending the event to the Telegram app in a number of different ways.

WebviewProxy

In mobile apps, the event receiver API should be typically exposed as a window.TelegramWebviewProxy object with a postEvent method.

window.TelegramWebviewProxy.postEvent(eventType, eventData)

window.external

Alternatively, a window.external.notify method can be exposed, accepting a string JSON payload with the event type and payload:

window.external.notify(JSON.stringify({eventType: eventType, eventData: eventData}));

postMessage API

Finally, web MTProto clients that need to open a game or process a payment in an iframe can use the postMessage API to receive events from iframes.
The GamingCommunication library by defaultwill use '*' as targetOrigin, sending messages to parent pages regardless of the origin of the embedder.

window.parent.postMessage(JSON.stringify({eventType: eventType, eventData: eventData}), targetOrigin);

Event types

eventType is a simple string indicating the event type, and eventData is a payload with an object that will be parsed by the Telegram app.

eventType eventData Description
payment_form_submit JSON object with data and title fields title is the censored credit card title.
data is a service-specific JSON payload with information about the payment credentials provided by the user to the payment system.
Neither Telegram, nor bots will have access to your credit card information.
Credit card details will be handled only by the payment system.
share_score null Will be called by games when the user explicitly clicks on the share score button to share the game, along with his score.
Typically done by using messages.forwardMessages on the game message with the with_my_score flag.
share_game null Will be called by games when the user explicitly clicks on the share game button to share the game, without sharing his score.
Typically done by using messages.forwardMessages on the game message without the with_my_score flag, or by sharing the game's short URL.
game_over null Can be called by games when the user loses a game
game_loaded null Can be called by games once the game fully loads
resize_frame JSON object with height field Called by supported pages inside of IV iframe embeds, indicates the new size of the embed frame.