Telegram Bot API

API JavaScript TelegramWidget: referência, eventos, códigos de erro e limites

· 10 min de leitura

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 como isForward ou chatType: "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

PropriedadeTipoDescrição
profileIntegerPerfil de widget aplicado pelo app: 1 nesta versão
colorSchemeStringlight ou dark, o esquema do chat (também em --tg-color-scheme)
themeParamsObjectPaleta do balão em #rrggbb, com as chaves do themeParams das Mini Apps
isActiveBooleanO widget está visível (!document.hidden)
isPreviewBooleanResultado inline mostrado antes do envio: sem toques, sem requests
isForwardBooleanCópia encaminhada
chatTypeStringprivate, group, supergroup, channel, ou null em encaminhamento ou prévia
viewerObjectid, first_name, last_name, username, is_premium de quem está vendo; só onde o widget pode mandar requests, senão null
publicDataStringEstado compartilhado, até 1024 bytes, ou null. Somente leitura
chatDataStringEstado do chat, até 1024 bytes, ou null; sempre null em encaminhamento. Somente leitura
contentSafeAreaInsetObjecttop, right, bottom, left, cornerLeft, cornerRight: a área coberta pelo horário da mensagem
walletObjectCarteira do Telegram, ou null (app sem carteira, requests não permitidos, prévia)
HapticFeedbackObjectVibração (haptics), veja abaixo

Métodos do TelegramWidget

MétodoO 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

EventoQuando
themeChangedO tema do chat mudou; colorScheme, themeParams e as variáveis CSS já estão atualizados
activated / deactivatedO widget ficou visível / oculto (depois de visibilitychange)
chatDataChangedO bot mudou o estado do chat; chatData já é o novo. Nunca em encaminhamento
publicDataChangedO bot mudou o estado compartilhado; num widget compartilhado na tela, só enquanto observa. Dispara depois de chatDataChanged quando ambos mudam
contentSafeAreaChangedMudou 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'
  );
});
codeSignificado
NOT_ALLOWEDSem allow_queries, encaminhamento de widget estático, sem toque onde segundo plano não é permitido, prévia, ou app que não entrega requests
BUSYOutro request ou chamada de carteira deste widget está em andamento
RATE_LIMITEDChamada em segundo plano menos de 5 segundos após a anterior, ou mais de 5 requests em 5 segundos por usuário e bot
TIMEOUTO bot não respondeu em 15 segundos (fora do ar, lento ou sem receber widget_query / shared_widget_query)
FAILEDQualquer outra coisa: bot bloqueado ou apagado, mensagem removida, falha de rede
INVALID_ANSWERA resposta do bot violou os limites
REJECTED, BAD_REQUESTSó 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ávelUso
--tg-theme-bg-color, --tg-theme-text-color, --tg-theme-hint-color, --tg-theme-link-colorFundo do balão, texto, texto secundário, links
--tg-theme-button-color, --tg-theme-button-text-colorBotã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-colorSegunda superfície, destaque, subtítulos, ações destrutivas, separadores
--tg-color-schemelight ou dark
--tg-text-font-size, --tg-text-line-height, --tg-text-paddingTamanho 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-opacityEstilo do botão do app, usado pelo <button> padrão
--tg-content-safe-area-inset-*, --tg-content-safe-area-corner-left / -rightFaixa 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

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

LimiteValorSe passar
HTML32768 bytes; 4096 bytes após zlib nível 9INPUT_MEDIA_WIDGET_TOO_LARGE
chat_data, public_data1024 bytes de UTF-8 cadaINPUT_MEDIA_WIDGET_DATA_TOO_LARGE
Dados do request1–64 bytesTypeError no widget
Dados da resposta1024 bytesWIDGET_RESULT_TOO_LARGE
Prazo de resposta15 segundosTIMEOUT; resposta atrasada: query is too old
Requests5 a cada 5 segundos por usuário e botRATE_LIMITED
Edições de widget compartilhado1 por segundo; atualização a cada 30 s por padrão, cache_time 5–3600Flood wait; invalid cache time specified abaixo de 5
CPU300 ms de JavaScript por segundo; 500 ms numa única tarefaLimitado; o widget é parado
Memória8 MBO widget é parado
Nós do DOM2000O widget é parado
Timers64 ativosRangeError
localStorage, sessionStorage4 KB por área por mensagemQuotaExceededError
BalãoDe 200 px até a largura máxima do balão, 50–600 px de alturaCortado

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.

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

ErroCausa
INPUT_MEDIA_WIDGET_TOO_LARGEHTML acima de 32768 bytes ou de 4096 bytes comprimidos
INPUT_MEDIA_WIDGET_HTML_INVALIDUTF-8 inválido ou caractere NUL em html
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_data ou public_data acima de 1024 bytes
INPUT_MEDIA_WIDGET_DATA_INVALID / WIDGET_DATA_INVALIDTexto de estado inválido no envio / na edição
message is not modifiedEdiçã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).

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.