Ejemplos de widgets de Telegram: HTML completo y bot en Python
Estos ejemplos de widgets de Telegram están completos y listos para ejecutar: cada uno incluye el HTML del widget (muy por debajo del límite de 4 KB comprimido), el código del bot en Python con requests y long polling, y lo que verá el usuario. Empieza con una tarjeta de pedido estática, añade solicitudes con un contador y termina con una encuesta en vivo como widget compartido. Si los widgets son nuevos para ti, lee primero qué son los widgets de Telegram.
Antes de empezar: en producción, los widgets por ahora solo funcionan en el chat privado con el bot y se envían con contenido protegido, así que no se pueden reenviar. Los grupos, el modo inline y los reenvíos solo funcionan en el servidor de pruebas. Todos los ejemplos corren en un chat privado.
Necesitas Python 3 con requests (pip install requests), el token del bot (cómo obtenerlo) y tu chat id. Guarda cada widget como archivo junto al script del bot. Antes de programar, puedes pegar cualquier widget en el formulario de sendWidget del Bot API Tester y verlo en tu chat.
Ejemplo 1: tarjeta de pedido estática (sin solicitudes)
Un resumen de pedido cuyo estado actualiza el bot. El widget nunca pregunta nada, así que se envía sin allow_queries. El estado vive en chat_data; el widget lo dibuja al iniciar y en cada evento chatDataChanged. El mensaje lleva además un caption y un teclado inline.
order.html (921 bytes, 522 bytes comprimido):
<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>$19.00</span></div>
<div class="row"><span>1 × Limonada</span><span>$4.50</span></div>
<div class="row"><strong>Total</strong><strong>$23.50</strong></div>
<div class="st"><span id="st">Pedido recibido</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 ? 'a las ' + s.at : '';
}
if (W) W.onEvent('chatDataChanged', render);
render();
</script>
bot_order.py: envía la tarjeta y cambia su estado tres veces:
import json
import time
import requests
TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
CHAT_ID = 123456789 # tu chat privado con el 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 # el widget ya muestra este 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 recibido"}),
caption="Pedido #1042: $23.50",
reply_markup={"inline_keyboard": [[
{"text": "Seguir el pedido", "url": "https://example.com/orders/1042"},
]]},
)
for status in ["En preparación", "En camino", "Entregado"]:
time.sleep(60) # en un bot real: cuando tu sistema de pedidos avise de un cambio
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; // tu chat privado con el 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; // el widget ya muestra este 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 recibido" }),
caption: "Pedido #1042: $23.50",
reply_markup: { inline_keyboard: [[
{ text: "Seguir el pedido", url: "https://example.com/orders/1042" },
]] },
});
for (const status of ["En preparación", "En camino", "Entregado"]) {
await sleep(60_000); // en un bot real: cuando tu sistema de pedidos avise de un cambio
await call("editMessageWidgetData", {
chat_id: CHAT_ID,
message_id: msg.message_id,
chat_data: JSON.stringify({ status, at: hhmm() }),
});
}Lo que ve el usuario: una tarjeta con los colores del chat, los productos, el total y "Pedido recibido", el caption "Pedido #1042: $23.50" y un botón "Seguir el pedido". Cada minuto la línea de estado cambia en silencio a "En preparación" con un "a las 19:40" en gris, y así sucesivamente: las ediciones de widgets no muestran la marca "editado" ni generan notificación. La hora hace que el estado se lea como una foto del momento, no como una barra de progreso.
editMessageWidgetDatacuenta como un mensaje enviado en los límites de tu bot, así que no actualices el estado en un bucle cerrado.- Solo el bot que envió el widget puede cambiar su estado, y el HTML nunca se puede reemplazar.
Ejemplo 2: contador con solicitudes widget_query
Un contador con botones +1 y Reiniciar. Un toque llama a TelegramWidget.request(); el bot actualiza la cuenta, la escribe en chat_data con editMessageWidgetData y responde con el mismo valor mediante answerWidgetQuery, para que el widget lo muestre al instante. Un número de revisión r hace que el widget ignore un estado viejo que llegue después de uno nuevo.
counter.html (1228 bytes, 686 bytes comprimido):
<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">Reiniciar</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) ? '' : 'Envía /start para obtener otro contador';
}, (e) => {
$('m').textContent = e.code === 'TIMEOUT' ? 'El bot no respondió' : 'No 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>
Claves del código del widget:
request()se llama de forma síncrona dentro del handler del clic. Una llamada posterior (trasawaito en un temporizador) se rechaza conNOT_ALLOWED: un toque habilita una llamada.- La promesa se resuelve con
{ result }, eldatadel bot onull, y se rechaza con unWidgetRequestErrorcuyocodese muestra al usuario. - Fuera de Telegram
window.TelegramWidgetesundefined, por eso el código revisaWantes de usarlo.
bot_counter.py: long polling con allowed_updates que incluye 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": cuenta, "r": revisión}
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 que cambiar: cuenta como éxito
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="Toca +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"):
# mensaje desconocido (p. ej., el bot se reinició) o data desconocida: responde igual
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 # guarda solo cuando la edición se aplicó
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: cuenta, r: revisión}
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 que cambiar: cuenta como éxito
}
console.log(`${method} failed: ${r.description}`);
return null;
}
function dump(state) {
return JSON.stringify(state); // ya es 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: "Toca +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)) {
// mensaje desconocido (p. ej., el bot se reinició) o data desconocida: responde igual
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); // guarda solo cuando la edición se aplicó
}
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();Lo que ve el usuario: tras /start, un "0" grande con dos botones nativos. Al tocar +1 aparece "Enviando…" y luego el número nuevo. Si el bot está detenido, a los 15 segundos el widget muestra "El bot no respondió" (TIMEOUT). Tras reiniciar el bot, el diccionario en memoria está vacío: el bot responde sin datos y el widget pide enviar /start. Un bot real guarda el estado en una base de datos, por chat y mensaje.
- El bot responde a todas las solicitudes, incluso las desconocidas, porque una sin respuesta termina en
TIMEOUT. - La nueva cuenta se guarda solo si
editMessageWidgetDatatuvo éxito, y "message is not modified" (por ejemplo, Reiniciar con el contador en 0) cuenta como éxito. - La solicitud no trae el estado del widget: la copia del bot es la fuente de verdad, y
datase valida contra una lista de valores conocidos, como cualquiercallback_data.
Ejemplo 3: encuesta en vivo como widget compartido
Una encuesta que aparece en muchos chats privados con un solo conjunto de resultados. El primer sendWidget con is_shared y allow_queries crea el widget compartido; el bot guarda widget.id y muestra la misma encuesta a cada usuario que envía /start con sendSharedWidget. Los votos van a public_data mediante editSharedWidgetData, así que todos los mensajes reciben los nuevos totales.
poll.html (1803 bytes, 985 bytes comprimido):
<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>¿Qué lenguaje para el 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' ? 'Abre el bot para votar' : 'No enviado: ' + e.code;
});
}
if (W) {
W.onEvent('publicDataChanged', () => take(W.publicData));
W.watchPublicData();
take(W.publicData);
}
draw();
</script>
El widget llama a watchPublicData(): sin eso, un widget compartido en pantalla recibiría el nuevo estado solo al volver a cargar el mensaje. Mientras la encuesta está visible, la app consulta el estado compartido según el periodo de actualización, que el bot fija en 10 segundos con cache_time. La elección del usuario se guarda en localStorage, que pertenece a este mensaje en este dispositivo.
bot_poll.py: votos por usuario y ediciones agrupadas a una por segundo:
import json
import time
import requests
TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
ADMIN_CHAT_ID = 123456789 # tu propio chat privado con el 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 de usuario -> opción
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():
"""Escribe el estado compartido como máximo una vez por segundo (límite del widget compartido)."""
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:]) # un voto por usuario
db["r"] += 1
save()
dirty = True
# quien vota ve los totales al instante; los demás, mediante la edición
call("answerWidgetQuery", widget_query_id=q["id"], data=public_state())
def main():
if not db["widget_id"]:
# el primer envío con is_shared crea el widget compartido
msg = call("sendWidget", chat_id=ADMIN_CHAT_ID, html=HTML,
public_data=public_state(), is_shared=True, allow_queries=True,
caption="Encuesta: ¿qué lenguaje para el 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="Encuesta: ¿qué lenguaje para el 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; // tu propio chat privado con el 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 de usuario -> opción
}
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 });
}
// Escribe el estado compartido como máximo una vez por segundo (límite del widget compartido).
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); // un voto por usuario
db.r += 1;
await save();
dirty = true;
}
// quien vota ve los totales al instante; los demás, mediante la edición
await call("answerWidgetQuery", { widget_query_id: q.id, data: publicState() });
}
async function main() {
if (!db.widget_id) {
// el primer envío con is_shared crea el widget compartido
const msg = await call("sendWidget", {
chat_id: ADMIN_CHAT_ID, html: HTML,
public_data: publicState(), is_shared: true, allow_queries: true,
caption: "Encuesta: ¿qué lenguaje para el 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: "Encuesta: ¿qué lenguaje para el próximo tutorial?",
});
}
}
await flush();
}
}
main();Lo que ve el usuario: tres botones nativos con porcentajes y barras. Tras tocar uno aparece "Voto registrado", su opción queda resaltada y los totales ya incluyen su voto (vienen en la respuesta). Los votos de los demás aparecen en unos 10 segundos, sin reabrir el chat.
- Por qué la revisión
r: una consulta del estado compartido puede traer un estado más viejo que el recibido en una respuesta. El widget ignora cualquier estado conrmenor al más reciente. - Una edición por segundo: un widget compartido acepta como máximo una edición por segundo; por encima, el método falla con flood wait. El bot marca el estado como pendiente y lo escribe en
flush(), consultando contimeout=1mientras haya una escritura pendiente. - Un voto por usuario: los votos se indexan por
from.idpara estewidget_id. Ambos campos los pone Telegram y el widget no puede falsificarlos. shared_widget_queryya está enallowed_updates: cuando los reenvíos lleguen a producción, los votos desde copias reenviadas (que traen soloid,from,dataywidget_id) se procesan con el mismo código.- Un ticker de precios sigue el mismo patrón sin solicitudes:
is_sharedsinallow_queriesy un bucle que llama aeditSharedWidgetDatacon el nuevo precio.
Ejemplo 4: vista previa en el navegador, tamaño y errores
Un widget es HTML, así que una ventana de navegador de 320–430 px de ancho sirve para un primer vistazo. Fuera de Telegram no existe TelegramWidget, así que coloca un sustituto antes del código del widget, en un archivo aparte, stub.html, para que nunca termine en lo que envías. Es una versión abreviada del sustituto de la documentación oficial, preparada para el 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 une el sustituto y un widget en 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("Abre preview.html en una ventana de 320-430 px de ancho")// 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("Abre preview.html en una ventana de 320-430 px de ancho");Ejecuta python3 preview.py counter.html, abre preview.html y busca request like en la consola. Ajusta chatData, publicData, viewer e isForward a los casos que quieras ver. Recuerda que el navegador dibuja cosas que Telegram elimina (inputs, vh, scroll) y no aplica ningún límite.
check_widget.py mide el tamaño exactamente como el servidor (zlib de Python a nivel 9) antes de enviar. La versión para Node.js es práctica en un proyecto de JavaScript, pero el zlib de Node puede variar en unos pocos bytes, así que cerca de 4096 fíate del número de Python:
import sys
import zlib
raw = open(sys.argv[1], "rb").read()
raw.decode("utf-8") # lanza UnicodeDecodeError si el UTF-8 no es válido
packed = len(zlib.compress(raw, 9))
print(f"{len(raw)} bytes, {packed} bytes tras zlib nivel 9")
if b"\x00" in raw:
sys.exit("carácter NUL: el servidor responde INPUT_MEDIA_WIDGET_HTML_INVALID")
if len(raw) > 32768 or packed > 4096:
sys.exit("demasiado grande: el 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); // lanza TypeError si el UTF-8 no es válido
// el zlib incluido en Node puede diferir del del servidor (Python) en unos bytes:
// deja un pequeño margen por debajo de 4096
const packed = deflateSync(raw, { level: 9 }).length;
console.log(`${raw.length} bytes, ${packed} bytes tras zlib nivel 9`);
if (raw.includes(0)) {
fail("carácter NUL: el servidor responde INPUT_MEDIA_WIDGET_HTML_INVALID");
}
if (raw.length > 32768 || packed > 4096) {
fail("demasiado grande: el servidor responde INPUT_MEDIA_WIDGET_TOO_LARGE");
}
console.log("OK");$ python3 check_widget.py counter.html
1228 bytes, 686 bytes tras zlib nivel 9
OK
Errores que puede devolver la Bot API con estos ejemplos:
| Error | Causa | Solución |
|---|---|---|
INPUT_MEDIA_WIDGET_TOO_LARGE | HTML de más de 32768 bytes o de más de 4096 bytes comprimido | Quita comentarios y código muerto; prefiere SVG y CSS a imágenes data: |
INPUT_MEDIA_WIDGET_HTML_INVALID | UTF-8 inválido o un carácter NUL en el HTML | Lee el archivo como texto UTF-8 y envíalo como string |
INPUT_MEDIA_WIDGET_DATA_TOO_LARGE | chat_data o public_data de más de 1024 bytes | Claves cortas, JSON compacto (separators=(",", ":")) |
message is not modified | La edición pone el estado que ya tiene | Tómalo como éxito |
query is too old | answerWidgetQuery después de 15 segundos | Responde primero y haz el trabajo lento después |
invalid cache time specified | cache_time menor que 5 | Usa de 5 a 3600 segundos |
Y en el widget, el code de una solicitud rechazada: NOT_ALLOWED (sin allow_queries, sin toque, una vista previa o el reenvío de un widget estático), BUSY (una solicitud a la vez), RATE_LIMITED (más de 5 solicitudes en 5 segundos), TIMEOUT, FAILED e INVALID_ANSWER. Un data vacío o de más de 64 bytes lanza TypeError antes de enviar nada.
Lista de verificación antes de enviar un widget
- El tamaño comprimido es menor de 4096 bytes (
check_widget.py). - El widget dibuja algo útil con estado
nully cuando faltaTelegramWidget. - Los colores salen de las variables
--tg-theme-*; probado en tema claro y oscuro. - El mensaje tiene caption, que es lo que muestran las notificaciones y las apps antiguas.
- El bot responde cada
widget_queryen menos de 15 segundos, yallowed_updatesincluyewidget_queryyshared_widget_query. - Limitas las ediciones de tu lado y no tratas "message is not modified" como error.
Todas las propiedades, eventos y límites usados aquí están en la referencia de la API JavaScript de TelegramWidget; la documentación oficial está en core.telegram.org/bots/widgets. Si aún no tienes bot, empieza por cómo crear un bot en Telegram.
Preguntas frecuentes
¿Cómo envío el HTML al método sendWidget?
Pasa todo el documento como el parámetro de texto html y envía la petición como JSON, por ejemplo requests.post(url, json={"chat_id": 123456789, "html": html}) en Python, para que las comillas y los saltos de línea se codifiquen bien.
¿Por qué mi widget muestra TIMEOUT después de tocarlo?
El bot no llamó a answerWidgetQuery en 15 segundos. Lo normal es que el bot no esté corriendo o que pase allowed_updates sin widget_query (ni shared_widget_query), así que nunca recibe la solicitud.
¿Qué hago con "message is not modified" en editMessageWidgetData?
Tómalo como éxito: el widget ya tiene ese estado. Ocurre cuando el nuevo chat_data o public_data es igual al actual. Aun así, responde a la solicitud que provocó la edición.
¿Cómo hago una encuesta en vivo con un widget compartido?
Envía el widget una vez con is_shared y allow_queries, guarda widget.id, muéstralo en otros chats con sendSharedWidget, cuenta los votos por (widget_id, from.id) y escribe los totales con editSharedWidgetData como máximo una vez por segundo. El widget debe llamar a watchPublicData().
¿Cómo puedo ver un widget en el navegador?
Fuera de Telegram window.TelegramWidget no existe, así que coloca un objeto sustituto y las variables del tema antes del código del widget, en un archivo de vista previa aparte. El navegador no aplica el perfil ni los límites del widget, así que prueba en Telegram antes de enviarlo a usuarios.
Guías relacionadas
Cómo crear un bot en Telegram paso a paso: de BotFather a tu primer mensaje
Aprende a crear un bot de Telegram: /newbot en @BotFather, token, prueba con getMe y tu primer mensaje con curl y Python. Gratis y sin servidor.
Cómo enviar mensajes con la API de Telegram: sendMessage paso a paso
Envía mensajes con la Bot API de Telegram: sendMessage con curl, Python y JavaScript, formato HTML y MarkdownV2, botones inline y errores 400, 403 y 429.
Cómo obtener el token de un bot de Telegram (y qué hacer si se filtra)
Cómo obtener el token de tu bot de Telegram con @BotFather, encontrarlo si el bot ya existe, comprobarlo con getMe y revocarlo si se filtró.
Webhook de Telegram: cómo configurar setWebhook para tu bot (Python y n8n)
Configura el webhook de tu bot de Telegram: requisitos HTTPS, setWebhook con secret_token, getWebhookInfo, handler en Python y errores típicos en n8n.
Cómo obtener el chat id de Telegram: usuarios, grupos, canales y temas
Obtén el chat id de Telegram para tu bot con getUpdates: usuarios, grupos, supergrupos (-100…), canales y temas, y qué hacer si result viene vacío.
Servidor de pruebas de Telegram: cómo probar un bot en el entorno de pruebas
Usa el servidor de pruebas de Telegram: entra al entorno de pruebas, crea un bot de prueba, llama a la Bot API con /test/ y activa TEST en nuestro tester.
Widgets de Telegram para tu sitio web: iniciar sesión con Telegram, posts, comentarios y botón compartir
Integra Telegram en tu sitio: iniciar sesión con Telegram (OIDC), el Login Widget clásico con verificación del hash, posts embebidos y botón compartir.
API JavaScript de TelegramWidget: referencia, eventos, errores y límites
Referencia de la API JavaScript TelegramWidget: propiedades, request(), eventos, errores, variables CSS, widget_query, answerWidgetQuery y límites.
Widgets de Telegram: HTML interactivo dentro de los mensajes de tu bot
Widgets de Telegram (Bot API 10.4): qué son, cómo funcionan sendWidget, chat_data y public_data, dónde se usan hoy y en qué difieren de las Mini Apps.