Приклади віджетів 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 (990 байтів, 589 байтів у стисненому вигляді):
<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: $23.50",
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: $23.50",
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: $23.50» і кнопку «Відстежити замовлення» під нею. Щохвилини рядок статусу тихо змінюється на «Готується» із сірим «станом на 19:40» і так далі: редагування віджета не додають ні позначки «змінено», ні сповіщення. Зверніть увагу на час «станом на …»: статус має читатися як знімок на певний момент, а не як індикатор прогресу, за яким треба стежити.
editMessageWidgetDataзараховується як одне надіслане повідомлення в ліміти бота, тому не оновлюйте статус у щільному циклі.- Змінювати стан може лише бот, який надіслав віджет, а сам HTML замінити не можна ніколи.
Приклад 2: лічильник із запитами widget_query
Лічильник із кнопками +1 і Скинути. За дотиком віджет викликає TelegramWidget.request(); бот оновлює число, записує його в chat_data через editMessageWidgetData і повертає те саме значення у відповіді answerWidgetQuery, щоб віджет одразу його показав. Номер ревізії r дає змогу віджету ігнорувати старий стан, якщо той надійшов пізніше за новий.
counter.html (1306 байтів, 762 байти у стисненому вигляді):
<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 (1916 байтів, 1096 байтів у стисненому вигляді):
<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
1306 bytes, 762 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, розмітка й кнопки
Як надіслати повідомлення через бота телеграм: sendMessage на curl, Python і JavaScript, parse_mode HTML і MarkdownV2, кнопки та помилки 400, 403, 429.
Токен бота Telegram: як отримати, де знайти, як перевірити й відкликати
Токен бота Телеграм: як отримати його в @BotFather, де знайти токен наявного бота, як перевірити через getMe і що робити, якщо токен витік.
Вебхук для телеграм-бота: налаштування setWebhook, перевірка та видалення
Як налаштувати вебхук телеграм-бота: вимоги до HTTPS і портів, setWebhook із secret_token, перевірка через getWebhookInfo, видалення та типові помилки.
Як дізнатися chat id у Телеграм: користувач, група, канал і тема форуму
Як дізнатися chat id у Телеграм через 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.