Telegram Bot API

Ejemplos de widgets de Telegram: HTML completo y bot en Python

· 12 min de lectura

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.

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:

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.

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.

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:

ErrorCausaSolución
INPUT_MEDIA_WIDGET_TOO_LARGEHTML de más de 32768 bytes o de más de 4096 bytes comprimidoQuita comentarios y código muerto; prefiere SVG y CSS a imágenes data:
INPUT_MEDIA_WIDGET_HTML_INVALIDUTF-8 inválido o un carácter NUL en el HTMLLee el archivo como texto UTF-8 y envíalo como string
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_data o public_data de más de 1024 bytesClaves cortas, JSON compacto (separators=(",", ":"))
message is not modifiedLa edición pone el estado que ya tieneTómalo como éxito
query is too oldanswerWidgetQuery después de 15 segundosResponde primero y haz el trabajo lento después
invalid cache time specifiedcache_time menor que 5Usa 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

  1. El tamaño comprimido es menor de 4096 bytes (check_widget.py).
  2. El widget dibuja algo útil con estado null y cuando falta TelegramWidget.
  3. Los colores salen de las variables --tg-theme-*; probado en tema claro y oscuro.
  4. El mensaje tiene caption, que es lo que muestran las notificaciones y las apps antiguas.
  5. El bot responde cada widget_query en menos de 15 segundos, y allowed_updates incluye widget_query y shared_widget_query.
  6. 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.

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.