Telegram Bot API

Telegram Widgets: Interactive HTML Inside Bot Messages

· 8 min read

Telegram widgets are small interactive HTML blocks that a bot sends inside a message with the sendWidget method, added in Bot API 10.4 on November 9, 2026. A widget is one HTML document of up to 32 KB that the Telegram app runs on the user's device, without any network access, and draws in the chat's own style: an order card that updates its status, a counter, a poll whose bars move as people vote, a promo code copied with one tap.

Where widgets work today: in the production environment a bot can send widgets only to the private chat with a user, and the messages are sent with protected content, so they can't be forwarded. Widgets in groups, in inline mode and in forwards work only on the test server for now.

What a Telegram widget is

Code and state: chat_data and public_data

A widget is fixed code plus changeable state. The HTML is set when the widget is sent and never changes: no method replaces it. What changes is the state, and only the bot writes it. The widget reads it as TelegramWidget.chatData and TelegramWidget.publicData and redraws on the chatDataChanged and publicDataChanged events.

PropertyChat state (chat_data)Shared state (public_data)
Tied toOne original messageThe message of a static widget, or a shared widget everywhere it is shown
SeenOnly in that chat (one for all members in a group)Wherever the widget is shown
In a forwardNeverA copy (static widget) or the live shared state (shared widget)
SizeUp to 1024 bytes of textUp to 1024 bytes of text
Changed witheditMessageWidgetDataeditMessageWidgetData or editSharedWidgetData
ExamplesA game in progress, an order statusPoll results, a price

Both are plain text that the server does not interpret, usually JSON. In the widget, an absent or cleared state is null.

Where widgets live: production vs test server

PlaceHow it gets thereRequests (with allow_queries)Production
Private chat with the botsendWidget, sendSharedWidgetOn a tap and in the backgroundYes
Basic group or supergroupsendWidgetOn a tap onlyTest server only
Any chat except channels, via the botInline mode (InputWidgetMessageContent, InputSharedWidgetMessageContent)On a tap onlyTest server only
A forward, channels includedForwarded by usersOn a tap, shared widgets onlyTest server only

Bots can't post widgets in channels. Apps that don't support widgets show the message as unsupported media with its caption. Widget messages can't be copied with copyMessage or copyMessages, and in groups the can_send_other_messages permission also covers widgets.

Telegram widgets vs Mini Apps

PropertyMini AppWidget
WhereA WebView opened from a button, the menu or a linkInside the message bubble, always visible in the chat
CodeA web page on your serverUp to 32 KB of HTML inside the message, fixed once sent
EngineThe platform's WebViewQuickJS sandbox, drawn by the Telegram app
NetworkThe webNone
Talking to the botYour backend, with signed initDataTelegramWidget.request() → widget_query update
InputEverything, keyboard includedTaps and pointer events, no keyboard

Where the APIs overlap, TelegramWidget reuses the names of Telegram.WebApp (themeParams, colorScheme, onEvent, openLink, HapticFeedback, ready). For anything bigger than a widget, open your bot or Mini App with openTelegramLink. If you are building a Mini App instead, see how to test a Telegram Mini App.

Send your first widget with sendWidget

  1. Create a bot and copy its token (how to create a Telegram bot, where to find the bot token).
  2. Send /start to the bot so it can write to you, and take your chat id from getUpdates.
  3. Call sendWidget. The html parameter is a string, so send the request as JSON:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendWidget" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "html": "<h3>Your promo code</h3><p>Tap the button to copy it.</p><button onclick=\"TelegramWidget.copyText(this.textContent)\">PROMO10</button>",
    "caption": "Your promo code: PROMO10"
  }'

The same in Python with requests or in JavaScript with fetch:

import requests

API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
html = """<h3>Your promo code</h3>
<p>Tap the button to copy it.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>"""

r = requests.post(f"{API}/sendWidget", json={
    "chat_id": 123456789,
    "html": html,
    "caption": "Your promo code: PROMO10",
}, timeout=10)
print(r.json())  # result: the sent Message with its "widget" field
const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const html = `<h3>Your promo code</h3>
<p>Tap the button to copy it.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>`;

const r = await fetch(`${API}/sendWidget`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    chat_id: 123456789,
    html,
    caption: "Your promo code: PROMO10",
  }),
  signal: AbortSignal.timeout(10_000),
});
console.log(await r.json()); // result: the sent Message with its "widget" field

This widget has no CSS at all and still looks like a normal message with a native button. TelegramWidget exists without any script tag, and copyText works because it is called in the handler of a tap. You can also paste the HTML into the sendWidget form of the Bot API Tester and send it with your own token.

Other sendWidget parameters: width and height (size anchors in logical pixels), chat_data and public_data (initial state), allow_queries, is_shared, plus the usual caption, reply_markup, reply_parameters, message_thread_id and protect_content.

How a widget talks to the bot

A request works like a callback button inside the widget:

  1. The bot sends the widget with allow_queries: true.
  2. On a tap, the widget calls TelegramWidget.request("like") with 1–64 bytes of data.
  3. The bot receives a widget_query update with id, from, chat, message_id and data (from a forward of a shared widget: a shared_widget_query). If you pass allowed_updates, include both types.
  4. The bot calls answerWidgetQuery within 15 seconds, optionally with data of up to 1024 bytes that only the asking widget receives.
  5. To change what everyone sees, the bot calls editMessageWidgetData (or editSharedWidgetData); the widget gets chatDataChanged / publicDataChanged.

The answer itself never changes the state. Requests are limited to 5 per 5 seconds per user and bot; a missed answer ends as TIMEOUT in the widget. Full working code is in Telegram widget examples.

Static and shared widgets

Without is_shared a widget is static: code and state live in the message, and a forward gets a frozen copy. With is_shared, the first send creates a shared widget: one object with an identifier (widget.id in the returned message) that any number of messages can show. Send it again with sendSharedWidget and change its shared state for all of them at once with editSharedWidgetData, at most once per second. A widget already on screen receives new shared state only after it calls TelegramWidget.watchPublicData(); the app then polls at the widget's refresh period (30 seconds by default, 5–3600 via cache_time).

Telegram widget limits at a glance

WhatLimit
HTML32768 bytes; 4096 bytes after zlib level 9
chat_data, public_data1024 bytes each
Request data / answer data1–64 bytes / up to 1024 bytes
Time to answer a query15 seconds
Requests5 per 5 seconds per user and bot
Bubble size200 px to the bubble's maximum wide, 50–600 px tall; the rest is clipped
Shared widget edits1 per second
Memory / DOM nodes8 MB / 2000 nodes

The complete table, with CPU quotas, timers and storage, is in the TelegramWidget API reference.

Design tips

Not to be confused with website widgets

"Telegram widget" also refers to the older widgets for websites: the Telegram Login Widget, post embeds and the share button. Those are scripts you put on your own site. Bot API 10.4 widgets are something else: HTML that a bot sends into a chat. For login, post embeds and sharing on your site, see our guide to Telegram website widgets. The official widget documentation lives at core.telegram.org/bots/widgets.

Next steps

Frequently asked questions

What are Telegram widgets?

Small interactive blocks drawn inside a bot's message, added in Bot API 10.4 (November 9, 2026). A widget is one self-contained HTML document with inline CSS and JavaScript that the Telegram app runs on the user's device in a sandbox without network access.

Do Telegram widgets work in groups?

Not in production yet. Currently a bot can send widgets in production only to the private chat with a user, and they can't be forwarded. Groups, inline mode and forwards already work on the test server.

How do I send a widget from a bot?

Call sendWidget with chat_id and html (a string, 1–32768 bytes, at most 4096 bytes after zlib level 9 compression), plus an optional caption, chat_data, public_data and allow_queries. The method returns the sent Message with its widget field.

Can a Telegram widget make HTTP requests?

No. fetch, XMLHttpRequest, WebSocket and every other network API throw NetworkDisabledError. The only way out is TelegramWidget.request(), which sends 1–64 bytes to your bot as a widget_query update.

What is the difference between a widget and a Mini App?

A Mini App is a web page you host, opened in a WebView from a button or link, with full network access. A widget lives inside the message bubble, is at most 32 KB of HTML fixed at sending, has no network and talks only to its bot through requests.

Can I change a widget's HTML after sending?

No. The code is fixed once sent; only the state changes. Update chat_data or public_data with editMessageWidgetData or editSharedWidgetData, or send a new widget for a new layout. The caption can be edited with editMessageCaption.

How to Create a Telegram Bot: Step by Step with BotFather and Python

How to create a Telegram bot step by step: register it with @BotFather, get the token, test it with getMe and send a first message with curl or Python.

Telegram Bot API 10.0–10.5: Bot Settings, Widgets, Rich Messages, Ephemeral Messages, Guest Mode and More

What's new in Telegram Bot API 10.0–10.5: setMySettings and BotFullInfo, HTML widgets, rich and ephemeral messages, guest mode, with JSON examples.

Telegram Bot API Limits: Rate Limits, 429 Errors, File Sizes and Message Length

Telegram Bot API rate limits explained: 30 msg/s, 1 msg/s per chat, 20/min in groups, handling 429 retry_after, plus file size and message length limits.

How to Send a Message with the Telegram Bot API (sendMessage)

Telegram Bot API send message guide: sendMessage with curl, Python and JavaScript, HTML and MarkdownV2 formatting, inline buttons and error fixes.

Telegram Bot Token: How to Get It, Find It Again, Check It and Keep It Safe

Telegram bot token guide: get one from @BotFather, find the token of an existing bot, check it with getMe, revoke a leaked token and store it safely.

How to Set Up a Telegram Bot Webhook: setWebhook, Secret Token and Troubleshooting

Set up a Telegram bot webhook: setWebhook URL requirements, secret_token header check, getWebhookInfo debugging, deleteWebhook and fixes for n8n.

How to Get a Telegram Chat ID for a User, Group, Channel or Topic

How to get a Telegram chat ID for a user, group, supergroup, channel or forum topic with getUpdates, plus fixes for an empty result and 409 Conflict.

Telegram Test Server: How to Test a Bot in the Telegram Test Environment

Use the Telegram test server for bots: log in to the test environment, create a test bot, call the Bot API via /test/ and switch our tester to TEST.

Telegram Widgets for Your Website: Login Widget, Post Embed, Discussion and Share Button

Add Telegram to your website: the new Telegram Login (OIDC), the legacy Login Widget with hash check code, post embeds, comments and a share button.

TelegramWidget JavaScript API: Reference, Events, Error Codes and Limits

TelegramWidget JavaScript API reference: properties, request(), events, error codes, CSS variables, widget_query and answerWidgetQuery, plus every limit.

Telegram Widget Examples: Complete HTML and Python Bot Code

Working Telegram widget examples with full code: a static order card, a counter with widget_query requests, a shared live poll and a local preview stub.

How to Test a Telegram Mini App: From Browser Mock to Real Telegram

Test a Telegram Mini App step by step: browser mock mode, localhost via HTTPS tunnel, test environment, DevTools per platform, initData validation.