API JavaScript TelegramWidget: referência, eventos, códigos de erro e limites
A API dos widgets do Telegram é o objeto window.TelegramWidget que todo widget da Bot API 10.4 recebe do app, mais o lado do bot: updates widget_query e o método answerWidgetQuery. Esta referência lista propriedades, métodos, eventos e códigos de erro do TelegramWidget, as variáveis CSS, as regras de gestos e os limites, com base na documentação oficial dos widgets.
Disponibilidade: no ambiente de produção, os widgets hoje funcionam só no chat privado com o bot e não podem ser encaminhados (saem com conteúdo protegido). Grupos, modo inline e encaminhamentos funcionam só no servidor de teste — é lá que propriedades comoisForwardouchatType: "group"fazem diferença primeiro.
Novo no assunto? Comece por o que são os widgets do Telegram e pelos exemplos de widget.
Como o objeto TelegramWidget aparece
Não precisa de tag de script. Dentro do Telegram, window.TelegramWidget existe antes do primeiro script do widget; num navegador comum é undefined. Métodos adicionados dentro de um perfil são detectados com typeof:
const W = window.TelegramWidget; // undefined num navegador comum
if (W && typeof W.setResizeAnchor === 'function') W.setResizeAnchor('bottom');
function render() {
let state = null;
try { state = JSON.parse(W.chatData); } catch (e) {}
// desenhe a partir do estado; null significa "ainda sem estado"
}
if (W) W.onEvent('chatDataChanged', render);
render();
Propriedades do TelegramWidget
| Propriedade | Tipo | Descrição |
|---|---|---|
profile | Integer | Perfil de widget aplicado pelo app: 1 nesta versão |
colorScheme | String | light ou dark, o esquema do chat (também em --tg-color-scheme) |
themeParams | Object | Paleta do balão em #rrggbb, com as chaves do themeParams das Mini Apps |
isActive | Boolean | O widget está visível (!document.hidden) |
isPreview | Boolean | Resultado inline mostrado antes do envio: sem toques, sem requests |
isForward | Boolean | Cópia encaminhada |
chatType | String | private, group, supergroup, channel, ou null em encaminhamento ou prévia |
viewer | Object | id, first_name, last_name, username, is_premium de quem está vendo; só onde o widget pode mandar requests, senão null |
publicData | String | Estado compartilhado, até 1024 bytes, ou null. Somente leitura |
chatData | String | Estado do chat, até 1024 bytes, ou null; sempre null em encaminhamento. Somente leitura |
contentSafeAreaInset | Object | top, right, bottom, left, cornerLeft, cornerRight: a área coberta pelo horário da mensagem |
wallet | Object | Carteira do Telegram, ou null (app sem carteira, requests não permitidos, prévia) |
HapticFeedback | Object | Vibração (haptics), veja abaixo |
Métodos do TelegramWidget
| Método | O que faz |
|---|---|
request(data[, options]) | Envia 1–64 bytes ao bot. Retorna uma Promise de { result } (resposta do bot ou null) ou rejeita com WidgetRequestError. Só no handler de um toque, ou em segundo plano onde permitido. options pode ser { wallet: true } |
watchPublicData() / unwatchPublicData() | Liga / desliga a consulta ao vivo do estado compartilhado enquanto o widget está na tela. Sem efeito em widget estático ou prévia |
copyText(text) | Copia 1–256 caracteres num toque; o app mostra um aviso com o texto |
openLink(url) | Abre uma URL https: (≤ 256 caracteres, host que não seja t.me) depois que o usuário confirma |
openTelegramLink(url) | Abre um link https://t.me/… dentro do Telegram, como um link tocado numa mensagem |
setResizeAnchor(edge) | top (padrão) ou bottom: qual borda do balão fica parada quando a altura muda |
ready() | Opcional: avisa o app que o primeiro estado foi desenhado |
onEvent(type, handler) / offEvent(type, handler) | Adiciona / remove um handler (até 16 por tipo de evento) |
isProfileAtLeast(n) | Retorna profile >= n |
HapticFeedback tem impactOccurred(style) (light, medium, heavy, rigid, soft), notificationOccurred(type) (error, success, warning) e selectionChanged(). Não existe sendMessage, e o widget não conhece o próprio widget_id.
Eventos
| Evento | Quando |
|---|---|
themeChanged | O tema do chat mudou; colorScheme, themeParams e as variáveis CSS já estão atualizados |
activated / deactivated | O widget ficou visível / oculto (depois de visibilitychange) |
chatDataChanged | O bot mudou o estado do chat; chatData já é o novo. Nunca em encaminhamento |
publicDataChanged | O bot mudou o estado compartilhado; num widget compartilhado na tela, só enquanto observa. Dispara depois de chatDataChanged quando ambos mudam |
contentSafeAreaChanged | Mudou a área coberta pelo horário (legenda adicionada, removida ou movida, marca "editado") |
Os handlers são chamados sem argumentos, com this apontando para TelegramWidget: leia os valores novos do objeto.
Códigos do WidgetRequestError
button.addEventListener('click', () => {
status.textContent = 'Enviando…';
TelegramWidget.request('vote:2').then(
(answer) => { status.textContent = answer.result ?? 'Pronto'; },
(error) => { status.textContent = 'Erro: ' + error.code; }, // error.name === 'WidgetRequestError'
);
});
| code | Significado |
|---|---|
NOT_ALLOWED | Sem allow_queries, encaminhamento de widget estático, sem toque onde segundo plano não é permitido, prévia, ou app que não entrega requests |
BUSY | Outro request ou chamada de carteira deste widget está em andamento |
RATE_LIMITED | Chamada em segundo plano menos de 5 segundos após a anterior, ou mais de 5 requests em 5 segundos por usuário e bot |
TIMEOUT | O bot não respondeu em 15 segundos (fora do ar, lento ou sem receber widget_query / shared_widget_query) |
FAILED | Qualquer outra coisa: bot bloqueado ou apagado, mensagem removida, falha de rede |
INVALID_ANSWER | A resposta do bot violou os limites |
REJECTED, BAD_REQUEST | Só chamadas de carteira: o usuário recusou, ou a carteira recusou a transação ou o payload |
Dados vazios ou com mais de 64 bytes lançam TypeError antes de qualquer envio.
Lado do bot: widget_query e answerWidgetQuery
Um request de uma mensagem original chega como widget_query no Update; de um widget compartilhado encaminhado, como shared_widget_query. Se você passa allowed_updates no getUpdates ou no setWebhook, inclua os dois.
{
"update_id": 100000001,
"widget_query": {
"id": "8123456789012345678",
"from": {"id": 123456789, "is_bot": false, "first_name": "Alice"},
"chat": {"id": 123456789, "type": "private", "first_name": "Alice"},
"message_id": 4242,
"chat_instance": "901234567890123456",
"type": {"type": "data"},
"data": "refresh"
}
}
Um widget_query de mensagem enviada via bot traz inline_message_id e chat_type no lugar de chat e message_id; widget_id aparece em widgets compartilhados. Um shared_widget_query tem só id, from, type, data e widget_id. Responda a todo request com answerWidgetQuery (widget_query_id, data opcional de até 1024 bytes) e mude o estado à parte com editMessageWidgetData ou editSharedWidgetData. from e widget_id são definidos pelo Telegram e não podem ser forjados; já data é entrada não confiável.
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/answerWidgetQuery" \
-H "Content-Type: application/json" \
-d '{"widget_query_id": "8123456789012345678", "data": "{\"n\":5,\"r\":3}"}'
Variáveis CSS
| Variável | Uso |
|---|---|
--tg-theme-bg-color, --tg-theme-text-color, --tg-theme-hint-color, --tg-theme-link-color | Fundo do balão, texto, texto secundário, links |
--tg-theme-button-color, --tg-theme-button-text-color | Botão principal do app |
--tg-theme-secondary-bg-color, --tg-theme-accent-text-color, --tg-theme-subtitle-text-color, --tg-theme-destructive-text-color, --tg-theme-section-separator-color | Segunda superfície, destaque, subtítulos, ações destrutivas, separadores |
--tg-color-scheme | light ou dark |
--tg-text-font-size, --tg-text-line-height, --tg-text-padding | Tamanho do texto (cerca de 15px), altura de linha (cerca de 1.35), recuo do texto no balão (cerca de 8px 12px) |
--tg-button-bg, --tg-button-text, --tg-button-radius, --tg-button-font, --tg-button-padding, --tg-button-height, --tg-button-pressed-opacity, --tg-button-disabled-opacity | Estilo do botão do app, usado pelo <button> padrão |
--tg-content-safe-area-inset-*, --tg-content-safe-area-corner-left / -right | Faixa onde o horário é desenhado (igual a env(safe-area-inset-*)) |
O app define essas variáveis no elemento raiz com !important; você só pode redefini-las nos seus próprios elementos. prefers-color-scheme, light-dark() e color-scheme seguem o tema do chat, não o do sistema.
Gestos e touch-action
Toques e toques duplos são sempre do widget; arrastes verticais sempre rolam o chat (o widget recebe pointercancel). Toques longos e arrastes horizontais são reivindicados por elemento com touch-action: auto deixa para o chat (menu da mensagem, deslizar para responder), pan-y dá os arrastes horizontais ao widget e none dá também os toques longos (contextmenu). Regra prática: none em botão de segurar, controle de jogo ou canvas; pan-y em slider horizontal ou carrossel; auto no resto. Use pointer events (touch events não chegam) e mantenha os controles longe dos 20 px da borda inicial.
O que o perfil de widget remove
- Controles de formulário (
input,select,textarea);<button>é o único controle. Sem eventos de teclado nem foco. - Toda API de rede (
fetch,XMLHttpRequest,WebSockete outras lançamNetworkDisabledError), recursos externos,locationehistory. vhe unidades relativas à altura,overflow: auto / scroll(virahidden),position: sticky,@font-face,:has(), CSS nesting.alert,confirm,prompt,navigator.clipboard(usecopyText),iframe,video,audio, WebGL.
Recursos removidos não quebram o widget: o elemento, a declaração ou o evento é descartado e o resto continua funcionando.
Limites dos widgets do Telegram
| Limite | Valor | Se passar |
|---|---|---|
| HTML | 32768 bytes; 4096 bytes após zlib nível 9 | INPUT_MEDIA_WIDGET_TOO_LARGE |
chat_data, public_data | 1024 bytes de UTF-8 cada | INPUT_MEDIA_WIDGET_DATA_TOO_LARGE |
| Dados do request | 1–64 bytes | TypeError no widget |
| Dados da resposta | 1024 bytes | WIDGET_RESULT_TOO_LARGE |
| Prazo de resposta | 15 segundos | TIMEOUT; resposta atrasada: query is too old |
| Requests | 5 a cada 5 segundos por usuário e bot | RATE_LIMITED |
| Edições de widget compartilhado | 1 por segundo; atualização a cada 30 s por padrão, cache_time 5–3600 | Flood wait; invalid cache time specified abaixo de 5 |
| CPU | 300 ms de JavaScript por segundo; 500 ms numa única tarefa | Limitado; o widget é parado |
| Memória | 8 MB | O widget é parado |
| Nós do DOM | 2000 | O widget é parado |
| Timers | 64 ativos | RangeError |
localStorage, sessionStorage | 4 KB por área por mensagem | QuotaExceededError |
| Balão | De 200 px até a largura máxima do balão, 50–600 px de altura | Cortado |
Um widget parado mantém o último quadro com o selo "Widget stopped" e é recriado ao reaparecer; depois de duas falhas seguidas, fica parado até o app reiniciar.
Storage, links, haptics e copyText
- Web Storage pertence a esta mensagem neste aparelho: sobrevive a reinícios do app, nunca vai para o bot e não sincroniza entre dispositivos. Envolva o
setItememtry/catch. - Links:
openLink,openTelegramLink,copyTexterequestexigem um toque real: chame de forma síncrona no handler declick, não depois deawaitou timer. Um toque libera uma chamada. URL inválida lançaTypeError. - Haptics só tocam com o widget visível, no máximo 5 em sequência e 10 por segundo; são livres durante um toque e por 5 segundos depois. Desktop e web não vibram.
- copyText copia 1–256 caracteres e sempre mostra um aviso com o texto copiado.
Pagamentos com a carteira TON, em resumo
O widget pode pedir que o usuário pague pela carteira embutida do Telegram, nos formatos do TON Connect. Mostre o botão de pagar só quando TelegramWidget.wallet não for null. No toque, o widget envia request(data, { wallet: true }); o request do bot chega com type {"type": "data", "wallet_card": …} e o bot responde com uma transação nova. No handler da resposta, o widget chama wallet.sendTransaction(), sem precisar de segundo toque, dentro de 10 segundos:
TelegramWidget.request('pay:42', { wallet: true })
.then((a) => TelegramWidget.wallet.sendTransaction(JSON.parse(a.result), 'paid:42'))
.then((a) => show(a.result), (e) => showError(e.code));
Depois o bot recebe um request do tipo sent_transaction com o hash da mensagem e precisa verificar a transação na blockchain. Após um TIMEOUT o pagamento pode ter passado: consulte o bot sobre o pedido em vez de pagar de novo.
Erros da Bot API para widgets
| Erro | Causa |
|---|---|
INPUT_MEDIA_WIDGET_TOO_LARGE | HTML acima de 32768 bytes ou de 4096 bytes comprimidos |
INPUT_MEDIA_WIDGET_HTML_INVALID | UTF-8 inválido ou caractere NUL em html |
INPUT_MEDIA_WIDGET_DATA_TOO_LARGE | chat_data ou public_data acima de 1024 bytes |
INPUT_MEDIA_WIDGET_DATA_INVALID / WIDGET_DATA_INVALID | Texto de estado inválido no envio / na edição |
message is not modified | Edição que não muda nada; trate como sucesso |
Teste os métodos com o seu token no Bot API Tester e veja os parâmetros do sendWidget. Ainda não tem o token? Veja como pegar o token do bot.
Perguntas frequentes
Preciso incluir algum script para usar o TelegramWidget?
Não. Dentro do Telegram, window.TelegramWidget já existe antes do primeiro script do widget rodar, com estado, tema e contexto prontos. Fora do Telegram ele é undefined, então verifique antes de usar quando abrir o widget no navegador.
O que significa o erro NOT_ALLOWED do WidgetRequestError?
A mensagem não pode enviar requests: o widget foi enviado sem allow_queries, é um encaminhamento de widget estático ou uma prévia, ou request() foi chamado fora de um toque onde requests em segundo plano não são permitidos.
Em quanto tempo o bot precisa responder a um widget_query?
Em até 15 segundos, com answerWidgetQuery. Depois disso a promise do widget rejeita com TIMEOUT e uma resposta atrasada é recusada com query is too old. Responda a todo request, mesmo quando algo deu errado.
O widget pode alterar o próprio chatData ou publicData?
Não. Os dois são somente leitura no widget. Só o bot grava o estado, com sendWidget, editMessageWidgetData ou editSharedWidgetData; o widget só pode pedir ao bot com TelegramWidget.request().
Existe um método TelegramWidget.sendMessage?
Não. sendMessage não existe nos widgets: nada é enviado ao chat em nome do usuário. O widget só pode mandar requests ao seu bot, copiar texto, abrir links e tocar vibração (haptics).
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.
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.
Widgets do Telegram: blocos HTML interativos dentro das mensagens do bot
Widgets do Telegram (Bot API 10.4): o que são, como funcionam sendWidget, chat_data e public_data, onde já rodam e a diferença para Mini Apps.