Telegram has officially launched Widgets — interactive blocks that bots can embed directly in messages. The update arrived on November 9, 2026, alongside Bot API 10.4. Users can now interact with polls, mini-games, and other interface elements without opening a separate Mini App or browser.
The new format also supports requests for TON transactions through the built-in wallet. For bot developers, marketers, and performance teams, this makes it possible to create short interactive experiences directly in chats. However, a full rollout across all message types has not happened yet: in production, widgets currently work only in private chats with bots.
Key Takeaways
- On November 9, Telegram Bot API 10.4 introduced the sendWidget method for sending interactive HTML messages.
- A widget can contain up to 32 KB of HTML, CSS, and JavaScript, but its compressed size must not exceed 4 KB.
- Widgets run in an isolated QuickJS environment without direct network access.
- Interactive buttons, charts, polls, games, and requests to bots are supported.
- TON transactions are possible through the built-in wallet, subject to user confirmation.
- In production, widgets are available only in private chats with bots; groups, forwarding, and inline mode are still limited to the test server.
What Are Telegram Widgets and How Do They Work?
Telegram Widgets are small interactive HTML documents displayed as part of a regular message. Unlike a button that launches a web app, a widget displays its interface immediately in the chat feed.
Widget code can include HTML markup, CSS styles, and JavaScript. Telegram compresses it before transmission, and the client app renders the interface according to its own security and design rules.
The official documentation provides several examples of use: an interactive vote, a price chart, a board game for two players, or a promo code that can be copied with a tap.
One important detail is that the widget’s code remains unchanged after it is sent. Its state can be updated — for example, voting results or data received from the bot. To change the interface itself, a new widget must be created.
Why the 4 KB Limit Doesn’t Mean a Full Website Inside a Message
Telegram has imposed two size limits on each widget: up to 32,768 bytes for the original HTML document and up to 4,096 bytes after zlib compression. The document includes embedded styles and JavaScript.
This makes it possible to create compact interfaces without loading external resources. At the same time, the format is not intended for running full websites with large libraries, video players, or complex forms.
Widgets run in QuickJS rather than a conventional browser WebView. Telegram prohibits direct network requests via fetch, XMLHttpRequest, and WebSocket. External scripts, styles, fonts, and images are not loaded either.
Not all HTML elements are supported. Standard input, textarea, and select fields, for example, are unavailable. Complex questionnaires or data-entry forms therefore need to be implemented using other methods or moved into a Mini App.
How a Widget Exchanges Data with a Bot
Despite having no direct internet access, interactive messages can communicate with a bot’s server-side logic.
This uses the TelegramWidget.request() method. When a user presses a button, the widget sends a request through Telegram’s infrastructure. The bot receives a widget_query event, processes it on its server, and returns a response.
For example, a user selects an answer in a quiz. The widget passes the choice to the bot, which checks the answer and returns the result. The interface can then display the next stage without opening a new window.
Two types of state are provided for synchronization: chat_data, associated with a specific message in a chat, and public_data, which can be used by multiple instances of a shared widget.
This provides a technical foundation for voting, multiplayer experiences, and widgets with updating data. However, the ability to use such scenarios in groups and forwarded messages is still limited to the test environment.
TON Payments Inside Messages: What’s Supported?
One of the most interesting Telegram Widgets features is integration with the built-in TON wallet. A widget can initiate a cryptocurrency transaction request or a request to sign data using TON Connect formats.
A payment flow involves several stages. The user presses a button, the widget contacts the bot, the bot generates the transaction parameters, and Telegram opens a wallet window showing the amount and recipient.
The transaction requires user confirmation. After it is submitted, the bot must verify the result on the blockchain, including the sender address, recipient address, and amount. A notification that the transaction was sent is not sufficient proof of successful payment.
The wallet API is not always available. It may be absent in older app versions, in countries where the relevant wallet is unsupported, or in modes where the widget is not permitted to send requests.
Telegram therefore does allow TON payments to be initiated from an interactive message. But this is not a universal payment gateway for all goods and payment methods. The transaction itself is confirmed in a separate, secure wallet interface.
Telegram Widgets vs. Mini Apps: What’s the Difference?
Telegram specifically emphasizes that Widgets are not a smaller version of Mini Apps. They are two different tools intended for different interaction scenarios.
- Placement: Widgets appear inside messages, while Mini Apps launch in a separate WebView.
- Size: widgets have a strict code-size limit, while Mini Apps can use full-fledged web interfaces.
- Network: Widgets have no direct internet access, while Mini Apps can communicate with external servers.
- Interaction: widgets support taps, presses and holds, and horizontal gestures, but not standard text input.
- Payments: Widgets have an API for interacting with the TON wallet, while Mini Apps support a broader payment infrastructure.
- Complexity: widgets are suited to short interactive actions, while Mini Apps are designed for catalogs, user dashboards, and multistep services.
UAGEEK previously covered this technology during its testing phase in an article about HTMLBubbles, interactive games, and TON in Telegram. The main change now is the arrival of an official Bot API and developer documentation.
Can Telegram Widgets Be Used for Traffic Arbitrage?
For affiliate marketing, the most interesting opportunity is to move part of the user interaction from an external page directly into a bot message.
For example, instead of a plain text message with a link, a bot can present an interactive offer selector, a short quiz, or a product demonstration. The user takes an action immediately, and the bot receives a signal to trigger the next step in the flow.
Potential use cases include:
- Interactive pre-landing page: a short flow that lets users choose options and proceed to the relevant offer.
- Quizzes and gamification: engaging users through a simple game or sequence of questions.
- Promo codes: displaying a personalized offer with the option to copy a code.
- Product cards: a compact interface with a price, terms, and a button for the next action.
- TON scenarios: requesting a transaction through a supported wallet with user confirmation.
These are potential scenarios, however, not verified advertising campaign results. There is currently insufficient public data to claim that widgets improve CTR, conversion rates, or profitability compared with ordinary messages or Mini Apps.
It is also important that the new Bot API feature does not automatically mean that such blocks are permitted in Telegram Ads. The platform’s ad placements have their own formats and moderation rules.
The Main Limitation: Widgets Still Can’t Be Shared Across All Chats
As of November 13, 2026, Telegram’s official documentation describes a phased rollout of Widgets.
In production, bots can send interactive messages only to users in private chats. These messages are automatically protected from forwarding.
Support for widgets in groups, inline mode, and forwarded messages has already been implemented on the test server, but is not yet available for general use.
This significantly limits the viral distribution of interactive content. For now, you cannot simply create a widget and expect users to forward it widely between groups and channels.
Users with outdated Telegram clients may also see the message as an unsupported media format with a text caption. For commercial use cases, this means an alternative interaction method should be provided.
What Developers and Marketers Should Do
The arrival of the official API already makes it possible to start building and testing widgets. However, it is still too early to move complete sales funnels onto them.
- Check Bot API 10.4 support in your infrastructure and Telegram bot libraries.
- Build a small test widget with buttons, a short quiz, or a promo code.
- Check the HTML and JavaScript restrictions and compressed-code size limits.
- Implement widget_query handling on the bot server and test state updates.
- For TON payments, provide for user confirmation, transaction verification, and error handling.
- Keep an alternative flow using a standard message or Mini App for unsupported clients.
For performance teams, it makes sense to begin by testing individual funnel stages: acquisition, quiz engagement, offer clicks, and completion of the target action. This makes it possible to assess whether a widget actually reduces user drop-off rather than merely adding another interactive element.
What’s Next for Telegram Widgets?
Telegram has moved from HTMLBubbles experiments to a documented tool for bots. Developers can now build compact interfaces that work directly inside messages, exchange data with bots, and support interaction with the TON wallet.
The next important milestone is extending widget availability to groups, inline mode, and forwarding. These features could make the format much more interesting for distributing interactive content.
For now, Telegram Widgets should be viewed as a new tool for bots and short interaction flows, not a full replacement for pre-landing pages or Mini Apps. Their practical value for marketing will depend on further rollout and real-world test results.
Sources for Verification
Sources for Verification
Telegram — Widgets. Official technical documentation covering code size, QuickJS, network restrictions, state handling, the TON wallet, and rollout stages.
Telegram Widgets documentation
Telegram — Bot API. The Bot API 10.4 update of November 9, 2026, the sendWidget and sendSharedWidget methods, and new event types.
Telegram Bot API update history
Telegram — Mini Apps. Official description of the Mini Apps platform, its capabilities, and launch methods for comparison with Widgets.
Telegram Mini Apps documentation
Pavel Durov — post on X. Public announcement about the arrival of interactive applications inside Telegram messages.
Pavel Durov’s original post
UAGEEK — Telegram Tests HTMLBubbles: Games and TON Directly in Chats. An earlier stage in the technology’s development, before the official Bot API became available.
Article about HTMLBubbles testing