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.
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.
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)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}));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);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. |