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 (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» і так далі: редагування віджета не додають ні позначки «змінено», ні сповіщення. Зверніть увагу на час «станом на …»: статус має читатися як знімок на певний момент, а не як індикатор прогресу, за яким треба стежити.

Приклад 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>

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

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 (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 секунд, без повторного відкриття чату.

Приклад 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_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, розмітка й кнопки

Як надіслати повідомлення через бота телеграм: 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.