Telegram Bot API

Exemplos de widget do Telegram: HTML completo e bot em Python

· 12 min de leitura

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.

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:

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.

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.

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:

ErroCausaSolução
INPUT_MEDIA_WIDGET_TOO_LARGEHTML acima de 32768 bytes ou de 4096 bytes após compressãoTire comentários e código morto, prefira SVG e CSS a imagens data:
INPUT_MEDIA_WIDGET_HTML_INVALIDUTF-8 inválido ou caractere NUL no HTMLLeia o arquivo como texto UTF-8 e envie como string
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_data ou public_data acima de 1024 bytesChaves curtas, JSON compacto (separators=(",", ":"))
message is not modifiedA edição define o estado que já existeTrate como sucesso
query is too oldanswerWidgetQuery depois de 15 segundosResponda primeiro, faça o trabalho lento depois
invalid cache time specifiedcache_time menor que 5Use 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

  1. O tamanho comprimido está abaixo de 4096 bytes (check_widget.py).
  2. O widget desenha algo útil com estado null e quando TelegramWidget não existe.
  3. As cores vêm das variáveis --tg-theme-*; testado nos temas claro e escuro.
  4. A mensagem tem legenda, que é o que notificações e apps antigos mostram.
  5. O bot responde a todo widget_query em até 15 segundos, e allowed_updates lista widget_query e shared_widget_query.
  6. 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.

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.