Telegram Bot API

Contoh Widget Telegram: Kode HTML dan Bot Python Lengkap

· 12 menit baca

Contoh widget telegram di halaman ini lengkap dan siap dijalankan: masing-masing berisi HTML widget (jauh di bawah batas 4 KB terkompresi), kode bot Python dengan requests dan long polling, serta penjelasan apa yang dilihat pengguna. Mulai dari kartu pesanan statis, tambahkan request lewat penghitung (counter), lalu bangun polling live sebagai widget shared. Kalau widget masih baru bagimu, baca dulu apa itu widget Telegram.

Sebelum mulai: di lingkungan produksi, widget saat ini hanya berfungsi di chat pribadi dengan bot, dan dikirim dengan konten terlindungi sehingga tidak bisa diteruskan. Grup, mode inline, dan forward hanya berfungsi di server tes. Semua contoh di bawah berjalan di chat pribadi.

Yang kamu butuhkan: Python 3 dengan requests (pip install requests), token bot (cara mendapatkannya), dan chat id kamu. Simpan setiap widget sebagai file di samping script bot. Sebelum menulis kode, kamu bisa menempelkan widget mana pun ke form sendWidget di Bot API Tester dan langsung melihatnya di chat.

Contoh 1: kartu pesanan statis (tanpa request)

Ringkasan pesanan yang baris statusnya diperbarui bot seiring proses pesanan. Widget tidak pernah bertanya apa pun ke bot, jadi dikirim tanpa allow_queries. Status disimpan di chat_data; widget menggambarnya saat mulai dan setiap kali ada event chatDataChanged. Pesannya juga punya caption dan inline keyboard di bawah widget.

order.html (929 byte, 525 byte terkompresi):

<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>Pesanan #1042</h3>
<div class="row"><span>2 × Margherita</span><span>Rp190.000</span></div>
<div class="row"><span>1 × Es lemon</span><span>Rp45.000</span></div>
<div class="row"><strong>Total</strong><strong>Rp235.000</strong></div>
<div class="st"><span id="st">Pesanan diterima</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 ? 'per ' + s.at : '';
}
if (W) W.onEvent('chatDataChanged', render);
render();
</script>

bot_order.py: kirim kartu, lalu ubah statusnya tiga kali:

import json
import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
CHAT_ID = 123456789  # chat pribadimu dengan bot
HTML = open("order.html", encoding="utf-8").read()


def call(method, **params):
    r = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if not r["ok"]:
        if "message is not modified" in r.get("description", ""):
            return True  # widget sudah menampilkan state ini
        raise RuntimeError(f"{method}: {r['description']}")
    return r["result"]


msg = call(
    "sendWidget",
    chat_id=CHAT_ID,
    html=HTML,
    chat_data=json.dumps({"status": "Pesanan diterima"}),
    caption="Pesanan #1042: Rp235.000",
    reply_markup={"inline_keyboard": [[
        {"text": "Lacak pesanan", "url": "https://example.com/orders/1042"},
    ]]},
)

for status in ["Sedang dimasak", "Dalam perjalanan", "Sudah diantar"]:
    time.sleep(60)  # di bot sungguhan: saat sistem pesanan melaporkan perubahan
    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; // chat pribadimu dengan bot
const HTML = await readFile("order.html", "utf-8");

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  });
  const r = await res.json();
  if (!r.ok) {
    if ((r.description ?? "").includes("message is not modified")) {
      return true; // widget sudah menampilkan state ini
    }
    throw new Error(`${method}: ${r.description}`);
  }
  return r.result;
}

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

const msg = await call("sendWidget", {
  chat_id: CHAT_ID,
  html: HTML,
  chat_data: JSON.stringify({ status: "Pesanan diterima" }),
  caption: "Pesanan #1042: Rp235.000",
  reply_markup: { inline_keyboard: [[
    { text: "Lacak pesanan", url: "https://example.com/orders/1042" },
  ]] },
});

for (const status of ["Sedang dimasak", "Dalam perjalanan", "Sudah diantar"]) {
  await sleep(60_000); // di bot sungguhan: saat sistem pesanan melaporkan perubahan
  await call("editMessageWidgetData", {
    chat_id: CHAT_ID,
    message_id: msg.message_id,
    chat_data: JSON.stringify({ status, at: hhmm() }),
  });
}

Yang dilihat pengguna: kartu dengan warna chat berisi item, total, dan "Pesanan diterima", caption "Pesanan #1042: Rp235.000", serta tombol "Lacak pesanan" di bawahnya. Setiap menit baris status diam-diam berubah menjadi "Sedang dimasak" dengan teks abu-abu "per 19:40", dan seterusnya: edit widget tidak memunculkan tanda "diedit" maupun notifikasi. Perhatikan waktu "per": status sebaiknya terbaca sebagai snapshot, bukan progress bar yang ditunggu-tunggu.

Contoh 2: counter dengan request widget_query

Penghitung dengan tombol +1 dan Reset. Ketukan memanggil TelegramWidget.request(); bot memperbarui hitungan, menulisnya ke chat_data dengan editMessageWidgetData, lalu menjawab dengan nilai yang sama lewat answerWidgetQuery agar widget bisa langsung menampilkannya. Nomor revisi r membuat widget mengabaikan state lama yang datang setelah state yang lebih baru.

counter.html (1219 byte, 678 byte terkompresi):

<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">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 = 'Mengirim…';
  W.request(data).then((a) => {
    $('m').textContent = show(a.result) ? '' : 'Kirim /start untuk penghitung baru';
  }, (e) => {
    $('m').textContent = e.code === 'TIMEOUT' ? 'Bot tidak menjawab' : 'Gagal terkirim: ' + e.code;
  });
}
$('like').addEventListener('click', () => ask('like'));
$('reset').addEventListener('click', () => ask('reset'));
if (W) {
  W.onEvent('chatDataChanged', () => show(W.chatData));
  show(W.chatData);
}
</script>

Poin penting di kode widget:

bot_counter.py: long polling dengan allowed_updates yang menyertakan 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": hitungan, "r": revisi}


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  # tidak ada yang berubah: anggap sukses
    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="Ketuk +1 untuk menghitung", 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"):
        # pesan tidak dikenal (mis. bot baru restart) atau data tidak dikenal: tetap jawab
        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  # simpan hanya setelah edit berhasil
    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: hitungan, r: revisi}

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; // tidak ada yang berubah: anggap sukses
  }
  console.log(`${method} failed: ${r.description}`);
  return null;
}

function dump(state) {
  return JSON.stringify(state); // sudah ringkas, seperti 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: "Ketuk +1 untuk menghitung", 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)) {
    // pesan tidak dikenal (mis. bot baru restart) atau data tidak dikenal: tetap jawab
    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); // simpan hanya setelah edit berhasil
  }
  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();

Yang dilihat pengguna: setelah /start, angka "0" besar dengan dua tombol native. Ketukan +1 menampilkan "Mengirim…", lalu angka baru. Jika bot mati, setelah 15 detik widget menampilkan "Bot tidak menjawab" (TIMEOUT). Setelah bot restart, dictionary di memori kosong, jadi bot menjawab tanpa data dan widget meminta pengguna mengirim /start; bot sungguhan menyimpan state di database dengan kunci chat dan pesan.

Contoh 3: polling live sebagai widget shared Telegram

Satu polling yang tampil di banyak chat pribadi dengan satu set hasil. sendWidget pertama dengan is_shared dan allow_queries membuat widget shared; bot menyimpan widget.id dari pesan yang dikembalikan, lalu menampilkan polling yang sama ke setiap pengguna yang mengirim /start lewat sendSharedWidget. Suara masuk ke public_data melalui editSharedWidgetData, sehingga setiap pesan yang menampilkan polling mendapat total terbaru.

poll.html (1800 byte, 972 byte terkompresi):

<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>Bahasa apa untuk tutorial berikutnya?</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 = 'Mengirim…';
  W.request('vote:' + i).then((a) => {
    mine = i;
    try { localStorage.setItem('vote', String(i)); } catch (e) {}
    $('msg').textContent = 'Suara tercatat';
    take(a.result);
    draw();
  }, (e) => {
    $('msg').textContent = e.code === 'NOT_ALLOWED' ? 'Buka bot untuk memilih' : 'Gagal terkirim: ' + e.code;
  });
}
if (W) {
  W.onEvent('publicDataChanged', () => take(W.publicData));
  W.watchPublicData();
  take(W.publicData);
}
draw();
</script>

Widget memanggil watchPublicData(): tanpa itu, widget shared yang sudah tampil di layar baru mendapat state bersama yang baru saat pesan dimuat ulang. Selama polling terlihat, aplikasi mengambil state bersama sesuai periode refresh widget, yang di sini diatur bot menjadi 10 detik lewat cache_time. Pilihan pengguna sendiri disimpan di localStorage, yang melekat pada pesan ini di perangkat ini.

bot_poll.py: suara disimpan per pengguna, edit digabung menjadi maksimal satu per detik:

import json
import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
ADMIN_CHAT_ID = 123456789  # chat pribadimu sendiri dengan bot
HTML = open("poll.html", encoding="utf-8").read()
OPTIONS = 3
DB_FILE = "poll.json"

try:
    with open(DB_FILE) as f:
        db = json.load(f)
except FileNotFoundError:
    db = {"widget_id": None, "votes": {}, "r": 0}  # votes: user id -> opsi
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():
    """Tulis state bersama maksimal sekali per detik (batas widget shared)."""
    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:])  # satu suara per pengguna
        db["r"] += 1
        save()
        dirty = True
    # pemilih langsung melihat angka baru; yang lain mendapatkannya lewat edit
    call("answerWidgetQuery", widget_query_id=q["id"], data=public_state())


def main():
    if not db["widget_id"]:
        # pengiriman pertama dengan is_shared membuat widget shared
        msg = call("sendWidget", chat_id=ADMIN_CHAT_ID, html=HTML,
                   public_data=public_state(), is_shared=True, allow_queries=True,
                   caption="Polling: bahasa apa untuk tutorial berikutnya?")
        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="Polling: bahasa apa untuk tutorial berikutnya?")
        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; // chat pribadimu sendiri dengan bot
const HTML = await readFile("poll.html", "utf-8");
const OPTIONS = 3;
const DB_FILE = "poll.json";

let db;
try {
  db = JSON.parse(await readFile(DB_FILE, "utf-8"));
} catch (e) {
  if (e.code !== "ENOENT") throw e;
  db = { widget_id: null, votes: {}, r: 0 }; // votes: user id -> opsi
}
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 });
}

// Tulis state bersama maksimal sekali per detik (batas widget shared).
async function flush() {
  const now = performance.now() / 1000; // detik monoton
  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); // satu suara per pengguna
    db.r += 1;
    await save();
    dirty = true;
  }
  // pemilih langsung melihat angka baru; yang lain mendapatkannya lewat edit
  await call("answerWidgetQuery", { widget_query_id: q.id, data: publicState() });
}

async function main() {
  if (!db.widget_id) {
    // pengiriman pertama dengan is_shared membuat widget shared
    const msg = await call("sendWidget", {
      chat_id: ADMIN_CHAT_ID, html: HTML,
      public_data: publicState(), is_shared: true, allow_queries: true,
      caption: "Polling: bahasa apa untuk tutorial berikutnya?",
    });
    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: "Polling: bahasa apa untuk tutorial berikutnya?",
        });
      }
    }
    await flush();
  }
}

main();

Yang dilihat pengguna: tiga tombol native dengan persentase dan bar. Setelah diketuk, muncul "Suara tercatat", opsi pilihan pengguna diberi garis tepi, dan hitungannya langsung menyertakan suaranya (dari jawaban bot). Suara pengguna lain muncul dalam sekitar 10 detik, tanpa perlu membuka ulang chat.

Contoh 4: preview di browser, cek ukuran, dan error

Widget adalah HTML, jadi jendela browser desktop selebar 320–430 px cukup untuk melihat tampilan awalnya. Di luar Telegram tidak ada TelegramWidget, jadi taruh objek pengganti di atas kode widget. Simpan di file terpisah, stub.html, agar tidak ikut terkirim. Ini versi ringkas stub dari dokumentasi resmi, sudah disetel untuk counter:

<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 menggabungkan stub dan widget menjadi 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("Buka preview.html di jendela browser selebar 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("Buka preview.html di jendela browser selebar 320-430 px");

Jalankan python3 preview.py counter.html, buka preview.html, dan lihat console untuk request like. Ubah chatData, publicData, viewer, dan isForward sesuai kasus yang ingin dilihat. Ingat, browser tetap menggambar hal yang dihapus Telegram (input, vh, scroll) dan tidak menerapkan batasan apa pun.

check_widget.py menghitung ukuran persis seperti server (zlib Python level 9) sebelum dikirim. Versi Node.js praktis untuk proyek JavaScript, tetapi zlib Node bisa meleset beberapa byte, jadi jika ukurannya mendekati 4096, percayai angka dari Python:

import sys
import zlib

raw = open(sys.argv[1], "rb").read()
raw.decode("utf-8")  # melempar UnicodeDecodeError jika UTF-8 tidak valid
packed = len(zlib.compress(raw, 9))
print(f"{len(raw)} bytes, {packed} bytes after zlib level 9")
if b"\x00" in raw:
    sys.exit("Karakter NUL: server menjawab INPUT_MEDIA_WIDGET_HTML_INVALID")
if len(raw) > 32768 or packed > 4096:
    sys.exit("Terlalu besar: server menjawab 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); // melempar TypeError jika UTF-8 tidak valid
// zlib bawaan Node bisa berbeda beberapa byte dari zlib server (Python):
// sisakan sedikit ruang di bawah 4096
const packed = deflateSync(raw, { level: 9 }).length;
console.log(`${raw.length} bytes, ${packed} bytes after zlib level 9`);
if (raw.includes(0)) {
  fail("Karakter NUL: server menjawab INPUT_MEDIA_WIDGET_HTML_INVALID");
}
if (raw.length > 32768 || packed > 4096) {
  fail("Terlalu besar: server menjawab INPUT_MEDIA_WIDGET_TOO_LARGE");
}
console.log("OK");
$ python3 check_widget.py counter.html
1219 bytes, 678 bytes after zlib level 9
OK

Error dari Bot API yang mungkin kamu temui saat mencoba contoh-contoh ini:

ErrorPenyebabSolusi
INPUT_MEDIA_WIDGET_TOO_LARGEHTML lebih dari 32768 byte atau lebih dari 4096 byte terkompresiHapus komentar dan kode mati, pilih SVG dan CSS daripada gambar data:
INPUT_MEDIA_WIDGET_HTML_INVALIDUTF-8 tidak valid atau ada karakter NUL di HTMLBaca file sebagai teks UTF-8 dan kirim sebagai string
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_data atau public_data lebih dari 1024 byteKey pendek, JSON ringkas (separators=(",", ":"))
message is not modifiedEdit mengisi state yang sudah samaAnggap sukses
query is too oldanswerWidgetQuery setelah 15 detikJawab dulu, kerjakan proses lambat sesudahnya
invalid cache time specifiedcache_time di bawah 5Pakai 5–3600 detik

Di sisi widget, code dari request yang ditolak: NOT_ALLOWED (tanpa allow_queries, bukan dari ketukan, preview, atau forward widget statis), BUSY (hanya satu request dalam satu waktu), RATE_LIMITED (lebih dari 5 request per 5 detik), TIMEOUT, FAILED, dan INVALID_ANSWER. Data kosong atau lebih dari 64 byte melempar TypeError sebelum apa pun dikirim.

Checklist sebelum mengirim widget ke pengguna

  1. Ukuran terkompresi di bawah 4096 byte (check_widget.py).
  2. Widget tetap menggambar sesuatu yang berguna dari state null dan saat TelegramWidget tidak ada.
  3. Warna diambil dari variabel --tg-theme-*; sudah dicek di tema chat terang dan gelap.
  4. Pesan punya caption, karena itulah yang tampil di notifikasi dan aplikasi lama.
  5. Bot menjawab setiap widget_query dalam 15 detik, dan allowed_updates mencantumkan widget_query dan shared_widget_query.
  6. Edit dibatasi di sisi kamu, dan "message is not modified" tidak diperlakukan sebagai error.

Semua properti, event, dan batasan yang dipakai di sini tercantum di referensi API JavaScript TelegramWidget; dokumentasi resmi ada di core.telegram.org/bots/widgets. Parameter setiap method bisa dilihat di referensi method Bot API, dan kalau bot belum ada, mulai dari cara membuat bot Telegram.

Pertanyaan umum

Bagaimana cara mengirim HTML ke method sendWidget?

Kirim seluruh dokumen sebagai parameter string html. Kirim request sebagai JSON, misalnya requests.post(url, json={"chat_id": 123456789, "html": html}) di Python, agar tanda kutip dan baris baru di HTML ter-encode dengan benar.

Kenapa widget menampilkan TIMEOUT setelah diketuk?

Bot tidak memanggil answerWidgetQuery dalam 15 detik. Biasanya bot sedang tidak jalan, atau bot memakai allowed_updates tanpa widget_query (dan shared_widget_query) sehingga query tidak pernah sampai.

Apa yang harus dilakukan dengan error "message is not modified" dari editMessageWidgetData?

Anggap sebagai sukses: widget sudah memiliki state tersebut. Error ini muncul saat chat_data atau public_data yang baru sama dengan yang sekarang. Tetap jawab widget query yang memicu edit itu.

Bagaimana membuat polling live dengan widget shared Telegram?

Kirim widget sekali dengan is_shared dan allow_queries, simpan widget.id, kirim ke chat lain dengan sendSharedWidget, hitung suara per (widget_id, from.id), lalu tulis totalnya dengan editSharedWidgetData maksimal sekali per detik. Widget wajib memanggil watchPublicData().

Bagaimana cara preview widget di browser?

Di luar Telegram window.TelegramWidget bernilai undefined, jadi taruh objek pengganti kecil dan variabel tema di atas kode widget dalam file preview terpisah. Browser tidak menerapkan profil maupun batasan widget, jadi tetap uji di Telegram sebelum dikirim ke pengguna.

Cara Membuat Bot Telegram: dari BotFather sampai Pesan Pertama

Cara membuat bot telegram langkah demi langkah: daftar di @BotFather, simpan token, cek dengan getMe, lalu kirim pesan pertama lewat curl dan Python.

Kirim Pesan Bot Telegram dengan Telegram Bot API (sendMessage)

Kirim pesan bot telegram lewat Bot API: contoh sendMessage dengan curl, Python, dan JavaScript, format HTML/MarkdownV2, tombol inline, dan solusi error.

Telegram Bot Token: Cara Mendapatkan, Mengecek, dan Mencabut Token

Cara mendapatkan token bot telegram dari @BotFather, melihat token bot lama, mengecek dengan getMe, dan me-revoke token yang bocor. Lengkap dengan contoh.

Webhook Telegram Bot: Cara Setting setWebhook, Secret Token, dan Mengatasi Error

Panduan webhook telegram bot: syarat HTTPS dan port, setWebhook dengan secret_token, cek getWebhookInfo, deleteWebhook, serta solusi error 409 dan n8n.

Chat ID Telegram Dimana? Cara Mendapatkan Chat ID User, Grup, dan Channel

Chat id telegram dimana? Cara mendapatkan chat id user, grup, supergroup, dan channel lewat getUpdates, plus solusi saat result kosong atau error 409.

Server Test Telegram: Cara Test Bot di Lingkungan Test Telegram

Cara memakai server test Telegram untuk bot: login ke lingkungan test, buat bot test, panggil Bot API lewat /test/, lalu aktifkan TEST di tester kami.

Widget Telegram untuk Website: Login dengan Telegram, Embed Post, Komentar, dan Tombol Share

Pasang widget telegram untuk website: login dengan Telegram (OIDC), Login Widget lama dengan cek hash, embed post, komentar channel, dan tombol share.

API JavaScript TelegramWidget: Referensi, Event, Kode Error, dan Batasan

Referensi API JavaScript TelegramWidget: properti, request(), event, kode error, variabel CSS, widget_query dan answerWidgetQuery, plus semua batasannya.

Widget Telegram: HTML Interaktif di Dalam Pesan Bot

Widget telegram (Bot API 10.4): apa itu, cara kerja sendWidget, chat_data dan public_data, di mana bisa dipakai saat ini, dan bedanya dengan Mini App.