Примеры виджетов Telegram: готовый HTML и код бота на Python
Здесь собраны полные примеры виджетов 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» и так далее: правки виджета не дают ни пометки «изменено», ни уведомления. Обратите внимание на время «на …»: статус должен читаться как снимок на момент, а не как индикатор прогресса, за которым нужно следить.
editMessageWidgetDataзасчитывается как одно отправленное сообщение в лимиты бота, поэтому не обновляйте статус в плотном цикле.- Менять состояние может только бот, который отправил виджет, а сам HTML заменить нельзя никогда.
Пример 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>
Ключевые моменты в коде виджета:
request()вызывается синхронно внутри обработчика click. Запрос, сделанный позже (послеawaitили в таймере), отклоняется сNOT_ALLOWED: одно нажатие разрешает один вызов.- Промис разрешается объектом
{ result }— этоdataиз ответа бота илиnull— либо отклоняется сWidgetRequestError, чейcodeпоказывается пользователю. - Вне Telegram
window.TelegramWidgetравенundefined, поэтому код проверяетWперед использованием.
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. Настоящий бот хранит состояние в базе с ключом «чат + сообщение».
- Бот отвечает на каждый запрос, даже неизвестный: запрос без ответа закончится в виджете ошибкой
TIMEOUT. - Новое значение фиксируется только после успешного
editMessageWidgetData, а «message is not modified» (например, «Сброс» на счётчике, который уже равен 0) считается успехом. - Запрос не несёт состояние виджета: источник истины — копия у бота, а
dataсверяется со списком допустимых значений, как любойcallback_data.
Пример 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 секунд, без повторного открытия чата.
- Зачем ревизия
r: при опросе общего состояния может прийти версия старше той, что виджет только что получил в ответе. Виджет отбрасывает любое состояние, у которогоrменьше самого свежего из уже виденных. - Одна правка в секунду: общий виджет принимает не больше одной правки в секунду, сверх этого метод вернёт flood wait. Бот помечает состояние как «грязное» и записывает его в
flush(), а пока запись ждёт, опрашивает Telegram сtimeout=1. - Один голос на пользователя: голоса хранятся по
from.idдля этогоwidget_id. Оба поля заполняет Telegram, и виджет не может их подделать. shared_widget_queryуже есть вallowed_updates: когда пересылка появится в продакшене, голоса из пересланных копий (в них толькоid,from,dataиwidget_id) обработает тот же код.- Биржевой тикер строится по той же схеме, только без запросов:
is_sharedбезallow_queriesи цикл, который вызываетeditSharedWidgetDataс новой ценой.
Пример 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_LARGE | HTML больше 32768 байт или больше 4096 байт в сжатом виде | Уберите комментарии и мёртвый код, используйте SVG и CSS вместо data:-картинок |
INPUT_MEDIA_WIDGET_HTML_INVALID | Некорректный UTF-8 или символ NUL в HTML | Читайте файл как текст в UTF-8 и отправляйте строкой |
INPUT_MEDIA_WIDGET_DATA_TOO_LARGE | chat_data или public_data больше 1024 байт | Короткие ключи, компактный JSON (separators=(",", ":")) |
message is not modified | Правка устанавливает то же состояние, что уже есть | Считать успехом |
query is too old | answerWidgetQuery позже 15 секунд | Сначала ответьте, медленную работу делайте потом |
invalid cache time specified | cache_time меньше 5 | Используйте 5–3600 секунд |
А в самом виджете — code отклонённого запроса: NOT_ALLOWED (нет allow_queries, не было нажатия, это превью или пересылка статичного виджета), BUSY (одновременно возможен только один запрос), RATE_LIMITED (больше 5 запросов за 5 секунд), TIMEOUT, FAILED и INVALID_ANSWER. Пустые данные или данные длиннее 64 байт выбрасывают TypeError ещё до отправки.
Чек-лист перед отправкой виджета пользователям
- Сжатый размер меньше 4096 байт (
check_widget.py). - Виджет рисует что-то полезное при состоянии
nullи при отсутствииTelegramWidget. - Цвета берутся из переменных
--tg-theme-*; проверено в светлой и тёмной теме чата. - У сообщения есть подпись — именно её показывают уведомления и старые приложения.
- Бот отвечает на каждый
widget_queryв течение 15 секунд, а вallowed_updatesуказаныwidget_queryиshared_widget_query. - Частота правок ограничена на вашей стороне, а «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.