Telegram Bot API

Telegram widget örnekleri: eksiksiz HTML ve Python bot kodu

· 12 dk okuma

Bu Telegram widget örnekleri eksiksiz ve çalıştırılmaya hazır: her birinde widget HTML'i (sıkıştırılmış 4 KB sınırının epey altında), requests ve long polling üzerine kurulu Python bot kodu ve kullanıcının ne gördüğünün açıklaması var. Statik bir sipariş kartıyla başlayın, sayaçla istek eklemeyi görün, ardından paylaşılan widget olarak canlı bir anket kurun. Widget'lar sizin için yeniyse önce Telegram widget nedir rehberini okuyun.

Başlamadan önce: üretim ortamında widget'lar şu an yalnızca botla olan özel sohbette çalışır ve korumalı içerikle gönderildikleri için iletilemez. Gruplar, inline mod ve iletmeler yalnızca test sunucusunda çalışır. Aşağıdaki tüm örnekler özel sohbette çalışır.

Gerekenler: requests kurulu Python 3 (pip install requests), bir bot token'ı (nasıl alınır) ve chat id'niz. Her widget'ı bot script'inin yanına dosya olarak kaydedin. Kod yazmadan önce herhangi bir widget'ı Bot API Tester'daki sendWidget formuna yapıştırıp sohbetinizde görebilirsiniz.

Örnek 1: statik sipariş kartı (istek yok)

Sipariş ilerledikçe durum satırını botun güncellediği bir sipariş özeti. Widget bota hiçbir şey sormaz, bu yüzden allow_queries olmadan gönderilir. Durum chat_data'da tutulur; widget onu başlangıçta ve her chatDataChanged olayında çizer. Mesajda ayrıca bir caption ve widget'ın altında bir inline klavye var.

order.html (944 bayt, sıkıştırılmış 544 bayt):

<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>Sipariş #1042</h3>
<div class="row"><span>2 × Margherita</span><span>380,00 ₺</span></div>
<div class="row"><span>1 × Limonata</span><span>90,00 ₺</span></div>
<div class="row"><strong>Toplam</strong><strong>470,00 ₺</strong></div>
<div class="st"><span id="st">Sipariş alındı</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 + ' itibarıyla' : '';
}
if (W) W.onEvent('chatDataChanged', render);
render();
</script>

bot_order.py: kartı gönderir, ardından durumunu üç kez değiştirir:

import json
import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
CHAT_ID = 123456789  # botla olan özel sohbetiniz
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 bu durumu zaten gösteriyor
        raise RuntimeError(f"{method}: {r['description']}")
    return r["result"]


msg = call(
    "sendWidget",
    chat_id=CHAT_ID,
    html=HTML,
    chat_data=json.dumps({"status": "Sipariş alındı"}),
    caption="Sipariş #1042: 470,00 ₺",
    reply_markup={"inline_keyboard": [[
        {"text": "Siparişi takip et", "url": "https://example.com/orders/1042"},
    ]]},
)

for status in ["Hazırlanıyor", "Yolda", "Teslim edildi"]:
    time.sleep(60)  # gerçek botta: sipariş sisteminiz bir değişiklik bildirdiğinde
    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; // botla olan özel sohbetiniz
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 bu durumu zaten gösteriyor
    }
    throw new Error(`${method}: ${r.description}`);
  }
  return r.result;
}

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

const msg = await call("sendWidget", {
  chat_id: CHAT_ID,
  html: HTML,
  chat_data: JSON.stringify({ status: "Sipariş alındı" }),
  caption: "Sipariş #1042: 470,00 ₺",
  reply_markup: { inline_keyboard: [[
    { text: "Siparişi takip et", url: "https://example.com/orders/1042" },
  ]] },
});

for (const status of ["Hazırlanıyor", "Yolda", "Teslim edildi"]) {
  await sleep(60_000); // gerçek botta: sipariş sisteminiz bir değişiklik bildirdiğinde
  await call("editMessageWidgetData", {
    chat_id: CHAT_ID,
    message_id: msg.message_id,
    chat_data: JSON.stringify({ status, at: hhmm() }),
  });
}

Kullanıcı ne görür: sohbet renklerinde ürünleri, toplamı ve "Sipariş alındı" yazısını gösteren bir kart, altında "Sipariş #1042: 470,00 ₺" açıklaması ve "Siparişi takip et" butonu. Her dakika durum satırı sessizce "Hazırlanıyor" olur, yanında gri "19:40 itibarıyla" yazar ve böyle devam eder: widget düzenlemeleri "düzenlendi" işareti ve bildirim üretmez. "itibarıyla" ifadesine dikkat: durum, birinin beklediği bir ilerleme çubuğu gibi değil, bir anlık görüntü gibi okunmalı.

Örnek 2: widget_query istekleriyle sayaç

+1 ve Sıfırla butonlu bir sayaç. Dokunuş TelegramWidget.request() çağırır; bot sayıyı günceller, editMessageWidgetData ile chat_data'ya yazar ve aynı değeri answerWidgetQuery ile yanıt olarak döner, böylece widget onu hemen gösterebilir. Revizyon numarası r, yeni durumdan sonra gelen eski bir durumu widget'ın yok saymasını sağlar.

counter.html (1228 bayt, sıkıştırılmış 689 bayt):

<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">Sıfırla</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 = 'Gönderiliyor…';
  W.request(data).then((a) => {
    $('m').textContent = show(a.result) ? '' : 'Yeni sayaç için /start gönderin';
  }, (e) => {
    $('m').textContent = e.code === 'TIMEOUT' ? 'Bot yanıt vermedi' : 'Gönderilmedi: ' + e.code;
  });
}
$('like').addEventListener('click', () => ask('like'));
$('reset').addEventListener('click', () => ask('reset'));
if (W) {
  W.onEvent('chatDataChanged', () => show(W.chatData));
  show(W.chatData);
}
</script>

Widget kodunda önemli noktalar:

bot_counter.py: widget_query içeren allowed_updates ile long polling:

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": sayı, "r": revizyon}


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  # değişecek bir şey yok: başarılı say
    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="Saymak için +1'e dokunun", 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"):
        # bilinmeyen mesaj (ör. bot yeniden başladı) veya bilinmeyen veri: yine de yanıtla
        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  # yalnızca düzenleme başarılı olunca kaydet
    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: sayı, r: revizyon}

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; // değişecek bir şey yok: başarılı say
  }
  console.log(`${method} failed: ${r.description}`);
  return null;
}

function dump(state) {
  return JSON.stringify(state); // zaten kompakt, separators=(",", ":") gibi
}

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: "Saymak için +1'e dokunun", 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)) {
    // bilinmeyen mesaj (ör. bot yeniden başladı) veya bilinmeyen veri: yine de yanıtla
    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); // yalnızca düzenleme başarılı olunca kaydet
  }
  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();

Kullanıcı ne görür: /start sonrasında büyük bir "0" ve iki doğal buton. +1'e dokununca "Gönderiliyor…", ardından yeni sayı görünür. Bot durdurulmuşsa widget 15 saniye sonra "Bot yanıt vermedi" gösterir (TIMEOUT). Bot yeniden başlarsa bellekteki sözlük boşalır; bot veri olmadan yanıt verir ve widget kullanıcıdan /start göndermesini ister. Gerçek bir bot durumunu sohbet ve mesaja göre anahtarlanmış bir veritabanında tutar.

Örnek 3: Telegram shared widget ile canlı anket

Pek çok özel sohbette gösterilen, tek bir sonuç kümesine sahip bir anket. is_shared ve allow_queries ile yapılan ilk sendWidget paylaşılan widget'ı oluşturur; bot dönen mesajdaki widget.id'yi saklar ve aynı anketi /start gönderen her kullanıcıya sendSharedWidget ile gösterir. Oylar editSharedWidgetData ile public_data'ya yazılır, böylece anketi gösteren her mesaj yeni toplamları alır.

poll.html (1811 bayt, sıkıştırılmış 993 bayt):

<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>Sıradaki eğitim hangi dilde olsun?</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 = 'Gönderiliyor…';
  W.request('vote:' + i).then((a) => {
    mine = i;
    try { localStorage.setItem('vote', String(i)); } catch (e) {}
    $('msg').textContent = 'Oyunuz sayıldı';
    take(a.result);
    draw();
  }, (e) => {
    $('msg').textContent = e.code === 'NOT_ALLOWED' ? 'Oy vermek için botu açın' : 'Gönderilmedi: ' + e.code;
  });
}
if (W) {
  W.onEvent('publicDataChanged', () => take(W.publicData));
  W.watchPublicData();
  take(W.publicData);
}
draw();
</script>

Widget watchPublicData() çağırır: bu olmadan ekranda duran paylaşılan widget yeni durumu ancak mesaj yeniden yüklendiğinde alırdı. Anket görünür olduğu sürece uygulama paylaşılan durumu widget'ın yenileme periyodunda sorgular; bot bu periyodu cache_time ile 10 saniyeye ayarlar. Kullanıcının kendi seçimi, bu cihazdaki bu mesaja ait olan localStorage'da tutulur.

bot_poll.py: kullanıcıya göre anahtarlanan oylar, saniyede bire indirilen düzenlemeler:

import json
import time
import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API = f"https://api.telegram.org/bot{TOKEN}"
ADMIN_CHAT_ID = 123456789  # botla olan kendi özel sohbetiniz
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: kullanıcı id -> seçenek
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():
    """Paylaşılan durumu saniyede en fazla bir kez yaz (paylaşılan widget sınırı)."""
    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:])  # kullanıcı başına bir oy
        db["r"] += 1
        save()
        dirty = True
    # oy veren yeni sayıları hemen görür; diğerleri düzenleme ile alır
    call("answerWidgetQuery", widget_query_id=q["id"], data=public_state())


def main():
    if not db["widget_id"]:
        # is_shared ile ilk gönderim paylaşılan widget'ı oluşturur
        msg = call("sendWidget", chat_id=ADMIN_CHAT_ID, html=HTML,
                   public_data=public_state(), is_shared=True, allow_queries=True,
                   caption="Anket: sıradaki eğitim hangi dilde olsun?")
        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="Anket: sıradaki eğitim hangi dilde olsun?")
        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; // botla olan kendi özel sohbetiniz
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: kullanıcı id -> seçenek
}
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 });
}

// Paylaşılan durumu saniyede en fazla bir kez yaz (paylaşılan widget sınırı).
async function flush() {
  const now = performance.now() / 1000; // monotonik saniye
  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); // kullanıcı başına bir oy
    db.r += 1;
    await save();
    dirty = true;
  }
  // oy veren yeni sayıları hemen görür; diğerleri düzenleme ile alır
  await call("answerWidgetQuery", { widget_query_id: q.id, data: publicState() });
}

async function main() {
  if (!db.widget_id) {
    // is_shared ile ilk gönderim paylaşılan widget'ı oluşturur
    const msg = await call("sendWidget", {
      chat_id: ADMIN_CHAT_ID, html: HTML,
      public_data: publicState(), is_shared: true, allow_queries: true,
      caption: "Anket: sıradaki eğitim hangi dilde olsun?",
    });
    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: "Anket: sıradaki eğitim hangi dilde olsun?",
        });
      }
    }
    await flush();
  }
}

main();

Kullanıcı ne görür: yüzdeleri ve çubukları olan üç doğal buton. Dokunduktan sonra "Oyunuz sayıldı" yazar, seçtiği seçeneğin çevresi çizilir ve sayılar onun oyunu hemen içerir (yanıttan gelir). Diğer kullanıcıların oyları sohbeti yeniden açmadan yaklaşık 10 saniye içinde görünür.

Örnek 4: tarayıcıda önizleme, boyut kontrolü ve hatalar

Widget sonuçta HTML olduğu için 320–430 px genişliğinde bir masaüstü tarayıcı penceresi hızlı bir ilk bakış sağlar. Telegram dışında TelegramWidget yoktur; widget kodunun üstüne bir yedek nesne koyun. Onu ayrı bir dosyada, stub.html'de tutun ki gönderdiğiniz şeye asla karışmasın. Bu, resmi belgelerdeki yedek nesnenin sayaç için ayarlanmış kısaltılmış hâlidir:

<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 yedek nesneyi ve widget'ı preview.html dosyasında birleştirir:

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 dosyasını 320-430 px genişliğinde bir tarayıcı penceresinde açın")
// 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 dosyasını 320-430 px genişliğinde bir tarayıcı penceresinde açın");

python3 preview.py counter.html çalıştırın, preview.html'i açın ve konsolda request like satırını izleyin. chatData, publicData, viewer ve isForward değerlerini görmek istediğiniz durumlara göre ayarlayın. Unutmayın: tarayıcı Telegram'ın kaldırdığı şeyleri (input'lar, vh, kaydırma) çizer ve hiçbir sınırı uygulamaz.

check_widget.py göndermeden önce boyutu tam olarak sunucunun yaptığı gibi (Python zlib, seviye 9) ölçer. Node.js sürümü bir JavaScript projesinde işe yarar, ancak Node'un zlib'i birkaç bayt sapabilir; bu yüzden 4096'ya yakın değerlerde Python'un sonucuna güvenin:

import sys
import zlib

raw = open(sys.argv[1], "rb").read()
raw.decode("utf-8")  # geçersiz UTF-8'de UnicodeDecodeError fırlatır
packed = len(zlib.compress(raw, 9))
print(f"{len(raw)} bayt, zlib seviye 9 sonrası {packed} bayt")
if b"\x00" in raw:
    sys.exit("NUL karakteri: sunucu INPUT_MEDIA_WIDGET_HTML_INVALID döndürür")
if len(raw) > 32768 or packed > 4096:
    sys.exit("çok büyük: sunucu INPUT_MEDIA_WIDGET_TOO_LARGE döndürür")
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); // geçersiz UTF-8'de TypeError fırlatır
// Node'un paketlediği zlib sunucununkinden (Python) birkaç bayt farklı olabilir:
// 4096'nın biraz altında pay bırakın
const packed = deflateSync(raw, { level: 9 }).length;
console.log(`${raw.length} bayt, zlib seviye 9 sonrası ${packed} bayt`);
if (raw.includes(0)) {
  fail("NUL karakteri: sunucu INPUT_MEDIA_WIDGET_HTML_INVALID döndürür");
}
if (raw.length > 32768 || packed > 4096) {
  fail("çok büyük: sunucu INPUT_MEDIA_WIDGET_TOO_LARGE döndürür");
}
console.log("OK");
$ python3 check_widget.py counter.html
1228 bayt, zlib seviye 9 sonrası 689 bayt
OK

Bu örneklerle çalışırken Bot API'den alabileceğiniz hatalar:

HataNedenÇözüm
INPUT_MEDIA_WIDGET_TOO_LARGEHTML 32768 baytı veya sıkıştırılmış hâli 4096 baytı aşıyorYorumları ve ölü kodu silin, data: görseller yerine SVG ve CSS tercih edin
INPUT_MEDIA_WIDGET_HTML_INVALIDHTML'de geçersiz UTF-8 veya NUL karakteriDosyayı UTF-8 metin olarak okuyup string olarak gönderin
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_data veya public_data 1024 baytı aşıyorKısa anahtarlar, sıkı JSON (separators=(",", ":"))
message is not modifiedDüzenleme, widget'ın zaten sahip olduğu durumu yazıyorBaşarı sayın
query is too oldanswerWidgetQuery 15 saniyeden sonra çağrıldıÖnce yanıtlayın, yavaş işi sonra yapın
invalid cache time specifiedcache_time 5'ten küçük5–3600 saniye kullanın

Widget tarafında reddedilen isteğin code değerleri: NOT_ALLOWED (allow_queries yok, dokunuş yok, önizleme veya statik widget'ın iletilmiş kopyası), BUSY (aynı anda tek istek), RATE_LIMITED (5 saniyede 5 istekten fazla), TIMEOUT, FAILED ve INVALID_ANSWER. Boş veya 64 bayttan uzun veri, hiçbir şey gönderilmeden TypeError fırlatır.

Widget'ı kullanıcılara göndermeden önce kontrol listesi

  1. Sıkıştırılmış boyut 4096 baytın altında (check_widget.py).
  2. Widget, durum null iken ve TelegramWidget yokken de işe yarar bir şey çiziyor.
  3. Renkler --tg-theme-* değişkenlerinden geliyor; açık ve koyu sohbet temasında kontrol edildi.
  4. Mesajda caption var; bildirimler ve eski uygulamalar onu gösterir.
  5. Bot her widget_query'yi 15 saniye içinde yanıtlıyor ve allowed_updates listesinde widget_query ile shared_widget_query var.
  6. Düzenlemeler sizin tarafınızda hız sınırına tabi ve "message is not modified" hata sayılmıyor.

Burada kullanılan tüm özellikler, olaylar ve sınırlar TelegramWidget JavaScript API başvurusunda listeleniyor; resmi belgeler core.telegram.org/bots/widgets adresinde. Botu sıfırdan kuruyorsanız Telegram bot yapma rehberine, 10.4 ile gelen diğer metotlar için metot başvurusuna bakın.

Sık sorulan sorular

sendWidget metoduna HTML nasıl gönderilir?

Belgenin tamamını html metin parametresi olarak verin. İsteği JSON olarak gönderin, örneğin Python'da requests.post(url, json={"chat_id": 123456789, "html": html}); böylece HTML'deki tırnaklar ve satır sonları doğru kodlanır.

Dokunduktan sonra widget neden TIMEOUT gösteriyor?

Bot 15 saniye içinde answerWidgetQuery çağırmadı. Genellikle bot çalışmıyordur ya da allowed_updates listesinde widget_query (ve shared_widget_query) olmadığı için isteği hiç almıyordur.

editMessageWidgetData "message is not modified" döndürürse ne yapmalıyım?

Başarılı sayın: widget zaten bu durumu gösteriyor. Yeni chat_data veya public_data mevcut olanla aynıysa bu hata gelir. Düzenlemeyi tetikleyen widget isteğini yine de yanıtlayın.

Telegram shared widget ile canlı anket nasıl yapılır?

Widget'ı bir kez is_shared ve allow_queries ile gönderin, widget.id değerini saklayın, diğer sohbetlere sendSharedWidget ile gönderin, oyları (widget_id, from.id) çiftine göre sayın ve toplamları saniyede en fazla bir kez editSharedWidgetData ile yazın. Widget watchPublicData() çağırmalıdır.

Widget'ı tarayıcıda nasıl önizlerim?

Telegram dışında window.TelegramWidget tanımsızdır; ayrı bir önizleme dosyasında widget kodunun üstüne küçük bir yedek nesne ve tema değişkenleri koyun. Tarayıcı widget profilini ve sınırları uygulamaz, bu yüzden kullanıcılara göndermeden önce Telegram'da test edin.

Telegram bot nasıl yapılır? BotFather ile adım adım bot oluşturma

Telegram bot yapma rehberi: BotFather'da /newbot ile bot oluşturun, token'ı getMe ile test edin, chat ID'yi bulun ve Python ile ilk mesajı gönderin.

Telegram Bot API ile mesaj gönderme (send message): curl, Python ve JavaScript

Telegram Bot API send message rehberi: curl, Python ve JavaScript ile sendMessage, HTML ve MarkdownV2 biçimlendirme, inline butonlar ve sık hatalar.

Telegram bot token nasıl alınır, nerede bulunur ve nasıl iptal edilir?

Telegram bot token nedir, BotFather'dan nasıl alınır, mevcut botun token'ı nerede bulunur? getMe ile test, 401 hatası ve sızan token'ı iptal etme.

Telegram bot webhook kurulumu: URL, secret token, getWebhookInfo ve sorun giderme

Telegram bot webhook kurulumu: setWebhook ile HTTPS URL ve secret_token ayarlayın, getWebhookInfo ile hataları görün; 409 Conflict ve n8n localhost çözümü.

Telegram chat ID nasıl bulunur: kullanıcı, grup, kanal ve konu için adım adım

Telegram chat ID nasıl bulunur? getUpdates ile kullanıcı, grup, süper grup ve kanal ID'sini öğrenin; -100 ön eki, konu ID'si ve boş result sorunu.

Telegram test sunucusu: Telegram botunu test ortamında nasıl test edersiniz?

Telegram test sunucusu nedir? Test ortamına giriş, test botu oluşturma, Bot API'yi /test/ ile çağırma ve Bot API Tester'da TEST modu adım adım.

Web siteniz için Telegram widget'ları: Telegram ile giriş, gönderi gömme, yorumlar ve paylaş butonu

Sitenize Telegram ile giriş ekleyin: yeni Telegram Login (OIDC), eski Login Widget ve hash kontrolü, gönderi gömme, yorumlar ve paylaş butonu.

TelegramWidget JavaScript API: özellikler, olaylar, hata kodları ve sınırlar

Telegram widget API başvurusu: TelegramWidget özellikleri, request(), olaylar, hata kodları, CSS değişkenleri, widget_query, answerWidgetQuery ve sınırlar.

Telegram widget: bot mesajının içinde çalışan etkileşimli HTML

Telegram widget nedir: Bot API 10.4'teki sendWidget, chat_data ve public_data nasıl çalışır, bugün nerede kullanılabilir, Mini App'ten farkı nedir?