Widgets em mensagens do Telegram são mini‑apps feitas em HTML, CSS e JavaScript que vivem direto na bolha de conversa: um jogo, calculadora, enquete ou resposta de bot abrem sem janela separada e sem Mini App. Nos clientes do Telegram eles recebem nomes diferentes – message widgets, HTML bubbles (módulo HTMLBubbles em beta para macOS), bloco tgwidget em rich‑message – mas tratam do mesmo mecanismo. Ele já funciona nas versões beta do Telegram para Android, iOS e macOS, e a lista de espera do construtor de widgets sem código está aberta no @catalogue_app.
Entrar na lista de espera de widgets
O que é um widget em mensagem
Uma mensagem comum exibe texto e mídia. Um widget é um tipo de mídia separado, messageMediaWidget: dentro dele há um documento HTML compactado com seus próprios estilos e scripts, além de tamanho e dois conjuntos de dados. O cliente renderiza o documento na bolha e executa seu JavaScript em sandbox; o widget reage a cliques, anima, guarda estado e responde ao tema do chat.
| Widget em mensagem | Mini App | |
|---|---|---|
| Onde abre | direto no feed do chat | em janela separada sobre o chat |
| Do que é feito | HTML, CSS e JavaScript dentro da mensagem | página web no servidor do desenvolvedor |
| Rede | nenhuma: tudo necessário está na mensagem | há, como em um site |
| Reencaminhar | reencaminha como mensagem, com seu estado | reencaminha um link |
| Comunicação com bot | requisição ao toque, resposta ≤ 1 024 bytes | quaisquer requisições ao seu servidor |
Onde os widgets já funcionam
| Cliente | Build | Estado |
|---|---|---|
| Android, beta | 13.2.0 | widgets são renderizados e JavaScript é executado |
| iOS, beta | 13.2 | widgets em mensagens e ferramentas de teste |
| macOS, beta | 13.1.0 | sandbox, requisições ao bot, cenas 3D em three.js |
| Telegram Desktop | 7.3 | ainda não |
A beta Android é distribuída pelo canal de beta‑testers e por link direto no site do Telegram. O protocolo do cliente nela usa a camada 233, um passo à frente da pública: já inclui tipos para entrega de widget pelo servidor, respostas inline de bots e atualização de dados após envio.
Como o widget funciona no Android
Não há navegador por trás do widget. A marcação é interpretada e desenhada por um renderizador nativo baseado em litehtml, enquanto o JavaScript roda em um interpretador QuickJS em sua própria thread. O DOM para o script é emulado: mudanças são enviadas ao renderizador em lotes, e cada lote passa por um validador antes da pintura. O toque real é decidido por um juiz nativo de gestos, não pelo script – por isso um clique sintético não se passa por dedo de usuário.
Análise detalhada da build está no material sobre as betas Android e iOS.
Como o widget funciona no iOS e macOS
Nas plataformas Apple o documento é renderizado pelo WebKit em um módulo separado WidgetSandbox, isolado da rede por três camadas: política de segurança de conteúdo, lista de regras que bloqueia http, https e ws, e remoção das classes de rede da janela antes da execução do código. Na beta para macOS, junto ao módulo HTMLBubbles, vem a biblioteca three.js, que a mensagem carrega via link interno app:three: cenas 3D são desenhadas pelo renderizador Metal do aplicativo. Como isso aparecia nas primeiras builds pode ser visto no material sobre a beta para macOS.
O que o widget pode fazer
- Layout e animação – flex, gradientes, cantos arredondados,
transform, animações CSS e transitions. - Gráfica – SVG e canvas 2D: caminhos, gradientes, padrões, manipulação de pixels.
- Formulários – campos de texto, listas, sliders, botões, blocos expansíveis.
- Estado –
localStoragepróprio de cada widget, armazenado junto à mensagem: pontuação de jogo e dados inseridos sobrevivem a reinícios do cliente. - Tema – cores do chat chegam via variáveis CSS
--tg-theme-*, e o widget se repinta automaticamente para modo claro ou escuro. - Feedback – vibração via
HapticFeedback, links ao toque, cópia de texto. - Bot – ao tocar, o widget envia ao seu bot até 64 bytes e recebe resposta de até 1 024 bytes; o bot pode atualizar os dados do widget já enviado.
- Observador – o widget sabe quem o abriu (id, nome, Premium) e em qual chat está.
O que o widget não tem e por quê
Não há rede alguma: fetch, XMLHttpRequest, WebSocket e workers são substituídos por stubs. Isso é intencional, não uma falha: o widget não pode revelar o IP do leitor e funciona offline. Dados dinâmicos chegam via bot – requisição ao toque ou atualização da mensagem.
Cota para uma tarefa JavaScript – 500 ms de CPU, memória – 64 MB. Altura da bolha – de 50 a 600 dp no Android e de 24 a 900 pt no iOS. Animações fora da tela são pausadas.
Como ficar dentro da cota
Trabalho pesado é dividido em pedaços menores que 500 ms usando requestAnimationFrame ou setTimeout. Um loop de jogo com passo fixo de física cabe na cota com folga: um runner estilo Geometry Dash completa todo o nível em 3 289 frames usando 30 ms de CPU, até 109 comandos canvas por frame.
O que pode ser feito com widget
- Jogos – arcades em canvas, puzzles, clickers, aventuras textuais, torneios com placar direto no chat.
- Widgets de IA – pergunta ao tocar, resposta do modelo via bot na mesma bolha.
- Calculadoras e conversores – moedas, juros, unidades, divisão de conta entre participantes.
- Enquetes e quizzes – com design próprio, contagem e resultado instantâneo.
- Cards e gráficos – perfil, previsões, estatísticas, gerados a partir dos dados da mensagem.
- Intelligent UI – interface que o bot monta sob demanda: formulário de reserva, escolha de horário, carrinho de compras.
E não só isso: widget é um documento HTML, e tudo que cabe na sandbox pode ser enviado como mensagem.
🎮 Jogos em mensagens – entrar na lista de espera
🤖 Widgets de IA – entrar na lista de espera
🧮 Calculadoras e conversores – entrar na lista de espera
Seu widget sem código
Um widget é uma única mensagem com documento interno, portanto pode ser montado a partir de blocos prontos, sem programar. O construtor de widgets sem código está disponível no @catalogue_app: escolha template de jogo, quiz ou calculadora, personalize textos e cores – e o widget pronto pode ser enviado a qualquer chat. Você pode disparar sua própria instância a partir de um bot criado no mesmo @catalogue_app e compartilhar o template para que outros façam fork.
A lista de espera reúne quem quer criar seu próprio widget: quando os widgets chegarem a todos os apps do Telegram, o @catalogue_app avisará os primeiros inscritos.
🧩 Seu widget sem código – entrar na lista de espera
Um widget‑jogo que já funciona na beta Android do Telegram pode ser enviado com o comando /game no @catalogue_app.
Perguntas
O que são HTML bubbles no Telegram?
É o nome do módulo de widgets na beta do Telegram para macOS: mensagem estruturada em HTML e CSS com JavaScript embutido, que vive direto na bolha do chat. No Android e iOS o mesmo mecanismo é chamado de widgets em mensagens.
Já dá para enviar um widget?
Widgets são renderizados nas betas Android, iOS e macOS. Ainda não há método de envio via Bot API; o protocolo da beta já inclui tipos para entrega de widget pelo servidor e resposta inline de bot.
Como o widget difere de Mini App?
Mini App abre em janela separada e carrega página do servidor; widget vive no feed e traz todo o código dentro da própria mensagem. Widget não tem rede; a comunicação externa ocorre via bot.
Preciso saber programar?
Para escrever um widget do zero – sim, são HTML, CSS e JavaScript. Para montar um a partir de template – não, é isso que o construtor sem código no @catalogue_app oferece.
Quando os widgets chegarão às versões estáveis?
Telegram ainda não anunciou data. O mecanismo já está nas betas das três plataformas, e a beta Android já inclui os tipos de protocolo necessários.
