Telegram Bot API

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

· 8 dk okuma

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?

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.

ÖzellikSohbet durumu (chat_data)Paylaşılan durum (public_data)
Neye bağlıTek bir orijinal mesajaStatik widget'ta mesaja, paylaşılan widget'ta gösterildiği her yere
Kim görürYalnızca o sohbet (grupta tüm üyeler için tek durum)Widget'ın gösterildiği her yer
İletilen mesajdaAslaBir kopya (statik widget) veya canlı paylaşılan durum (paylaşılan widget)
BoyutEn fazla 1024 bayt metinEn fazla 1024 bayt metin
Değiştiren metoteditMessageWidgetDataeditMessageWidgetData veya editSharedWidgetData
ÖrnekSüren bir oyun, sipariş durumuAnket 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

YerNasıl gelirİstekler (allow_queries ile)Üretimde
Botla özel sohbetsendWidget, sendSharedWidgetDokunuşta ve arka plandaEvet
Normal grup veya süper grupsendWidgetYalnızca dokunuştaYalnızca test sunucusu
Kanallar hariç her sohbet, bot aracılığıylaInline mod (InputWidgetMessageContent, InputSharedWidgetMessageContent)Yalnızca dokunuştaYalnızca test sunucusu
İletilen mesaj (kanallar dahil)Kullanıcıların iletmesiyleDokunuşta, yalnızca paylaşılan widget'larYalnı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?

ÖzellikMini AppWidget
NeredeButon, menü veya bağlantıyla açılan bir WebViewMesaj balonunun içinde, sohbette hep görünür
KodSizin sunucunuzdaki bir web sayfasıMesajın içindeki en fazla 32 KB HTML, gönderilince sabit
MotorPlatformun WebView'ıQuickJS sandbox'ı, çizimi Telegram uygulaması yapar
AğTüm webYok
Botla iletişimİmzalı initData ile kendi backend'inizTelegramWidget.request() → widget_query güncellemesi
GirdiKlavye dahil her şeyDokunuş 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

  1. Bir bot oluşturun ve token'ını kopyalayın (Telegram bot nasıl yapılır, bot token nasıl alınır).
  2. Botun size yazabilmesi için ona /start gönderin ve chat id'nizi getUpdates ile alın.
  3. sendWidget metodunu çağırın. html parametresi 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 Message
const 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 Message

Bu 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:

  1. Bot widget'ı allow_queries: true ile gönderir.
  2. Dokunulduğunda widget, 1–64 bayt veriyle TelegramWidget.request("like") çağırır.
  3. Bot id, from, chat, message_id ve data içeren bir widget_query güncellemesi alır (paylaşılan widget'ın iletilmiş kopyasından gelirse shared_widget_query). allowed_updates kullanıyorsanız iki türü de ekleyin.
  4. 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 data gönderir.
  5. Herkesin gördüğünü değiştirmek için bot editMessageWidgetData (veya editSharedWidgetData) çağırır; widget chatDataChanged / publicDataChanged olayı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

NeSınır
HTML32768 bayt; zlib seviye 9 sonrası 4096 bayt
chat_data, public_dataHer biri 1024 bayt
İstek verisi / yanıt verisi1–64 bayt / en fazla 1024 bayt
İsteği yanıtlama süresi15 saniye
İsteklerKullanıcı ve bot başına 5 saniyede 5
Balon boyutuGenişlik 200 px'ten balonun azami genişliğine, yükseklik 50–600 px; fazlası kırpılır
Paylaşılan widget düzenlemeleriSaniyede 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ı

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

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.

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.