Telegram Bot API

Примеры виджетов Telegram: готовый HTML и код бота на Python

· 12 мин чтения

Здесь собраны полные примеры виджетов Telegram, которые можно сразу запустить: в каждом есть HTML виджета (с большим запасом до лимита 4 КБ в сжатом виде), код бота на Python с requests и long polling и описание того, что увидит пользователь. Начнём со статичной карточки заказа, затем добавим запросы на примере счётчика и соберём живой опрос на общем виджете. Если виджеты для вас в новинку, сначала прочитайте, что такое виджеты Telegram.

Перед началом: в продакшене виджеты сейчас работают только в личном чате с ботом и отправляются с защищённым содержимым, поэтому переслать их нельзя. Группы, инлайн-режим и пересылка работают только на тестовом сервере. Все примеры ниже запускаются в личном чате.

Что понадобится: Python 3 с requests (pip install requests), токен бота (как его получить) и ваш chat id. Сохраняйте каждый виджет в файл рядом со скриптом бота. Ещё до написания кода любой виджет можно вставить в форму sendWidget в Bot API Tester и посмотреть, как он выглядит в чате.

Пример 1: статичная карточка заказа (без запросов)

Сводка заказа, у которой бот обновляет строку статуса по мере выполнения. Виджет ничего не спрашивает у бота, поэтому отправляется без allow_queries. Статус хранится в chat_data: виджет рисует его при запуске и при каждом событии chatDataChanged. У сообщения также есть подпись и инлайн-клавиатура под виджетом.

order.html (966 байт, 583 байт в сжатом виде):

<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>سفارش #1042</h3>
<div class="row"><span>2 × پیتزا مارگاریتا</span><span>$19.00</span></div>
<div class="row"><span>1 × لیموناد</span><span>$4.50</span></div>
<div class="row"><strong>جمع کل</strong><strong>$23.50</strong></div>
<div class="st"><span id="st">سفارش ثبت شد</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.at : '';
}
if (W) W.onEvent('chatDataChanged', render);
render();
</script>

bot_order.py: отправляем карточку, затем трижды меняем статус:

import json
import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
CHAT_ID = 123456789  # ваш личный чат с ботом
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  # виджет уже показывает это состояние
        raise RuntimeError(f"{method}: {r['description']}")
    return r["result"]


msg = call(
    "sendWidget",
    chat_id=CHAT_ID,
    html=HTML,
    chat_data=json.dumps({"status": "Заказ принят"}),
    caption="Заказ №1042: 1 430 ₽",
    reply_markup={"inline_keyboard": [[
        {"text": "Отследить заказ", "url": "https://example.com/orders/1042"},
    ]]},
)

for status in ["Готовится", "В пути", "Доставлен"]:
    time.sleep(60)  # в реальном боте: когда система заказов сообщит об изменении
    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; // ваш личный чат с ботом
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; // виджет уже показывает это состояние
    }
    throw new Error(`${method}: ${r.description}`);
  }
  return r.result;
}

function hhmm() {
  return new Date().toTimeString().slice(0, 5); // как time.strftime("%H:%M")
}

const msg = await call("sendWidget", {
  chat_id: CHAT_ID,
  html: HTML,
  chat_data: JSON.stringify({ status: "Заказ принят" }),
  caption: "Заказ №1042: 1 430 ₽",
  reply_markup: { inline_keyboard: [[
    { text: "Отследить заказ", url: "https://example.com/orders/1042" },
  ]] },
});

for (const status of ["Готовится", "В пути", "Доставлен"]) {
  await sleep(60_000); // в реальном боте: когда система заказов сообщит об изменении
  await call("editMessageWidgetData", {
    chat_id: CHAT_ID,
    message_id: msg.message_id,
    chat_data: JSON.stringify({ status, at: hhmm() }),
  });
}

Что увидит пользователь: карточку в цветах чата с позициями, итогом и статусом «Заказ принят», подпись «Заказ №1042: 1 430 ₽» и кнопку «Отследить заказ» под ней. Раз в минуту строка статуса тихо меняется на «Готовится» с серым «на 19:40» и так далее: правки виджета не дают ни пометки «изменено», ни уведомления. Обратите внимание на время «на …»: статус должен читаться как снимок на момент, а не как индикатор прогресса, за которым нужно следить.

Пример 2: счётчик с запросами widget_query

Счётчик с кнопками +1 и Сброс. По нажатию виджет вызывает TelegramWidget.request(); бот обновляет число, записывает его в chat_data через editMessageWidgetData и возвращает то же значение в ответе answerWidgetQuery, чтобы виджет сразу его показал. Номер ревизии r позволяет виджету игнорировать старое состояние, если оно пришло позже нового.

counter.html (1271 байт, 736 байт в сжатом виде):

<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">صفر کن</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 = 'در حال ارسال…';
  W.request(data).then((a) => {
    $('m').textContent = show(a.result) ? '' : 'برای شمارنده جدید /start بفرستید';
  }, (e) => {
    $('m').textContent = e.code === 'TIMEOUT' ? 'ربات پاسخ نداد' : 'ارسال نشد: ' + e.code;
  });
}
$('like').addEventListener('click', () => ask('like'));
$('reset').addEventListener('click', () => ask('reset'));
if (W) {
  W.onEvent('chatDataChanged', () => show(W.chatData));
  show(W.chatData);
}
</script>

Ключевые моменты в коде виджета:

bot_counter.py: long polling с allowed_updates, в котором есть 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": значение, "r": ревизия}


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 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="Жмите +1, чтобы считать", 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"):
        # неизвестное сообщение (например, бот перезапущен) или данные: всё равно отвечаем
        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  # сохраняем, только если правка прошла
    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: значение, r: ревизия}

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 dump(state) {
  return JSON.stringify(state); // и так компактно, как 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: "Жмите +1, чтобы считать", 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)) {
    // неизвестное сообщение (например, бот перезапущен) или данные: всё равно отвечаем
    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); // сохраняем, только если правка прошла
  }
  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();

Что увидит пользователь: после /start — крупный «0» и две нативные кнопки. Нажатие на +1 показывает «Отправка…», а затем новое число. Если бот остановлен, через 15 секунд виджет напишет «Бот не ответил» (TIMEOUT). После перезапуска бота словарь в памяти пуст, поэтому бот отвечает без данных, и виджет просит отправить /start. Настоящий бот хранит состояние в базе с ключом «чат + сообщение».

Пример 3: живой опрос на общем виджете Telegram

Один опрос, показанный во многих личных чатах, с общими результатами. Первый sendWidget с is_shared и allow_queries создаёт общий виджет; бот сохраняет widget.id из возвращённого сообщения и потом показывает тот же опрос каждому, кто отправит /start, через sendSharedWidget. Голоса попадают в public_data через editSharedWidgetData, поэтому новые итоги получает каждое сообщение с опросом.

poll.html (1877 байт, 1053 байт в сжатом виде):

<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>آموزش بعدی با کدام زبان باشد؟</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 = 'در حال ارسال…';
  W.request('vote:' + i).then((a) => {
    mine = i;
    try { localStorage.setItem('vote', String(i)); } catch (e) {}
    $('msg').textContent = 'رأی شما ثبت شد';
    take(a.result);
    draw();
  }, (e) => {
    $('msg').textContent = e.code === 'NOT_ALLOWED' ? 'برای رأی دادن ربات را باز کنید' : 'ارسال نشد: ' + e.code;
  });
}
if (W) {
  W.onEvent('publicDataChanged', () => take(W.publicData));
  W.watchPublicData();
  take(W.publicData);
}
draw();
</script>

Виджет вызывает watchPublicData(): без этого общий виджет, который уже на экране, получил бы новое общее состояние только при повторной загрузке сообщения. Пока опрос виден, приложение опрашивает общее состояние с периодом обновления виджета — бот задаёт его в 10 секунд через cache_time. Собственный выбор пользователя хранится в localStorage, который принадлежит этому сообщению на этом устройстве.

bot_poll.py: голоса по пользователям, правки объединяются до одной в секунду:

import json
import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
ADMIN_CHAT_ID = 123456789  # ваш личный чат с ботом
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 пользователя -> вариант
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():
    """Записываем общее состояние не чаще раза в секунду (лимит общего виджета)."""
    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:])  # один голос на пользователя
        db["r"] += 1
        save()
        dirty = True
    # проголосовавший видит новые цифры сразу, остальные — после правки
    call("answerWidgetQuery", widget_query_id=q["id"], data=public_state())


def main():
    if not db["widget_id"]:
        # первая отправка с is_shared создаёт общий виджет
        msg = call("sendWidget", chat_id=ADMIN_CHAT_ID, html=HTML,
                   public_data=public_state(), is_shared=True, allow_queries=True,
                   caption="Опрос: какой язык взять для следующего туториала?")
        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="Опрос: какой язык взять для следующего туториала?")
        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; // ваш личный чат с ботом
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 пользователя -> вариант
}
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 });
}

// Записываем общее состояние не чаще раза в секунду (лимит общего виджета).
async function flush() {
  const now = performance.now() / 1000; // монотонные секунды
  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); // один голос на пользователя
    db.r += 1;
    await save();
    dirty = true;
  }
  // проголосовавший видит новые цифры сразу, остальные — после правки
  await call("answerWidgetQuery", { widget_query_id: q.id, data: publicState() });
}

async function main() {
  if (!db.widget_id) {
    // первая отправка с is_shared создаёт общий виджет
    const msg = await call("sendWidget", {
      chat_id: ADMIN_CHAT_ID, html: HTML,
      public_data: publicState(), is_shared: true, allow_queries: true,
      caption: "Опрос: какой язык взять для следующего туториала?",
    });
    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: "Опрос: какой язык взять для следующего туториала?",
        });
      }
    }
    await flush();
  }
}

main();

Что увидит пользователь: три нативные кнопки с процентами и полосками. После нажатия появляется «Голос учтён», выбранный вариант обводится рамкой, а цифры сразу учитывают голос (из ответа бота). Голоса других пользователей появляются примерно в течение 10 секунд, без повторного открытия чата.

Пример 4: превью в браузере, проверка размера и ошибки

Виджет — это HTML, поэтому первое впечатление можно получить в окне браузера шириной 320–430 px. Вне Telegram объекта TelegramWidget нет, так что перед кодом виджета нужна заглушка. Держите её в отдельном файле stub.html, чтобы она никогда не попала в отправляемый HTML. Это сокращённая версия заглушки из официальной документации, настроенная под счётчик:

<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 склеивает заглушку и виджет в 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("Откройте preview.html в окне браузера шириной 320-430 px")
// 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("Откройте preview.html в окне браузера шириной 320-430 px");

Запустите python3 preview.py counter.html, откройте preview.html и следите в консоли за строкой request like. Подставляйте в chatData, publicData, viewer и isForward те случаи, которые хотите увидеть. Помните, что браузер рисует то, что Telegram удаляет (поля ввода, vh, прокрутку), и не применяет никаких лимитов.

check_widget.py считает размер точно так же, как сервер (zlib из Python, уровень 9), ещё до отправки. Версия для Node.js удобна в JavaScript-проекте, но zlib в Node может отличаться на несколько байт, поэтому вблизи 4096 доверяйте цифре из Python:

import sys
import zlib

raw = open(sys.argv[1], "rb").read()
raw.decode("utf-8")  # UnicodeDecodeError, если UTF-8 некорректный
packed = len(zlib.compress(raw, 9))
print(f"{len(raw)} bytes, {packed} bytes after zlib level 9")
if b"\x00" in raw:
    sys.exit("NUL character: the server answers INPUT_MEDIA_WIDGET_HTML_INVALID")
if len(raw) > 32768 or packed > 4096:
    sys.exit("too large: the server answers 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); // TypeError, если UTF-8 некорректный
// встроенный в Node zlib может отличаться от серверного (Python) на несколько байт:
// оставляйте небольшой запас до 4096
const packed = deflateSync(raw, { level: 9 }).length;
console.log(`${raw.length} bytes, ${packed} bytes after zlib level 9`);
if (raw.includes(0)) {
  fail("NUL character: the server answers INPUT_MEDIA_WIDGET_HTML_INVALID");
}
if (raw.length > 32768 || packed > 4096) {
  fail("too large: the server answers INPUT_MEDIA_WIDGET_TOO_LARGE");
}
console.log("OK");
$ python3 check_widget.py counter.html
1271 bytes, 736 bytes after zlib level 9
OK

Ошибки Bot API, которые могут встретиться при работе с этими примерами:

ОшибкаПричинаЧто делать
INPUT_MEDIA_WIDGET_TOO_LARGEHTML больше 32768 байт или больше 4096 байт в сжатом видеУберите комментарии и мёртвый код, используйте SVG и CSS вместо data:-картинок
INPUT_MEDIA_WIDGET_HTML_INVALIDНекорректный UTF-8 или символ NUL в HTMLЧитайте файл как текст в UTF-8 и отправляйте строкой
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_data или public_data больше 1024 байтКороткие ключи, компактный JSON (separators=(",", ":"))
message is not modifiedПравка устанавливает то же состояние, что уже естьСчитать успехом
query is too oldanswerWidgetQuery позже 15 секундСначала ответьте, медленную работу делайте потом
invalid cache time specifiedcache_time меньше 5Используйте 5–3600 секунд

А в самом виджете — code отклонённого запроса: NOT_ALLOWED (нет allow_queries, не было нажатия, это превью или пересылка статичного виджета), BUSY (одновременно возможен только один запрос), RATE_LIMITED (больше 5 запросов за 5 секунд), TIMEOUT, FAILED и INVALID_ANSWER. Пустые данные или данные длиннее 64 байт выбрасывают TypeError ещё до отправки.

Чек-лист перед отправкой виджета пользователям

  1. Сжатый размер меньше 4096 байт (check_widget.py).
  2. Виджет рисует что-то полезное при состоянии null и при отсутствии TelegramWidget.
  3. Цвета берутся из переменных --tg-theme-*; проверено в светлой и тёмной теме чата.
  4. У сообщения есть подпись — именно её показывают уведомления и старые приложения.
  5. Бот отвечает на каждый widget_query в течение 15 секунд, а в allowed_updates указаны widget_query и shared_widget_query.
  6. Частота правок ограничена на вашей стороне, а «message is not modified» не считается ошибкой.

Все свойства, события и лимиты, которые встречаются в примерах, описаны в справочнике TelegramWidget JavaScript API; официальная документация — на core.telegram.org/bots/widgets. Остальные новинки версии 10.4 — в обзоре что нового в Telegram Bot API 10.

Частые вопросы

Как передать HTML в метод sendWidget?

Передайте весь документ строкой в параметре html. Отправляйте запрос в JSON, например requests.post(url, json={"chat_id": 123456789, "html": html}) на Python, — тогда кавычки и переводы строк в HTML закодируются правильно.

Почему после нажатия виджет показывает TIMEOUT?

Бот не вызвал answerWidgetQuery за 15 секунд. Обычно бот просто не запущен или передаёт allowed_updates без widget_query (и shared_widget_query), поэтому запрос до него не доходит.

Что делать с ошибкой «message is not modified» от editMessageWidgetData?

Считать её успехом: у виджета уже это состояние. Ошибка возникает, когда новые chat_data или public_data совпадают с текущими. На запрос виджета, из-за которого была правка, всё равно нужно ответить.

Как сделать живой опрос на общем виджете Telegram?

Отправьте виджет один раз с is_shared и allow_queries, сохраните widget.id, рассылайте его в другие чаты через sendSharedWidget, считайте голоса по паре (widget_id, from.id) и записывайте итоги через editSharedWidgetData не чаще раза в секунду. Сам виджет должен вызвать watchPublicData().

Как посмотреть виджет в браузере?

Вне Telegram window.TelegramWidget не определён, поэтому в отдельном файле для превью поставьте перед кодом виджета небольшую заглушку и переменные темы. Браузер не применяет профиль виджета и лимиты, так что перед отправкой пользователям проверьте виджет в Telegram.

Как создать бота в Телеграм: от @BotFather до первого сообщения

Как создать бота в Телеграм: регистрация в @BotFather, токен, проверка через getMe, первое сообщение на curl и Python, команды и описание бота.

Что нового в Telegram Bot API 10.0–10.5: настройки бота, виджеты, rich-сообщения, эфемерные сообщения и гостевой режим

Что нового в Telegram Bot API 10.0–10.5: setMySettings и BotFullInfo, HTML-виджеты, rich- и эфемерные сообщения, гостевой режим — с примерами.

Лимиты Telegram Bot API: сообщения в секунду, ошибка 429 и размеры файлов

Все лимиты Telegram Bot API в одном месте: сообщения в секунду, ошибка 429 и retry_after, платные рассылки, размеры файлов, длина текста и подписи.

Как отправить сообщение через бота Telegram: sendMessage, разметка и кнопки

Как отправить сообщение через бота Telegram: sendMessage на curl, Python и JavaScript, parse_mode HTML и MarkdownV2, кнопки и ошибки 400, 403, 429.

Токен бота Telegram: как получить, где найти, как проверить и отозвать

Как получить токен бота Телеграм в @BotFather, где взять токен уже созданного бота, как проверить его через getMe и что делать, если токен утёк.

Вебхук для Telegram-бота: настройка setWebhook, проверка и удаление

Как настроить вебхук Телеграм-бота: требования к HTTPS и портам, setWebhook с secret_token, проверка через getWebhookInfo, удаление и частые ошибки.

Как узнать chat id в Telegram: пользователь, группа, канал и тема форума

Как узнать chat id в Telegram через getUpdates: личный чат, группа, супергруппа, канал и тема форума. Форматы id с -100 и что делать с пустым result.

Тестовый сервер Telegram: как тестировать бота в тестовом окружении

Тестовый сервер Telegram для ботов: вход в тестовое окружение, создание тестового бота, запросы к Bot API через /test/ и переключатель TEST в тестере.

Виджеты Telegram для сайта: вход через Telegram, встраивание постов, комментарии и кнопка «Поделиться»

Вход через Telegram на сайте: новый Telegram Login (OIDC), старый Login Widget с проверкой hash, встраивание постов, комментарии и кнопка «Поделиться».

TelegramWidget JavaScript API: свойства, события, коды ошибок и лимиты

Справочник TelegramWidget API: свойства, request(), события, коды ошибок, CSS-переменные, widget_query и answerWidgetQuery, а также все лимиты виджетов.

Виджеты Telegram: интерактивный HTML прямо в сообщениях бота

Виджеты Telegram в Bot API 10.4: что это, как работают sendWidget, chat_data и public_data, где виджеты доступны сейчас и чем они отличаются от Mini Apps.

Тестирование Telegram Mini App: от браузера до отладки на телефоне

Тестирование Telegram Mini App по шагам: mock-режим в браузере, HTTPS-туннель для localhost, тестовая среда, DevTools на телефоне и проверка initData.