Telegram Bot API

Widgets do Telegram: blocos HTML interativos dentro das mensagens do bot

· 8 min de leitura

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

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.

AspectoEstado do chat (chat_data)Estado compartilhado (public_data)
Ligado aUma mensagem originalA mensagem de um widget estático, ou o widget compartilhado em todo lugar onde aparece
VisívelSó naquele chat (um só para todos os membros de um grupo)Onde quer que o widget apareça
Em encaminhamentoNuncaUma cópia (widget estático) ou o estado vivo (widget compartilhado)
TamanhoAté 1024 bytes de textoAté 1024 bytes de texto
Alterado comeditMessageWidgetDataeditMessageWidgetData ou editSharedWidgetData
ExemplosPartida em andamento, status do pedidoResultado 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

LugarComo chega láRequests (com allow_queries)Produção
Chat privado com o botsendWidget, sendSharedWidgetNo toque e em segundo planoSim
Grupo ou supergruposendWidgetSó no toqueSó no servidor de teste
Qualquer chat exceto canais, via botModo inline (InputWidgetMessageContent, InputSharedWidgetMessageContent)Só no toqueSó no servidor de teste
Encaminhamento, inclusive para canaisEncaminhado pelos usuáriosNo toque, só widgets compartilhadosSó 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

AspectoMini AppWidget
Onde ficaWebView aberta por botão, menu ou linkDentro do balão da mensagem, sempre visível no chat
CódigoPágina web no seu servidorAté 32 KB de HTML dentro da mensagem, fixo após o envio
MotorA WebView da plataformaSandbox QuickJS, desenhado pelo app do Telegram
RedeA web inteiraNenhuma
Conversa com o botSeu backend, com initData assinadoTelegramWidget.request() → update widget_query
EntradaTudo, inclusive tecladoToques 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

  1. Crie um bot e copie o token (como criar bot no Telegram, onde pegar o token do bot).
  2. Mande /start para o bot, para que ele possa escrever para você, e pegue o seu chat id no getUpdates.
  3. 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:

  1. O bot envia o widget com allow_queries: true.
  2. No toque, o widget chama TelegramWidget.request("like") com 1 a 64 bytes de dados.
  3. O bot recebe um update widget_query com id, from, chat, message_id e data (vindo de um encaminhamento de widget compartilhado: shared_widget_query). Se você usa allowed_updates, inclua os dois tipos.
  4. O bot chama answerWidgetQuery em até 15 segundos, opcionalmente com data de até 1024 bytes, que só o widget que perguntou recebe.
  5. Para mudar o que todo mundo vê, o bot chama editMessageWidgetData (ou editSharedWidgetData); o widget recebe chatDataChanged / 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
HTML32768 bytes; 4096 bytes após zlib nível 9
chat_data, public_data1024 bytes cada
Dados do request / da resposta1–64 bytes / até 1024 bytes
Prazo para responder15 segundos
Requests5 a cada 5 segundos por usuário e bot
Tamanho do balãoDe 200 px até a largura máxima do balão, 50–600 px de altura; o resto é cortado
Edições de widget compartilhado1 por segundo
Memória / nós do DOM8 MB / 2000 nós

A tabela completa, com cotas de CPU, timers e storage, está na referência da API TelegramWidget.

Dicas de design

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

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.

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.