Exemplos de widget do Telegram: HTML completo e bot em Python
Estes exemplos de widget do Telegram estão completos e prontos para rodar: cada um traz o HTML do widget (bem abaixo do limite de 4 KB comprimido), o código do bot em Python com requests e long polling, e o que o usuário vê. Comece com um card de pedido estático, adicione requests com um contador e depois monte uma enquete ao vivo como widget compartilhado. Se o assunto é novo para você, leia antes o que são os widgets do Telegram.
Antes de começar: no ambiente de produção, os widgets hoje funcionam só no chat privado com o bot e são enviados com conteúdo protegido, ou seja, não podem ser encaminhados. Grupos, modo inline e encaminhamentos só funcionam no servidor de teste. Todos os exemplos abaixo rodam num chat privado.
Você vai precisar de Python 3 com requests (pip install requests), do token do bot (como pegar o token) e do seu chat id. Salve cada widget como arquivo ao lado do script do bot. Antes de escrever código, dá para colar qualquer widget no formulário do sendWidget no Bot API Tester e ver o resultado no seu chat.
Exemplo 1: card de pedido estático (sem requests)
Um resumo de pedido cuja linha de status o bot atualiza conforme o pedido avança. O widget nunca pergunta nada ao bot, então é enviado sem allow_queries. O status fica em chat_data; o widget o desenha ao iniciar e de novo a cada evento chatDataChanged. A mensagem também tem legenda e um teclado inline abaixo do widget.
order.html (925 bytes, 526 bytes comprimidos):
<style>
h3{margin:0 0 6px}
.row{display:flex;justify-content:space-between;gap:12px}
.st{margin-top:10px;padding:6px 10px;border-radius:8px;background:var(--tg-theme-secondary-bg-color)}
.hint{color:var(--tg-theme-hint-color);font-size:.87em}
</style>
<h3>Pedido #1042</h3>
<div class="row"><span>2 × Margherita</span><span>R$ 19,00</span></div>
<div class="row"><span>1 × Limonada</span><span>R$ 4,50</span></div>
<div class="row"><strong>Total</strong><strong>R$ 23,50</strong></div>
<div class="st"><span id="st">Pedido recebido</span> <span class="hint" id="at"></span></div>
<script>
const W = window.TelegramWidget;
function render() {
let s = null;
try { s = JSON.parse(W.chatData); } catch (e) {}
if (!s) return;
document.getElementById('st').textContent = s.status;
document.getElementById('at').textContent = s.at ? 'às ' + s.at : '';
}
if (W) W.onEvent('chatDataChanged', render);
render();
</script>
bot_order.py: envia o card e depois muda o status três vezes:
import json
import time
import requests
TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
CHAT_ID = 123456789 # seu chat privado com o bot
HTML = open("order.html", encoding="utf-8").read()
def call(method, **params):
r = requests.post(f"{API}/{method}", json=params, timeout=40).json()
if not r["ok"]:
if "message is not modified" in r.get("description", ""):
return True # o widget já mostra esse estado
raise RuntimeError(f"{method}: {r['description']}")
return r["result"]
msg = call(
"sendWidget",
chat_id=CHAT_ID,
html=HTML,
chat_data=json.dumps({"status": "Pedido recebido"}),
caption="Pedido #1042: R$ 23,50",
reply_markup={"inline_keyboard": [[
{"text": "Acompanhar pedido", "url": "https://example.com/orders/1042"},
]]},
)
for status in ["Em preparo", "Saiu para entrega", "Entregue"]:
time.sleep(60) # num bot real: quando o sistema de pedidos avisar a mudança
call(
"editMessageWidgetData",
chat_id=CHAT_ID,
message_id=msg["message_id"],
chat_data=json.dumps({"status": status, "at": time.strftime("%H:%M")}),
)// bot_order.mjs
import { readFile } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";
const TOKEN = "123456789:AAEexampleTokenReplaceWithYours";
const API = `https://api.telegram.org/bot${TOKEN}`;
const CHAT_ID = 123456789; // seu chat privado com o bot
const HTML = await readFile("order.html", "utf-8");
async function call(method, params = {}) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
signal: AbortSignal.timeout(40_000),
});
const r = await res.json();
if (!r.ok) {
if ((r.description ?? "").includes("message is not modified")) {
return true; // o widget já mostra esse estado
}
throw new Error(`${method}: ${r.description}`);
}
return r.result;
}
function hhmm() {
return new Date().toTimeString().slice(0, 5); // como time.strftime("%H:%M")
}
const msg = await call("sendWidget", {
chat_id: CHAT_ID,
html: HTML,
chat_data: JSON.stringify({ status: "Pedido recebido" }),
caption: "Pedido #1042: R$ 23,50",
reply_markup: { inline_keyboard: [[
{ text: "Acompanhar pedido", url: "https://example.com/orders/1042" },
]] },
});
for (const status of ["Em preparo", "Saiu para entrega", "Entregue"]) {
await sleep(60_000); // num bot real: quando o sistema de pedidos avisar a mudança
await call("editMessageWidgetData", {
chat_id: CHAT_ID,
message_id: msg.message_id,
chat_data: JSON.stringify({ status, at: hhmm() }),
});
}O que o usuário vê: um card nas cores do chat com os itens, o total e "Pedido recebido", a legenda "Pedido #1042: R$ 23,50" e o botão "Acompanhar pedido" embaixo. A cada minuto a linha de status muda em silêncio para "Em preparo" com um "às 19:40" em cinza, e assim por diante: edições de widget não geram marca de "editado" nem notificação. Repare no horário: o status deve ser lido como um retrato daquele momento, não como uma barra de progresso.
editMessageWidgetDataconta como uma mensagem enviada nos limites de envio do bot, então não atualize o status num loop apertado.- Só o bot que enviou o widget pode mudar o estado, e o HTML nunca pode ser trocado.
Exemplo 2: contador com requests widget_query
Um contador com os botões +1 e Zerar. O toque chama TelegramWidget.request(); o bot atualiza a contagem, grava em chat_data com editMessageWidgetData e responde com o mesmo valor via answerWidgetQuery, para o widget mostrar na hora. O número de revisão r faz o widget ignorar um estado antigo que chegue depois de um mais novo.
counter.html (1220 bytes, 679 bytes comprimidos):
<style>
.n{font-size:2.4em;font-weight:600;text-align:center;font-variant-numeric:tabular-nums}
.row{display:flex;gap:8px}
.row button{flex:1}
#m{min-height:1.35em;margin-top:6px;text-align:center;color:var(--tg-theme-hint-color);font-size:.87em}
</style>
<div class="n" id="n">0</div>
<div class="row"><button id="like">+1</button><button id="reset">Zerar</button></div>
<div id="m"></div>
<script>
const W = window.TelegramWidget, $ = (id) => document.getElementById(id);
let rev = -1;
function show(text) {
let s = null;
try { s = JSON.parse(text); } catch (e) {}
if (!s || typeof s.n !== 'number' || s.r < rev) return false;
rev = s.r;
$('n').textContent = s.n;
return true;
}
function ask(data) {
if (!W) return;
$('m').textContent = 'Enviando…';
W.request(data).then((a) => {
$('m').textContent = show(a.result) ? '' : 'Envie /start para um novo contador';
}, (e) => {
$('m').textContent = e.code === 'TIMEOUT' ? 'O bot não respondeu' : 'Não enviado: ' + e.code;
});
}
$('like').addEventListener('click', () => ask('like'));
$('reset').addEventListener('click', () => ask('reset'));
if (W) {
W.onEvent('chatDataChanged', () => show(W.chatData));
show(W.chatData);
}
</script>
Pontos-chave do código do widget:
request()é chamado de forma síncrona dentro do handler do clique. Um request feito depois (após umawait, num timer) é recusado comNOT_ALLOWED: um toque libera uma chamada.- A promise resolve com
{ result }— odatado bot ounull— e rejeita com umWidgetRequestErrorcujocodeé mostrado ao usuário. - Fora do Telegram,
window.TelegramWidgetéundefined, por isso o código testaWantes de usar.
bot_counter.py: long polling com allowed_updates incluindo widget_query:
import json
import time
import requests
TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
HTML = open("counter.html", encoding="utf-8").read()
counters = {} # (chat_id, message_id) -> {"n": contagem, "r": revisão}
def call(method, **params):
r = requests.post(f"{API}/{method}", json=params, timeout=40).json()
if r["ok"]:
return r["result"]
if "message is not modified" in r.get("description", ""):
return True # nada a mudar: conta como sucesso
print(f"{method} failed: {r.get('description')}")
return None
def dump(state):
return json.dumps(state, separators=(",", ":"))
def send_counter(chat_id):
state = {"n": 0, "r": 0}
msg = call("sendWidget", chat_id=chat_id, html=HTML, chat_data=dump(state),
caption="Toque em +1 para contar", allow_queries=True)
if msg:
counters[(chat_id, msg["message_id"])] = state
def on_widget_query(q):
key = (q["chat"]["id"], q["message_id"])
state = counters.get(key)
if state is None or q["data"] not in ("like", "reset"):
# mensagem desconhecida (ex.: o bot reiniciou) ou data desconhecido: responda mesmo assim
call("answerWidgetQuery", widget_query_id=q["id"])
return
new = {"n": state["n"] + 1 if q["data"] == "like" else 0, "r": state["r"] + 1}
if call("editMessageWidgetData", chat_id=key[0], message_id=key[1],
chat_data=dump(new)):
counters[key] = new # só confirma depois que a edição passou
call("answerWidgetQuery", widget_query_id=q["id"], data=dump(counters[key]))
def main():
offset = 0
while True:
updates = call("getUpdates", offset=offset, timeout=30,
allowed_updates=["message", "widget_query"])
if updates is None:
time.sleep(3)
continue
for u in updates:
offset = u["update_id"] + 1
if "widget_query" in u:
on_widget_query(u["widget_query"])
elif u.get("message", {}).get("text") == "/start":
send_counter(u["message"]["chat"]["id"])
main()// bot_counter.mjs
import { readFile } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";
const TOKEN = "123456789:AAEexampleTokenReplaceWithYours";
const API = `https://api.telegram.org/bot${TOKEN}`;
const HTML = await readFile("counter.html", "utf-8");
const counters = new Map(); // "chat_id:message_id" -> {n: contagem, r: revisão}
async function call(method, params = {}) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
signal: AbortSignal.timeout(40_000),
});
const r = await res.json();
if (r.ok) return r.result;
if ((r.description ?? "").includes("message is not modified")) {
return true; // nada a mudar: conta como sucesso
}
console.log(`${method} failed: ${r.description}`);
return null;
}
function dump(state) {
return JSON.stringify(state); // já compacto, como separators=(",", ":")
}
async function sendCounter(chatId) {
const state = { n: 0, r: 0 };
const msg = await call("sendWidget", {
chat_id: chatId, html: HTML, chat_data: dump(state),
caption: "Toque em +1 para contar", allow_queries: true,
});
if (msg) counters.set(`${chatId}:${msg.message_id}`, state);
}
async function onWidgetQuery(q) {
const chatId = q.chat.id, messageId = q.message_id;
const key = `${chatId}:${messageId}`;
const state = counters.get(key);
if (state === undefined || !["like", "reset"].includes(q.data)) {
// mensagem desconhecida (ex.: o bot reiniciou) ou data desconhecido: responda mesmo assim
await call("answerWidgetQuery", { widget_query_id: q.id });
return;
}
const next = { n: q.data === "like" ? state.n + 1 : 0, r: state.r + 1 };
if (await call("editMessageWidgetData", {
chat_id: chatId, message_id: messageId, chat_data: dump(next),
})) {
counters.set(key, next); // só confirma depois que a edição passou
}
await call("answerWidgetQuery", { widget_query_id: q.id, data: dump(counters.get(key)) });
}
async function main() {
let offset = 0;
while (true) {
const updates = await call("getUpdates", {
offset, timeout: 30, allowed_updates: ["message", "widget_query"],
});
if (updates === null) {
await sleep(3000);
continue;
}
for (const u of updates) {
offset = u.update_id + 1;
if (u.widget_query) {
await onWidgetQuery(u.widget_query);
} else if (u.message?.text === "/start") {
await sendCounter(u.message.chat.id);
}
}
}
}
main();O que o usuário vê: depois do /start, um "0" grande com dois botões nativos. Um toque em +1 mostra "Enviando…" e depois o número novo. Com o bot parado, o widget mostra "O bot não respondeu" após 15 segundos (TIMEOUT). Se o bot reiniciar, o dicionário em memória fica vazio: o bot responde sem dados e o widget pede um novo /start. Um bot de verdade guarda o estado num banco, com chave por chat e mensagem.
- O bot responde a todo request, mesmo os desconhecidos, porque um request sem resposta termina em
TIMEOUTno widget. - A nova contagem só é confirmada depois que
editMessageWidgetDatadá certo, e "message is not modified" (por exemplo, Zerar com o contador já em 0) conta como sucesso. - O request não traz o estado do widget: a cópia do bot é a fonte da verdade, e
dataé validado contra uma lista de valores conhecidos, como qualquercallback_data.
Exemplo 3: enquete ao vivo com widget compartilhado
Uma enquete exibida em vários chats privados com um único resultado. O primeiro sendWidget com is_shared e allow_queries cria o widget compartilhado; o bot guarda o widget.id da mensagem devolvida e depois mostra a mesma enquete a cada usuário que manda /start, com sendSharedWidget. Os votos vão para public_data via editSharedWidgetData, e todas as mensagens com a enquete recebem os totais novos.
poll.html (1798 bytes, 980 bytes comprimidos):
<style>
.o{display:block;width:100%;margin:6px 0;text-align:left}
.me{outline:2px solid var(--tg-theme-button-color)}
.bar{height:4px;margin-top:4px;border-radius:2px;background:var(--tg-theme-button-color)}
.h{color:var(--tg-theme-hint-color);font-size:.87em}
</style>
<strong>Qual linguagem no próximo tutorial?</strong>
<div id="list"></div>
<div class="h" id="msg"></div>
<script>
const W = window.TelegramWidget, $ = (id) => document.getElementById(id);
const OPTS = ['Python', 'JavaScript', 'Go'];
let st = { v: [0, 0, 0], r: -1 }, mine = null;
try { mine = JSON.parse(localStorage.getItem('vote')); } catch (e) {}
function take(text) {
let s = null;
try { s = JSON.parse(text); } catch (e) {}
if (s && Array.isArray(s.v) && s.r >= st.r) { st = s; draw(); }
}
function draw() {
const total = st.v.reduce((a, b) => a + b, 0);
$('list').replaceChildren(...OPTS.map((name, i) => {
const b = document.createElement('button');
const pct = total ? Math.round(st.v[i] / total * 100) : 0;
b.className = 'o' + (mine === i ? ' me' : '');
b.innerHTML = name + ' <span class="h">' + pct + '% (' + st.v[i] + ')</span><div class="bar" style="width:' + pct + '%"></div>';
b.addEventListener('click', () => vote(i));
return b;
}));
}
function vote(i) {
if (!W) return;
$('msg').textContent = 'Enviando…';
W.request('vote:' + i).then((a) => {
mine = i;
try { localStorage.setItem('vote', String(i)); } catch (e) {}
$('msg').textContent = 'Voto registrado';
take(a.result);
draw();
}, (e) => {
$('msg').textContent = e.code === 'NOT_ALLOWED' ? 'Abra o bot para votar' : 'Não enviado: ' + e.code;
});
}
if (W) {
W.onEvent('publicDataChanged', () => take(W.publicData));
W.watchPublicData();
take(W.publicData);
}
draw();
</script>
O widget chama watchPublicData(): sem isso, um widget compartilhado já na tela só pegaria o estado novo quando a mensagem fosse carregada de novo. Enquanto a enquete está visível, o app consulta o estado compartilhado no período de atualização do widget, que o bot define em 10 segundos com cache_time. A escolha do próprio usuário fica no localStorage, que pertence a esta mensagem neste aparelho.
bot_poll.py: votos por usuário, edições agrupadas em no máximo uma por segundo:
import json
import time
import requests
TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
ADMIN_CHAT_ID = 123456789 # seu próprio chat privado com o bot
HTML = open("poll.html", encoding="utf-8").read()
OPTIONS = 3
DB_FILE = "poll.json"
try:
with open(DB_FILE) as f:
db = json.load(f)
except FileNotFoundError:
db = {"widget_id": None, "votes": {}, "r": 0} # votes: id do usuário -> opção
dirty, last_edit = False, 0.0
def save():
with open(DB_FILE, "w") as f:
json.dump(db, f)
def call(method, **params):
r = requests.post(f"{API}/{method}", json=params, timeout=40).json()
if r["ok"]:
return r["result"]
if "message is not modified" in r.get("description", ""):
return True
print(f"{method} failed: {r.get('description')}")
return None
def public_state():
v = [0] * OPTIONS
for option in db["votes"].values():
v[option] += 1
return json.dumps({"v": v, "r": db["r"]}, separators=(",", ":"))
def flush():
"""Grava o estado compartilhado no máximo 1 vez por segundo (limite do widget compartilhado)."""
global dirty, last_edit
if dirty and time.monotonic() - last_edit >= 1:
last_edit = time.monotonic()
if call("editSharedWidgetData", widget_id=db["widget_id"],
public_data=public_state(), cache_time=10):
dirty = False
def on_query(q):
global dirty
data = q["data"]
if q.get("widget_id") == db["widget_id"] and data.startswith("vote:") \
and data[5:].isdigit() and int(data[5:]) < OPTIONS:
db["votes"][str(q["from"]["id"])] = int(data[5:]) # um voto por usuário
db["r"] += 1
save()
dirty = True
# quem votou vê os números na hora; os demais recebem pela edição
call("answerWidgetQuery", widget_query_id=q["id"], data=public_state())
def main():
if not db["widget_id"]:
# o primeiro envio com is_shared cria o widget compartilhado
msg = call("sendWidget", chat_id=ADMIN_CHAT_ID, html=HTML,
public_data=public_state(), is_shared=True, allow_queries=True,
caption="Enquete: qual linguagem no próximo tutorial?")
db["widget_id"] = msg["widget"]["id"]
save()
offset = 0
while True:
updates = call("getUpdates", offset=offset, timeout=1 if dirty else 25,
allowed_updates=["message", "widget_query", "shared_widget_query"])
if updates is None:
time.sleep(3)
continue
for u in updates:
offset = u["update_id"] + 1
q = u.get("widget_query") or u.get("shared_widget_query")
if q:
on_query(q)
elif u.get("message", {}).get("text") == "/start":
call("sendSharedWidget", chat_id=u["message"]["chat"]["id"],
widget_id=db["widget_id"],
caption="Enquete: qual linguagem no próximo tutorial?")
flush()
main()// bot_poll.mjs
import { readFile, writeFile } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";
const TOKEN = "123456789:AAEexampleTokenReplaceWithYours";
const API = `https://api.telegram.org/bot${TOKEN}`;
const ADMIN_CHAT_ID = 123456789; // seu próprio chat privado com o bot
const HTML = await readFile("poll.html", "utf-8");
const OPTIONS = 3;
const DB_FILE = "poll.json";
let db;
try {
db = JSON.parse(await readFile(DB_FILE, "utf-8"));
} catch (e) {
if (e.code !== "ENOENT") throw e;
db = { widget_id: null, votes: {}, r: 0 }; // votes: id do usuário -> opção
}
let dirty = false, lastEdit = -Infinity;
async function save() {
await writeFile(DB_FILE, JSON.stringify(db));
}
async function call(method, params = {}) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
signal: AbortSignal.timeout(40_000),
});
const r = await res.json();
if (r.ok) return r.result;
if ((r.description ?? "").includes("message is not modified")) return true;
console.log(`${method} failed: ${r.description}`);
return null;
}
function publicState() {
const v = new Array(OPTIONS).fill(0);
for (const option of Object.values(db.votes)) v[option] += 1;
return JSON.stringify({ v, r: db.r });
}
// Grava o estado compartilhado no máximo 1 vez por segundo (limite do widget compartilhado).
async function flush() {
const now = performance.now() / 1000; // segundos monotônicos
if (dirty && now - lastEdit >= 1) {
lastEdit = now;
if (await call("editSharedWidgetData", {
widget_id: db.widget_id, public_data: publicState(), cache_time: 10,
})) {
dirty = false;
}
}
}
async function onQuery(q) {
const data = q.data;
const digits = data.slice(5);
if (q.widget_id === db.widget_id && data.startsWith("vote:")
&& /^\d+$/.test(digits) && Number(digits) < OPTIONS) {
db.votes[String(q.from.id)] = Number(digits); // um voto por usuário
db.r += 1;
await save();
dirty = true;
}
// quem votou vê os números na hora; os demais recebem pela edição
await call("answerWidgetQuery", { widget_query_id: q.id, data: publicState() });
}
async function main() {
if (!db.widget_id) {
// o primeiro envio com is_shared cria o widget compartilhado
const msg = await call("sendWidget", {
chat_id: ADMIN_CHAT_ID, html: HTML,
public_data: publicState(), is_shared: true, allow_queries: true,
caption: "Enquete: qual linguagem no próximo tutorial?",
});
db.widget_id = msg.widget.id;
await save();
}
let offset = 0;
while (true) {
const updates = await call("getUpdates", {
offset, timeout: dirty ? 1 : 25,
allowed_updates: ["message", "widget_query", "shared_widget_query"],
});
if (updates === null) {
await sleep(3000);
continue;
}
for (const u of updates) {
offset = u.update_id + 1;
const q = u.widget_query || u.shared_widget_query;
if (q) {
await onQuery(q);
} else if (u.message?.text === "/start") {
await call("sendSharedWidget", {
chat_id: u.message.chat.id,
widget_id: db.widget_id,
caption: "Enquete: qual linguagem no próximo tutorial?",
});
}
}
await flush();
}
}
main();O que o usuário vê: três botões nativos com porcentagens e barras. Após o toque aparece "Voto registrado", a opção escolhida fica contornada e os números já incluem o voto (vindos da resposta). Os votos dos outros aparecem em uns 10 segundos, sem reabrir o chat.
- Por que a revisão
r: uma consulta ao estado compartilhado pode trazer um estado mais velho do que o que o widget acabou de receber na resposta. O widget ignora qualquer estado comrmenor que o mais novo já visto. - Uma edição por segundo: o widget compartilhado aceita no máximo uma edição por segundo; acima disso o método falha com flood wait. O bot marca o estado como pendente e grava em
flush(), fazendo polling comtimeout=1enquanto há escrita pendente. - Um voto por usuário: os votos têm chave
from.idpara estewidget_id. Os dois campos vêm do Telegram e não podem ser forjados pelo widget. shared_widget_queryjá está emallowed_updates: quando os encaminhamentos chegarem à produção, votos de cópias encaminhadas (que trazem sóid,from,dataewidget_id) serão tratados pelo mesmo código.- Uma cotação ao vivo segue o mesmo padrão sem requests:
is_sharedsemallow_queriese um loop que chamaeditSharedWidgetDatacom o preço novo.
Exemplo 4: prévia no navegador, tamanho e erros
Widget é HTML, então uma janela de navegador com 320–430 px de largura dá uma primeira ideia. Fora do Telegram não existe TelegramWidget, então coloque um substituto antes do código do widget. Deixe-o num arquivo próprio, stub.html, para ele nunca ir junto no envio. Esta é uma versão resumida do substituto da documentação oficial, já configurada para o contador:
<style>:root{--tg-theme-bg-color:#fff;--tg-theme-text-color:#000;--tg-theme-hint-color:#707579;
--tg-theme-link-color:#3390ec;--tg-theme-button-color:#3390ec;--tg-theme-button-text-color:#fff;
--tg-theme-secondary-bg-color:#f1f1f4}body{max-width:360px}</style>
<script>
window.TelegramWidget = window.TelegramWidget || {
profile: 1, colorScheme: 'light', themeParams: {}, isActive: true, isPreview: false,
isForward: false, chatType: 'private', viewer: { id: 1, first_name: 'Test' },
chatData: '{"n":4,"r":1}', publicData: null, wallet: null,
HapticFeedback: { impactOccurred() { return this; }, notificationOccurred() { return this; }, selectionChanged() { return this; } },
onEvent() {}, offEvent() {}, ready() {}, watchPublicData() {}, unwatchPublicData() {},
openLink: (url) => console.log('openLink', url), openTelegramLink: (url) => console.log('openTelegramLink', url),
copyText: (text) => console.log('copyText', text),
request: (data) => { console.log('request', data); return Promise.resolve({ result: '{"n":5,"r":2}' }); },
};
</script>
preview.py junta o stub e um widget em preview.html:
import sys
stub = open("stub.html", encoding="utf-8").read()
widget = open(sys.argv[1], encoding="utf-8").read()
with open("preview.html", "w", encoding="utf-8") as f:
f.write(stub + widget)
print("Abra preview.html numa janela de navegador com 320-430 px de largura")// preview.mjs
import { readFile, writeFile } from "node:fs/promises";
const stub = await readFile("stub.html", "utf-8");
const widget = await readFile(process.argv[2], "utf-8");
await writeFile("preview.html", stub + widget, "utf-8");
console.log("Abra preview.html numa janela de navegador com 320-430 px de largura");Rode python3 preview.py counter.html, abra preview.html e acompanhe no console o request like. Ajuste chatData, publicData, viewer e isForward para os casos que quer ver. Lembre que o navegador desenha coisas que o Telegram remove (inputs, vh, rolagem) e não aplica nenhum limite.
check_widget.py mede o tamanho exatamente como o servidor (zlib do Python, nível 9) antes do envio. A versão em Node.js é prática num projeto JavaScript, mas o zlib do Node pode errar por alguns bytes; perto de 4096, confie no número do Python:
import sys
import zlib
raw = open(sys.argv[1], "rb").read()
raw.decode("utf-8") # lança UnicodeDecodeError se o UTF-8 for inválido
packed = len(zlib.compress(raw, 9))
print(f"{len(raw)} bytes, {packed} bytes após zlib nível 9")
if b"\x00" in raw:
sys.exit("caractere NUL: o servidor responde INPUT_MEDIA_WIDGET_HTML_INVALID")
if len(raw) > 32768 or packed > 4096:
sys.exit("grande demais: o servidor responde INPUT_MEDIA_WIDGET_TOO_LARGE")
print("OK")// check_widget.mjs
import { readFile } from "node:fs/promises";
import { deflateSync } from "node:zlib";
function fail(message) {
console.error(message);
process.exit(1);
}
const raw = await readFile(process.argv[2]);
new TextDecoder("utf-8", { fatal: true }).decode(raw); // lança TypeError se o UTF-8 for inválido
// o zlib embutido no Node pode diferir do servidor (Python) em alguns bytes:
// deixe uma pequena margem abaixo de 4096
const packed = deflateSync(raw, { level: 9 }).length;
console.log(`${raw.length} bytes, ${packed} bytes após zlib nível 9`);
if (raw.includes(0)) {
fail("caractere NUL: o servidor responde INPUT_MEDIA_WIDGET_HTML_INVALID");
}
if (raw.length > 32768 || packed > 4096) {
fail("grande demais: o servidor responde INPUT_MEDIA_WIDGET_TOO_LARGE");
}
console.log("OK");$ python3 check_widget.py counter.html
1220 bytes, 679 bytes após zlib nível 9
OK
Erros que a Bot API pode devolver enquanto você mexe nestes exemplos:
| Erro | Causa | Solução |
|---|---|---|
INPUT_MEDIA_WIDGET_TOO_LARGE | HTML acima de 32768 bytes ou de 4096 bytes após compressão | Tire comentários e código morto, prefira SVG e CSS a imagens data: |
INPUT_MEDIA_WIDGET_HTML_INVALID | UTF-8 inválido ou caractere NUL no HTML | Leia o arquivo como texto UTF-8 e envie como string |
INPUT_MEDIA_WIDGET_DATA_TOO_LARGE | chat_data ou public_data acima de 1024 bytes | Chaves curtas, JSON compacto (separators=(",", ":")) |
message is not modified | A edição define o estado que já existe | Trate como sucesso |
query is too old | answerWidgetQuery depois de 15 segundos | Responda primeiro, faça o trabalho lento depois |
invalid cache time specified | cache_time menor que 5 | Use de 5 a 3600 segundos |
No widget, o code de um request rejeitado pode ser: NOT_ALLOWED (sem allow_queries, sem toque, prévia ou encaminhamento de widget estático), BUSY (um request por vez), RATE_LIMITED (mais de 5 requests em 5 segundos), TIMEOUT, FAILED e INVALID_ANSWER. Dados vazios ou com mais de 64 bytes lançam TypeError antes de qualquer envio.
Checklist antes de mandar um widget para usuários
- O tamanho comprimido está abaixo de 4096 bytes (
check_widget.py). - O widget desenha algo útil com estado
nulle quandoTelegramWidgetnão existe. - As cores vêm das variáveis
--tg-theme-*; testado nos temas claro e escuro. - A mensagem tem legenda, que é o que notificações e apps antigos mostram.
- O bot responde a todo
widget_queryem até 15 segundos, eallowed_updateslistawidget_queryeshared_widget_query. - As edições têm limite de taxa do seu lado, e "message is not modified" não é tratado como erro.
Todas as propriedades, eventos e limites usados aqui estão na referência da API JavaScript TelegramWidget; a documentação oficial fica em core.telegram.org/bots/widgets. Os parâmetros de cada método estão na referência de métodos, e se ainda não tem um bot, comece por como criar bot no Telegram.
Perguntas frequentes
Como mandar o HTML para o método sendWidget?
Passe o documento inteiro como a string html e envie a requisição como JSON, por exemplo requests.post(url, json={"chat_id": 123456789, "html": html}) em Python. Assim aspas e quebras de linha do HTML são codificadas corretamente.
Por que meu widget mostra TIMEOUT depois do toque?
O bot não chamou answerWidgetQuery em 15 segundos. Normalmente o bot não está rodando ou passa allowed_updates sem widget_query (e shared_widget_query), então nunca recebe o request.
O que fazer com "message is not modified" no editMessageWidgetData?
Trate como sucesso: o widget já tem esse estado. Isso acontece quando o novo chat_data ou public_data é igual ao atual. Responda mesmo assim ao request que gerou a edição.
Como fazer uma enquete ao vivo com widget compartilhado?
Envie o widget uma vez com is_shared e allow_queries, guarde o widget.id, reenvie para outros chats com sendSharedWidget, conte os votos por (widget_id, from.id) e grave os totais com editSharedWidgetData no máximo uma vez por segundo. O widget precisa chamar watchPublicData().
Como pré-visualizar um widget no navegador?
Fora do Telegram, window.TelegramWidget é undefined. Coloque um objeto substituto e as variáveis de tema antes do código do widget, num arquivo de prévia separado. O navegador não aplica o perfil nem os limites do widget, então teste no Telegram antes de mandar para usuários.
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.
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.