Widgets do Telegram: blocos HTML interativos dentro das mensagens do bot
Os widgets do Telegram são pequenos blocos HTML interativos que o bot envia dentro de uma mensagem com o método sendWidget, novidade da Bot API 10.4 (9 de novembro de 2026). Um widget é um único documento HTML de até 32 KB que o app do Telegram executa no aparelho do usuário, sem acesso à rede, e desenha no estilo do próprio chat: um card de pedido que atualiza o status, um contador, uma enquete com barras que se mexem a cada voto, um cupom copiado com um toque.
Onde os widgets funcionam hoje: no ambiente de produção, o bot só consegue enviar widgets no chat privado com o usuário, e as mensagens saem com conteúdo protegido, ou seja, não podem ser encaminhadas. Widgets em grupos, no modo inline e em encaminhamentos funcionam, por enquanto, só no servidor de teste.
O que é um widget do Telegram
- Um documento HTML.
<style>e<script>inline, imagens só como URLsdata:ou SVG inline. No máximo 32768 bytes em UTF-8 e 4096 bytes após compressão zlib nível 9. Um fragmento sem<html>e<body>também serve. - Sandbox. O JavaScript roda no QuickJS, um motor JavaScript enxuto, e não numa WebView. O app desenha só o que o perfil de widget permite, então o resultado é igual no iOS, Android, macOS, Desktop e na web.
- Offline.
fetch,XMLHttpRequest,WebSockete outras APIs de rede lançamNetworkDisabledError. Scripts, estilos, fontes e imagens externos nunca são carregados, e não há biblioteca embutida. - Visual nativo. A paleta do chat está disponível nas variáveis CSS
--tg-theme-*, e um<button>sem estilo é desenhado como o botão do próprio app. - Sem teclado. Inputs, selects e textareas são removidos. O widget reage a toques, pointer events, arrastes horizontais e toques longos.
Código e estado: chat_data e public_data
Um widget é código fixo mais estado mutável. O HTML é definido no envio e nunca muda — nenhum método o substitui. O que muda é o estado, e só o bot escreve nele. O widget lê o estado em TelegramWidget.chatData e TelegramWidget.publicData e se redesenha nos eventos chatDataChanged e publicDataChanged.
| Aspecto | Estado do chat (chat_data) | Estado compartilhado (public_data) |
|---|---|---|
| Ligado a | Uma mensagem original | A mensagem de um widget estático, ou o widget compartilhado em todo lugar onde aparece |
| Visível | Só naquele chat (um só para todos os membros de um grupo) | Onde quer que o widget apareça |
| Em encaminhamento | Nunca | Uma cópia (widget estático) ou o estado vivo (widget compartilhado) |
| Tamanho | Até 1024 bytes de texto | Até 1024 bytes de texto |
| Alterado com | editMessageWidgetData | editMessageWidgetData ou editSharedWidgetData |
| Exemplos | Partida em andamento, status do pedido | Resultado de enquete, cotação |
Os dois são texto que o servidor não interpreta (em geral JSON); estado ausente chega como null.
Onde os widgets aparecem: produção x servidor de teste
| Lugar | Como chega lá | Requests (com allow_queries) | Produção |
|---|---|---|---|
| Chat privado com o bot | sendWidget, sendSharedWidget | No toque e em segundo plano | Sim |
| Grupo ou supergrupo | sendWidget | Só no toque | Só no servidor de teste |
| Qualquer chat exceto canais, via bot | Modo inline (InputWidgetMessageContent, InputSharedWidgetMessageContent) | Só no toque | Só no servidor de teste |
| Encaminhamento, inclusive para canais | Encaminhado pelos usuários | No toque, só widgets compartilhados | Só no servidor de teste |
Bots não podem publicar widgets em canais, e apps sem suporte mostram a mensagem como mídia não suportada, com a legenda. Widgets não podem ser copiados com copyMessage, e em grupos a permissão can_send_other_messages também cobre widgets.
Widget do bot Telegram x Mini App
| Aspecto | Mini App | Widget |
|---|---|---|
| Onde fica | WebView aberta por botão, menu ou link | Dentro do balão da mensagem, sempre visível no chat |
| Código | Página web no seu servidor | Até 32 KB de HTML dentro da mensagem, fixo após o envio |
| Motor | A WebView da plataforma | Sandbox QuickJS, desenhado pelo app do Telegram |
| Rede | A web inteira | Nenhuma |
| Conversa com o bot | Seu backend, com initData assinado | TelegramWidget.request() → update widget_query |
| Entrada | Tudo, inclusive teclado | Toques e pointer events, sem teclado |
Onde as APIs se sobrepõem, o TelegramWidget usa os mesmos nomes do Telegram.WebApp (themeParams, onEvent, openLink, HapticFeedback). Para algo maior, abra a Mini App com openTelegramLink — e teste-a no Mini App Tester.
Enviando o primeiro widget com sendWidget
- Crie um bot e copie o token (como criar bot no Telegram, onde pegar o token do bot).
- Mande
/startpara o bot, para que ele possa escrever para você, e pegue o seu chat id nogetUpdates. - Chame sendWidget. O parâmetro
htmlé uma string, então envie a requisição como JSON:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendWidget" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"html": "<h3>Seu cupom</h3><p>Toque no botão para copiar.</p><button onclick=\"TelegramWidget.copyText(this.textContent)\">PROMO10</button>",
"caption": "Seu cupom: PROMO10"
}'
O mesmo em Python com requests ou em JavaScript com fetch:
import requests
API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
html = """<h3>Seu cupom</h3>
<p>Toque no botão para copiar.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>"""
r = requests.post(f"{API}/sendWidget", json={
"chat_id": 123456789,
"html": html,
"caption": "Seu cupom: PROMO10",
}, timeout=10)
print(r.json()) # result: a Message enviada, com o campo "widget"const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const html = `<h3>Seu cupom</h3>
<p>Toque no botão para copiar.</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: "Seu cupom: PROMO10",
}),
signal: AbortSignal.timeout(10_000),
});
console.log(await r.json()); // result: a Message enviada, com o campo "widget"Sem nenhuma linha de CSS, o widget já parece uma mensagem comum com botão nativo; o copyText funciona porque é chamado no handler de um toque. Você também pode colar o HTML no formulário do sendWidget no Bot API Tester e enviar com o seu token.
Outros parâmetros: width e height (âncoras de tamanho), chat_data e public_data (estado inicial), allow_queries, is_shared e os de sempre, como reply_markup e protect_content.
Como o widget conversa com o bot
Um request funciona como um botão de callback dentro do widget:
- O bot envia o widget com
allow_queries: true. - No toque, o widget chama
TelegramWidget.request("like")com 1 a 64 bytes de dados. - O bot recebe um update
widget_querycomid,from,chat,message_idedata(vindo de um encaminhamento de widget compartilhado:shared_widget_query). Se você usaallowed_updates, inclua os dois tipos. - O bot chama answerWidgetQuery em até 15 segundos, opcionalmente com
datade até 1024 bytes, que só o widget que perguntou recebe. - Para mudar o que todo mundo vê, o bot chama editMessageWidgetData (ou
editSharedWidgetData); o widget recebechatDataChanged/publicDataChanged.
A resposta não altera o estado; sem resposta, o widget recebe TIMEOUT. Código completo em exemplos de widget do Telegram.
Widgets estáticos e compartilhados
Sem is_shared, o widget é estático: código e estado ficam na mensagem, e um encaminhamento recebe uma cópia congelada. Com is_shared, o primeiro envio cria um widget compartilhado: um objeto com identificador (widget.id) que várias mensagens exibem. Reenvie com sendSharedWidget e altere o estado de todas de uma vez com editSharedWidgetData (no máximo 1 vez por segundo). Um widget já na tela só recebe o estado novo se chamar TelegramWidget.watchPublicData(); o app consulta a cada 30 segundos por padrão (5–3600 via cache_time).
Limites dos widgets em resumo
| O quê | Limite |
|---|---|
| HTML | 32768 bytes; 4096 bytes após zlib nível 9 |
chat_data, public_data | 1024 bytes cada |
| Dados do request / da resposta | 1–64 bytes / até 1024 bytes |
| Prazo para responder | 15 segundos |
| Requests | 5 a cada 5 segundos por usuário e bot |
| Tamanho do balão | De 200 px até a largura máxima do balão, 50–600 px de altura; o resto é cortado |
| Edições de widget compartilhado | 1 por segundo |
| Memória / nós do DOM | 8 MB / 2000 nós |
A tabela completa, com cotas de CPU, timers e storage, está na referência da API TelegramWidget.
Dicas de design
- Sempre mande legenda. Ela aparece na lista de chats, nas notificações e em apps sem suporte.
- Use o tema. Monte as cores com as variáveis
--tg-theme-*e teste nos temas claro e escuro;prefers-color-schemesegue o tema do chat, não o do sistema. - Mantenha pequeno. Meça o tamanho comprimido como o servidor faz:
python3 -c 'import sys,zlib; print(len(zlib.compress(sys.stdin.buffer.read(), 9)))' < widget.html. - Nada de segredos. Código e estado são, na prática, públicos.
- Layout pela largura com
%, flex ou grid;vhnão existe e nada rola dentro do widget.
Não confunda com os widgets para sites
"Widget do Telegram" também designa os antigos widgets para sites (Login Widget, incorporação de posts, botão de compartilhar): scripts que você coloca no seu site. Os widgets da Bot API 10.4 são HTML que o bot envia para um chat. Para os widgets de site, veja o guia widgets do Telegram para site e login com Telegram. Documentação oficial: core.telegram.org/bots/widgets.
Próximos passos
- Exemplos de widget do Telegram: card de pedido, contador com requests e enquete compartilhada ao vivo, com código do bot em Python.
- API JavaScript TelegramWidget: propriedades, métodos, eventos, códigos de erro, variáveis CSS e limites.
- Referência de métodos da Bot API: todos os métodos novos da 10.4, como
sendWidgeteanswerWidgetQuery.
Perguntas frequentes
O que são os widgets do Telegram?
São pequenos blocos interativos desenhados dentro de uma mensagem do bot, lançados na Bot API 10.4 (9 de novembro de 2026). Cada widget é um único documento HTML com CSS e JavaScript inline, que o app do Telegram executa no aparelho do usuário, num sandbox sem acesso à rede.
Widgets do Telegram funcionam em grupos?
Ainda não em produção. Hoje, no ambiente de produção, o bot só consegue enviar widgets no chat privado com o usuário, e eles não podem ser encaminhados. Grupos, modo inline e encaminhamentos já funcionam no servidor de teste.
Como enviar um widget pelo bot?
Chame sendWidget com chat_id e html (string de 1 a 32768 bytes, no máximo 4096 bytes após compressão zlib nível 9), mais os opcionais caption, chat_data, public_data e allow_queries. O método devolve a Message enviada com o campo widget.
Um widget do Telegram pode fazer requisições HTTP?
Não. fetch, XMLHttpRequest, WebSocket e qualquer outra API de rede lançam NetworkDisabledError. A única saída é TelegramWidget.request(), que manda de 1 a 64 bytes para o bot como update widget_query.
Qual a diferença entre widget e Mini App?
A Mini App é uma página web hospedada por você, aberta numa WebView a partir de um botão ou link, com acesso total à rede. O widget fica dentro do balão da mensagem, tem no máximo 32 KB de HTML fixado no envio, não acessa a rede e só conversa com o bot por meio de requests.
Dá para trocar o HTML de um widget depois de enviado?
Não. O código fica fixo; só o estado muda. Atualize chat_data ou public_data com editMessageWidgetData ou editSharedWidgetData, ou envie um widget novo para um layout novo. A legenda pode ser editada com editMessageCaption.
Guias relacionados
Como criar um bot no Telegram grátis: do BotFather à primeira mensagem
Aprenda a criar bot no Telegram grátis com o @BotFather: pegue o token, teste com getMe e envie a primeira mensagem com curl e Python.
Como enviar mensagens pela API do Telegram com sendMessage (curl, Python e JavaScript)
Use a API do Telegram para enviar mensagens com sendMessage: exemplos em curl, Python e JavaScript, HTML e MarkdownV2, botões inline e erros comuns.
Telegram bot token: como pegar o token do bot, verificar e revogar
Veja como pegar o token do bot do Telegram no @BotFather, achar o token de um bot existente, testar com getMe e revogar um token vazado.
Como configurar o webhook do bot do Telegram: setWebhook, secret_token e n8n
Configure o webhook do bot do Telegram: requisitos de HTTPS e portas, setWebhook com secret_token, getWebhookInfo, deleteWebhook e erros comuns no n8n.
Chat id do Telegram: como pegar o ID de usuário, grupo, canal e tópico com o seu bot
Descubra o chat id do Telegram para o seu bot: getUpdates em chat privado, grupos, supergrupos (-100), canais e tópicos, e o que fazer se vier vazio.
Servidor de teste do Telegram: como testar um bot no ambiente de teste
Use o servidor de teste do Telegram: entre no ambiente de teste, crie um bot de teste, chame a Bot API via /test/ e ative o modo TEST no nosso tester.
Widgets do Telegram para site: login com Telegram, post incorporado, comentários e botão compartilhar
Telegram no seu site: novo login com Telegram (OIDC), Login Widget clássico com checagem do hash, post incorporado, comentários e botão compartilhar.
API JavaScript TelegramWidget: referência, eventos, códigos de erro e limites
Referência da API JavaScript TelegramWidget: propriedades, request(), eventos, códigos de erro, variáveis CSS, widget_query, answerWidgetQuery e limites.
Exemplos de widget do Telegram: HTML completo e bot em Python
Exemplos de widget do Telegram com código completo: card de pedido, contador com widget_query, enquete compartilhada ao vivo e prévia no navegador.