Telegram widget örnekleri: eksiksiz HTML ve Python bot kodu
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ı.
editMessageWidgetData, botunuzun gönderim limitlerinde bir gönderilmiş mesaj sayılır; durumu sıkı bir döngüde güncellemeyin.- Durumu yalnızca widget'ı gönderen bot değiştirebilir; HTML'in kendisi asla değiştirilemez.
Ö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:
request(), click handler'ının içinde senkron olarak çağrılır. Sonradan (awaitsonrasında, bir zamanlayıcıda) yapılan istekNOT_ALLOWEDile reddedilir: bir dokunuş tek bir çağrının kilidini açar.- Promise, botun
data'sı veyanullolan{ result }ile çözülür; reddedilirsecodealanı kullanıcıya gösterilen birWidgetRequestErrordöner. - Telegram dışında
window.TelegramWidgetundefined'dır; kod bu yüzden kullanmadan önceW'yi kontrol eder.
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.
- Bot, bilinmeyenler dahil her isteği yanıtlar; yanıtsız istek widget'ta
TIMEOUTile biter. - Yeni sayı yalnızca
editMessageWidgetDatabaşarılı olunca kaydedilir; "message is not modified" (ör. zaten 0 olan sayaçta Sıfırla) başarı sayılır. - İstek widget'ın durumunu taşımaz: doğruluk kaynağı botun kendi kopyasıdır ve
data, hercallback_datagibi bilinen değerler listesine karşı kontrol edilir.
Ö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.
- Neden revizyon
r: paylaşılan durum sorgusu, widget'ın az önce yanıtta aldığından daha eski bir durum getirebilir. Widget,rdeğeri gördüğü en yeniden küçük olan durumu yok sayar. - Saniyede bir düzenleme: paylaşılan widget saniyede en fazla bir düzenleme kabul eder; fazlasında metot flood wait ile hata verir. Bot durumu "kirli" olarak işaretler ve
flush()içinde yazar; bekleyen yazma varkentimeout=1ile sorgular. - Kullanıcı başına bir oy: oylar bu
widget_idiçinfrom.id'ye göre tutulur. İki alan da Telegram'dan gelir ve widget tarafından taklit edilemez. shared_widget_queryzatenallowed_updateslistesinde: iletmeler üretime geldiğinde iletilmiş kopyalardan gelen oylar (yalnızcaid,from,datavewidget_idtaşırlar) aynı kodla işlenir.- Fiyat göstergesi aynı kalıbın istek içermeyen hâlidir:
allow_queriesolmadanis_sharedve yeni fiyatlaeditSharedWidgetDataçağıran bir döngü.
Ö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:
| Hata | Neden | Çözüm |
|---|---|---|
INPUT_MEDIA_WIDGET_TOO_LARGE | HTML 32768 baytı veya sıkıştırılmış hâli 4096 baytı aşıyor | Yorumları ve ölü kodu silin, data: görseller yerine SVG ve CSS tercih edin |
INPUT_MEDIA_WIDGET_HTML_INVALID | HTML'de geçersiz UTF-8 veya NUL karakteri | Dosyayı UTF-8 metin olarak okuyup string olarak gönderin |
INPUT_MEDIA_WIDGET_DATA_TOO_LARGE | chat_data veya public_data 1024 baytı aşıyor | Kısa anahtarlar, sıkı JSON (separators=(",", ":")) |
message is not modified | Düzenleme, widget'ın zaten sahip olduğu durumu yazıyor | Başarı sayın |
query is too old | answerWidgetQuery 15 saniyeden sonra çağrıldı | Önce yanıtlayın, yavaş işi sonra yapın |
invalid cache time specified | cache_time 5'ten küçük | 5–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
- Sıkıştırılmış boyut 4096 baytın altında (
check_widget.py). - Widget, durum
nulliken veTelegramWidgetyokken de işe yarar bir şey çiziyor. - Renkler
--tg-theme-*değişkenlerinden geliyor; açık ve koyu sohbet temasında kontrol edildi. - Mesajda caption var; bildirimler ve eski uygulamalar onu gösterir.
- Bot her
widget_query'yi 15 saniye içinde yanıtlıyor veallowed_updateslistesindewidget_queryileshared_widget_queryvar. - 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.
İlgili rehberler
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?