Telegram widget: bot mesajının içinde çalışan etkileşimli HTML
Telegram widget, botun sendWidget metoduyla mesajın içinde gönderdiği küçük, etkileşimli bir HTML bloğudur; Bot API 10.4 ile 9 Kasım 2026'da geldi. Widget en fazla 32 KB'lık tek bir HTML belgesidir: Telegram uygulaması onu kullanıcının cihazında, hiçbir ağ erişimi olmadan çalıştırır ve sohbetin kendi stilinde çizer. Durumu güncellenen bir sipariş kartı, bir sayaç, oy geldikçe çubukları hareket eden bir anket ya da tek dokunuşla kopyalanan bir promosyon kodu tipik örneklerdir.
Widget'lar bugün nerede çalışıyor: üretim ortamında bot, widget'ı yalnızca kullanıcıyla olan özel sohbete gönderebilir. Bu mesajlar korumalı içerikle (protected content) gönderilir, yani iletilemez. Gruplarda, inline modda ve iletilen mesajlarda widget'lar şimdilik yalnızca test sunucusunda çalışır.
Telegram widget nedir?
- Tek bir HTML belgesi. Satır içi
<style>ve<script>; görseller yalnızcadata:URL'si veya satır içi SVG olarak. UTF-8'de en fazla 32768 bayt, zlib seviye 9 ile sıkıştırıldıktan sonra en fazla 4096 bayt.<html>ve<body>olmadan çıplak bir parça da olur. - Sandbox içinde. JavaScript bir WebView'da değil, küçük bir JavaScript motoru olan QuickJS'te çalışır. Uygulama, widget'ın yaptığı her değişikliği widget profiline göre denetler ve yalnızca geçenleri çizer; bu yüzden widget iOS, Android, macOS, Telegram Desktop ve web'de aynı görünür.
- Çevrimdışı.
fetch,XMLHttpRequest,WebSocketve diğer ağ API'leriNetworkDisabledErrorfırlatır. Harici script, stil, font ve görseller asla yüklenmez; hazır bir kütüphane de gelmez. - Doğal görünüm. Sohbetin renk paleti
--tg-theme-*CSS değişkenleriyle gelir; stil verilmemiş bir<button>uygulamanın kendi butonu gibi çizilir. - Klavye yok. Input, select ve textarea kaldırılır. Widget dokunuşlara, pointer olaylarına, yatay sürüklemelere ve basılı tutmaya tepki verir.
Kod ve durum: chat_data ve public_data
Widget, sabit kod artı değişebilen durumdan oluşur. HTML gönderildiği anda belirlenir ve bir daha değişmez; onu değiştiren bir metot yoktur. Değişen şey durumdur ve onu yalnızca bot yazar. Widget durumu TelegramWidget.chatData ve TelegramWidget.publicData olarak okur, chatDataChanged ve publicDataChanged olaylarında yeniden çizer.
| Özellik | Sohbet durumu (chat_data) | Paylaşılan durum (public_data) |
|---|---|---|
| Neye bağlı | Tek bir orijinal mesaja | Statik widget'ta mesaja, paylaşılan widget'ta gösterildiği her yere |
| Kim görür | Yalnızca o sohbet (grupta tüm üyeler için tek durum) | Widget'ın gösterildiği her yer |
| İletilen mesajda | Asla | Bir kopya (statik widget) veya canlı paylaşılan durum (paylaşılan widget) |
| Boyut | En fazla 1024 bayt metin | En fazla 1024 bayt metin |
| Değiştiren metot | editMessageWidgetData | editMessageWidgetData veya editSharedWidgetData |
| Örnek | Süren bir oyun, sipariş durumu | Anket sonuçları, bir fiyat |
İkisi de sunucunun yorumlamadığı düz metindir; genellikle JSON kullanılır. Widget içinde olmayan veya temizlenmiş durum null olur.
Widget'lar nerede yaşar: üretim ve test sunucusu
| Yer | Nasıl gelir | İstekler (allow_queries ile) | Üretimde |
|---|---|---|---|
| Botla özel sohbet | sendWidget, sendSharedWidget | Dokunuşta ve arka planda | Evet |
| Normal grup veya süper grup | sendWidget | Yalnızca dokunuşta | Yalnızca test sunucusu |
| Kanallar hariç her sohbet, bot aracılığıyla | Inline mod (InputWidgetMessageContent, InputSharedWidgetMessageContent) | Yalnızca dokunuşta | Yalnızca test sunucusu |
| İletilen mesaj (kanallar dahil) | Kullanıcıların iletmesiyle | Dokunuşta, yalnızca paylaşılan widget'lar | Yalnızca test sunucusu |
Botlar kanallara widget gönderemez. Widget desteklemeyen uygulamalar mesajı açıklamasıyla birlikte desteklenmeyen medya olarak gösterir. Widget mesajları copyMessage veya copyMessages ile kopyalanamaz; gruplarda can_send_other_messages izni widget'ları da kapsar.
Telegram widget mı, Mini App mi?
| Özellik | Mini App | Widget |
|---|---|---|
| Nerede | Buton, menü veya bağlantıyla açılan bir WebView | Mesaj balonunun içinde, sohbette hep görünür |
| Kod | Sizin sunucunuzdaki bir web sayfası | Mesajın içindeki en fazla 32 KB HTML, gönderilince sabit |
| Motor | Platformun WebView'ı | QuickJS sandbox'ı, çizimi Telegram uygulaması yapar |
| Ağ | Tüm web | Yok |
| Botla iletişim | İmzalı initData ile kendi backend'iniz | TelegramWidget.request() → widget_query güncellemesi |
| Girdi | Klavye dahil her şey | Dokunuş ve pointer olayları, klavye yok |
API'lerin örtüştüğü yerlerde TelegramWidget, Telegram.WebApp'teki adları kullanır (themeParams, colorScheme, onEvent, openLink, HapticFeedback, ready). Widget'a sığmayan işler için botunuzu veya Mini App'inizi openTelegramLink ile açın. Mini App geliştiriyorsanız tarayıcıda deneme için Mini App Tester'ı kullanabilirsiniz.
sendWidget ile ilk widget'ınızı gönderin
- Bir bot oluşturun ve token'ını kopyalayın (Telegram bot nasıl yapılır, bot token nasıl alınır).
- Botun size yazabilmesi için ona
/startgönderin ve chat id'nizigetUpdatesile alın. - sendWidget metodunu çağırın.
htmlparametresi bir metin olduğu için isteği JSON olarak gönderin:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendWidget" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"html": "<h3>Promosyon kodunuz</h3><p>Kopyalamak için butona dokunun.</p><button onclick=\"TelegramWidget.copyText(this.textContent)\">PROMO10</button>",
"caption": "Promosyon kodunuz: PROMO10"
}'
Aynısı Python ve requests ya da JavaScript ve fetch ile:
import requests
API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"
html = """<h3>Promosyon kodunuz</h3>
<p>Kopyalamak için butona dokunun.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>"""
r = requests.post(f"{API}/sendWidget", json={
"chat_id": 123456789,
"html": html,
"caption": "Promosyon kodunuz: PROMO10",
}, timeout=10)
print(r.json()) # result: "widget" alanıyla birlikte gönderilen Messageconst API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const html = `<h3>Promosyon kodunuz</h3>
<p>Kopyalamak için butona dokunun.</p>
<button onclick="TelegramWidget.copyText(this.textContent)">PROMO10</button>`;
const r = await fetch(`${API}/sendWidget`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
chat_id: 123456789,
html,
caption: "Promosyon kodunuz: PROMO10",
}),
signal: AbortSignal.timeout(10_000),
});
console.log(await r.json()); // result: "widget" alanıyla birlikte gönderilen MessageBu widget'ta hiç CSS yok, yine de normal bir mesaj ve doğal bir buton gibi görünür. TelegramWidget herhangi bir script etiketi olmadan vardır; copyText ise bir dokunuşun handler'ında çağrıldığı için çalışır. HTML'i Bot API Tester'daki sendWidget formuna yapıştırıp kendi token'ınızla da gönderebilirsiniz.
Diğer sendWidget parametreleri: width ve height (mantıksal piksel cinsinden boyut çapaları), chat_data ve public_data (başlangıç durumu), allow_queries, is_shared ve alışılmış caption, reply_markup, reply_parameters, message_thread_id, protect_content.
Widget botla nasıl konuşur?
İstek, widget'ın içindeki bir callback butonu gibi çalışır:
- Bot widget'ı
allow_queries: trueile gönderir. - Dokunulduğunda widget, 1–64 bayt veriyle
TelegramWidget.request("like")çağırır. - Bot
id,from,chat,message_idvedataiçeren birwidget_querygüncellemesi alır (paylaşılan widget'ın iletilmiş kopyasından gelirseshared_widget_query).allowed_updateskullanıyorsanız iki türü de ekleyin. - Bot 15 saniye içinde answerWidgetQuery çağırır; isteğe bağlı olarak yalnızca soran widget'ın alacağı en fazla 1024 baytlık
datagönderir. - Herkesin gördüğünü değiştirmek için bot editMessageWidgetData (veya
editSharedWidgetData) çağırır; widgetchatDataChanged/publicDataChangedolayını alır.
Yanıtın kendisi durumu asla değiştirmez. İstekler kullanıcı ve bot başına 5 saniyede 5 ile sınırlıdır; yanıtlanmayan istek widget'ta TIMEOUT ile biter. Çalışan kodun tamamı Telegram widget örnekleri rehberinde.
Statik ve paylaşılan widget'lar
is_shared verilmezse widget statiktir: kod ve durum mesajda yaşar, iletilen kopya donmuş bir kopyadır. is_shared ile ilk gönderim bir paylaşılan widget oluşturur: istediğiniz kadar mesajın gösterebildiği, kimliği olan tek bir nesne (dönen mesajda widget.id). Onu sendSharedWidget ile tekrar gönderir, paylaşılan durumunu editSharedWidgetData ile hepsinde birden, saniyede en fazla bir kez değiştirirsiniz. Ekranda duran bir widget yeni paylaşılan durumu ancak TelegramWidget.watchPublicData() çağırdıktan sonra alır; uygulama o zaman durumu widget'ın yenileme periyodunda sorgular (varsayılan 30 saniye, cache_time ile 5–3600).
Telegram widget sınırları özeti
| Ne | Sınır |
|---|---|
| HTML | 32768 bayt; zlib seviye 9 sonrası 4096 bayt |
chat_data, public_data | Her biri 1024 bayt |
| İstek verisi / yanıt verisi | 1–64 bayt / en fazla 1024 bayt |
| İsteği yanıtlama süresi | 15 saniye |
| İstekler | Kullanıcı ve bot başına 5 saniyede 5 |
| Balon boyutu | Genişlik 200 px'ten balonun azami genişliğine, yükseklik 50–600 px; fazlası kırpılır |
| Paylaşılan widget düzenlemeleri | Saniyede 1 |
| Bellek / DOM düğümü | 8 MB / 2000 düğüm |
CPU kotaları, zamanlayıcılar ve depolama dahil tam tablo TelegramWidget API başvurusunda.
Tasarım ipuçları
- Her zaman caption gönderin. Sohbet listesi, bildirimler, arama ve widget desteklemeyen uygulamalar onu gösterir.
- Temayı kullanın. Renkleri
--tg-theme-*değişkenleri üzerine kurun, açık ve koyu sohbet temasında test edin;prefers-color-schemesistemi değil sohbet temasını izler. - İlk durumu hemen çizin:
chatData/publicDataelinizde, yüklenecek bir şey yok. - Küçük tutun. Sıkıştırılmış boyutu sunucunun yaptığı gibi ölçün:
python3 -c 'import sys,zlib; print(len(zlib.compress(sys.stdin.buffer.read(), 9)))' < widget.html. - Sır saklamayın. Kodu ve paylaşılan durumu herkese açık sayın; grupta sohbet durumunu her üye görür.
- Genişliğe göre yerleşim yapın:
%, flex veya grid.vhdesteklenmez ve widget içinde hiçbir şey kaydırılmaz. - İsteğin her sonucunu gösterin: "Gönderiliyor…", yanıt ve her hata kodu.
Web sitesi widget'larıyla karıştırmayın
"Telegram widget" denince eski web sitesi widget'ları da akla gelir: Telegram Login Widget, gönderi gömme (embed) ve paylaş butonu. Bunlar kendi sitenize koyduğunuz script'lerdir; kurulumları web siteleri için Telegram widget'ları rehberinde anlatılıyor. Bot API 10.4 widget'ları ise başka bir şeydir: botun sohbete gönderdiği HTML. Resmi widget belgeleri core.telegram.org/bots/widgets adresindedir.
Sonraki adımlar
- Telegram widget örnekleri: sipariş kartı, istek atan sayaç ve paylaşılan canlı anket; Python bot koduyla.
- TelegramWidget JavaScript API: özellikler, metotlar, olaylar, hata kodları, CSS değişkenleri ve sınırlar.
- Bot API metotları: 10.4 ile gelen diğer metotlar dahil tüm başvuru sayfaları.
Sık sorulan sorular
Telegram widget nedir?
Bot mesajının içinde çizilen küçük, etkileşimli bir bloktur; Bot API 10.4 (9 Kasım 2026) ile geldi. Widget, CSS ve JavaScript'i satır içinde olan tek bir HTML belgesidir; Telegram uygulaması onu kullanıcının cihazında, ağ erişimi olmayan bir sandbox'ta çalıştırır.
Telegram widget gruplarda çalışıyor mu?
Üretim ortamında henüz hayır. Şu an bot, widget'ı üretimde yalnızca kullanıcıyla olan özel sohbete gönderebilir ve bu mesajlar iletilemez. Gruplar, inline mod ve iletmeler şimdilik yalnızca test sunucusunda çalışır.
Bottan widget nasıl gönderilir?
sendWidget metodunu chat_id ve html (1–32768 bayt, zlib seviye 9 ile sıkıştırılınca en fazla 4096 bayt) ile çağırın; isteğe bağlı olarak caption, chat_data, public_data ve allow_queries ekleyin. Metot, widget alanı dolu olan gönderilmiş Message nesnesini döndürür.
Widget HTTP isteği atabilir mi?
Hayır. fetch, XMLHttpRequest, WebSocket ve diğer tüm ağ API'leri NetworkDisabledError fırlatır. Dışarıya tek yol TelegramWidget.request()'tir: botunuza 1–64 bayt veriyi widget_query güncellemesi olarak gönderir.
Widget ile Mini App arasındaki fark nedir?
Mini App, sizin barındırdığınız ve bir buton ya da bağlantıyla WebView'da açılan, tam ağ erişimli bir web sayfasıdır. Widget ise mesaj balonunun içinde yaşar, gönderildiği anda sabitlenen en fazla 32 KB HTML'dir, ağı yoktur ve botuyla yalnızca istekler üzerinden konuşur.
Gönderdikten sonra widget'ın HTML'ini değiştirebilir miyim?
Hayır. Kod gönderildiği anda sabitlenir, yalnızca durum değişir. chat_data veya public_data'yı editMessageWidgetData ya da editSharedWidgetData ile güncelleyin; yeni bir tasarım için yeni widget gönderin. Açıklama (caption) editMessageCaption ile düzenlenebilir.
İ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 örnekleri: eksiksiz HTML ve Python bot kodu
Çalışan Telegram widget örnekleri: statik sipariş kartı, widget_query ile sayaç, paylaşılan canlı anket ve yerel önizleme; HTML ve Python bot kodu.