Telegram Bot API

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

· 10 dk okuma

Telegram widget API'si, Bot API 10.4 widget'larının Telegram uygulamasından aldığı window.TelegramWidget nesnesi ile Bot API tarafındaki widget_query güncellemeleri ve answerWidgetQuery metodundan oluşur. Bu başvuru kılavuzu TelegramWidget'ın tüm özelliklerini, metotlarını, olaylarını ve hata kodlarını, CSS değişkenlerini, hareket kurallarını ve sınırları resmi Telegram widget belgelerine dayanarak listeler.

Kullanılabilirlik: üretim ortamında widget'lar şu an yalnızca botla olan özel sohbette çalışır ve iletilemez (korumalı içerikle gönderilir). Gruplar, inline mod ve iletmeler yalnızca test sunucusunda çalışır; isForward veya chatType: "group" gibi özellikler önce orada anlam kazanır.

Widget'larla yeni mi tanışıyorsunuz? Telegram widget nedir rehberiyle ve widget örnekleriyle başlayın.

TelegramWidget nesnesi nasıl gelir?

Widget'lar script etiketi gerektirmez. Telegram içinde window.TelegramWidget, widget'ın ilk script'i çalışmadan önce vardır; Telegram dışında (sıradan bir tarayıcıda) undefined'dır. Bir profil içinde sonradan eklenen metotlar typeof ile tespit edilir:

const W = window.TelegramWidget;   // normal tarayıcıda undefined
if (W && typeof W.setResizeAnchor === 'function') W.setResizeAnchor('bottom');

function render() {
  let state = null;
  try { state = JSON.parse(W.chatData); } catch (e) {}
  // durumdan çiz; null "henüz durum yok" demektir
}
if (W) W.onEvent('chatDataChanged', render);
render();

TelegramWidget özellikleri

ÖzellikTürAçıklama
profileIntegerUygulamanın uyguladığı widget profili: bu sürümde 1
colorSchemeStringSohbetin şeması: light veya dark (ayrıca --tg-color-scheme)
themeParamsObjectBalonun paleti, #rrggbb metinleri; anahtarlar Mini App'lerdeki themeParams ile aynı
isActiveBooleanWidget görünür (!document.hidden)
isPreviewBooleanGönderilmeden önce gösterilen inline sonuç: dokunuş ve istek yok
isForwardBooleanİletilmiş bir kopya
chatTypeStringprivate, group, supergroup, channel; iletilen mesajda veya önizlemede null
viewerObjectBakan kullanıcının id, first_name, last_name, username, is_premium alanları; yalnızca widget'ın istek gönderebildiği yerde, aksi hâlde null
publicDataStringPaylaşılan durum, en fazla 1024 bayt veya null. Salt okunur
chatDataStringSohbet durumu, en fazla 1024 bayt veya null; iletilen mesajda hep null. Salt okunur
contentSafeAreaInsetObjecttop, right, bottom, left, cornerLeft, cornerRight: mesaj saatinin kapladığı alan
walletObjectTelegram cüzdanı veya null (uygulamada cüzdan yok, istek izni yok, önizleme)
HapticFeedbackObjectDokunsal geri bildirim, aşağıya bakın

TelegramWidget metotları

MetotNe yapar
request(data[, options])Bota 1–64 bayt gönderir. { result } (botun yanıtı veya null) döndüren bir Promise verir ya da WidgetRequestError ile reddedilir. Yalnızca dokunuş handler'ında veya izin verilen yerde arka planda. options { wallet: true } olabilir
watchPublicData() / unwatchPublicData()Paylaşılan widget ekrandayken paylaşılan durumun canlı sorgulanmasını başlatır / durdurur. Statik widget'ta ve önizlemede etkisizdir
copyText(text)Dokunuşta 1–256 karakter kopyalar; uygulama metni içeren bir bildirim (toast) gösterir
openLink(url)Kullanıcı onayladıktan sonra bir https: URL'si açar (≤ 256 karakter, t.me olmayan)
openTelegramLink(url)Bir https://t.me/… bağlantısını, mesajdaki bir bağlantıya dokunulmuş gibi Telegram içinde açar
setResizeAnchor(edge)top (varsayılan) veya bottom: yükseklik değişince balonun hangi kenarı yerinde kalır
ready()İsteğe bağlı: uygulamaya ilk durumun çizildiğini bildirir
onEvent(type, handler) / offEvent(type, handler)Olay handler'ı ekler / kaldırır (olay türü başına en fazla 16)
isProfileAtLeast(n)profile >= n döndürür

isProfileAtLeast, request ve cüzdan metotları dışındaki tüm metotlar senkrondur. HapticFeedback şunları sunar: impactOccurred(style) (light, medium, heavy, rigid, soft), notificationOccurred(type) (error, success, warning) ve selectionChanged(). sendMessage yoktur ve widget kendi widget_id değerini bilmez.

Olaylar

OlayNe zaman
themeChangedSohbet teması değişti; colorScheme, themeParams ve CSS değişkenleri zaten güncel
activated / deactivatedWidget görünür / gizli oldu (visibilitychange sonrasında)
chatDataChangedBot sohbet durumunu değiştirdi; chatData zaten yeni. İletilen mesajda asla gelmez
publicDataChangedBot paylaşılan durumu değiştirdi; ekrandaki paylaşılan widget için yalnızca izleme açıkken. İkisi birden değişirse chatDataChanged'den sonra gelir
contentSafeAreaChangedMesaj saatinin kapladığı alan değişti (caption eklendi, kaldırıldı veya taşındı, "düzenlendi" işareti)

Handler'lar argümansız ve this TelegramWidget'a bağlı olarak çağrılır; yeni değerleri nesneden okuyun.

WidgetRequestError hata kodları

button.addEventListener('click', () => {
  status.textContent = 'Gönderiliyor…';
  TelegramWidget.request('vote:2').then(
    (answer) => { status.textContent = answer.result ?? 'Tamam'; },
    (error) => { status.textContent = 'Hata: ' + error.code; },  // error.name === 'WidgetRequestError'
  );
});
codeAnlamı
NOT_ALLOWEDallow_queries yok, statik widget'ın iletilmiş kopyası, arka plan isteklerinin kapalı olduğu yerde dokunuş yok, önizleme veya istekleri iletmeyen bir uygulama
BUSYBu widget'ın başka bir isteği veya cüzdan çağrısı sürüyor
RATE_LIMITEDSonuncusundan 5 saniye içinde yapılan arka plan çağrısı veya kullanıcı ve bot başına 5 saniyede 5 istekten fazlası
TIMEOUTBot 15 saniyede yanıt vermedi (kapalı, yavaş veya widget_query / shared_widget_query almıyor)
FAILEDDiğer her şey: bot engellendi veya silindi, mesaj yok, ağ hatası
INVALID_ANSWERBotun yanıtı sınırları aştı
REJECTED, BAD_REQUESTYalnızca cüzdan çağrıları: kullanıcı reddetti veya cüzdan işlemi ya da payload'u geri çevirdi

Boş veya 64 bayttan uzun veri, hiçbir şey gönderilmeden TypeError fırlatır.

Bot tarafı: widget_query ve answerWidgetQuery

Orijinal mesajdan gelen istek Update içinde widget_query olarak, iletilmiş paylaşılan widget'tan gelen ise shared_widget_query olarak gelir. getUpdates veya setWebhook'a allowed_updates veriyorsanız ikisini de ekleyin.

{
  "update_id": 100000001,
  "widget_query": {
    "id": "8123456789012345678",
    "from": {"id": 123456789, "is_bot": false, "first_name": "Alice"},
    "chat": {"id": 123456789, "type": "private", "first_name": "Alice"},
    "message_id": 4242,
    "chat_instance": "901234567890123456",
    "type": {"type": "data"},
    "data": "refresh"
  }
}

Bot aracılığıyla gönderilmiş bir mesajdan gelen widget_query'de chat ve message_id yerine inline_message_id ve chat_type bulunur; paylaşılan widget'larda widget_id da vardır. shared_widget_query yalnızca id, from, type, data ve widget_id içerir. Her isteği answerWidgetQuery ile yanıtlayın (widget_query_id, isteğe bağlı en fazla 1024 baytlık data); durumu ayrıca editMessageWidgetData veya editSharedWidgetData ile değiştirin. from ve widget_id Telegram tarafından doldurulur ve taklit edilemez, ama data'yı güvenilmeyen girdi olarak ele alın.

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/answerWidgetQuery" \
  -H "Content-Type: application/json" \
  -d '{"widget_query_id": "8123456789012345678", "data": "{\"n\":5,\"r\":3}"}'

CSS değişkenleri

DeğişkenAnlamı
--tg-theme-bg-color, --tg-theme-text-color, --tg-theme-hint-color, --tg-theme-link-colorBalon arka planı, metin, ikincil metin, bağlantılar
--tg-theme-button-color, --tg-theme-button-text-colorUygulamanın ana butonu
--tg-theme-secondary-bg-color, --tg-theme-accent-text-color, --tg-theme-subtitle-text-color, --tg-theme-destructive-text-color, --tg-theme-section-separator-colorİkinci yüzey, vurgu, alt başlıklar, yıkıcı işlemler, ayırıcılar
--tg-color-schemelight veya dark
--tg-text-font-size, --tg-text-line-height, --tg-text-paddingMesaj metni boyutu (yaklaşık 15px), satır yüksekliği (yaklaşık 1.35), balon metin boşluğu (yaklaşık 8px 12px)
--tg-button-bg, --tg-button-text, --tg-button-radius, --tg-button-font, --tg-button-padding, --tg-button-height, --tg-button-pressed-opacity, --tg-button-disabled-opacityVarsayılan <button>'ın kullandığı uygulama buton stili
--tg-content-safe-area-inset-*, --tg-content-safe-area-corner-left / -rightMesaj saatinin çizildiği şerit (env(safe-area-inset-*) ile aynı)

Uygulama bunları kök öğede !important ile ayarlar; yalnızca kendi öğelerinizde yeniden tanımlayabilirsiniz. prefers-color-scheme, light-dark() ve color-scheme sistemi değil sohbet temasını izler.

Hareketler ve touch-action

Dokunuş ve çift dokunuş her zaman widget'ındır; dikey sürükleme her zaman sohbeti kaydırır (widget pointercancel alır). Basılı tutma ve yatay sürükleme, öğe bazında CSS touch-action ile sahiplenilir: auto bunları sohbete bırakır (mesaj menüsü, kaydırarak yanıtlama), pan-y yatay sürüklemeyi widget'a verir, none basılı tutmayı (contextmenu) ve yatay sürüklemeyi verir. Pratik kural: basılı tutulan buton, oyun kontrolü veya canvas için touch-action: none, yatay slider veya carousel için pan-y, geri kalan her yerde auto. Pointer olaylarını kullanın; touch olayları gelmez. Kontrolleri baştaki 20 px'ten uzak tutun, o şerit hiçbir zaman sahiplenilemez.

Widget profilinin kaldırdıkları

Kaldırılan özellikler widget'ı bozmaz: öğe, bildirim veya olay atılır, gerisi çalışmaya devam eder. CSS.supports() ve @supports profile göre yanıt verir.

Telegram widget sınırları

SınırDeğerAşılınca
HTML32768 bayt; zlib seviye 9 sonrası 4096 baytINPUT_MEDIA_WIDGET_TOO_LARGE
chat_data, public_dataHer biri 1024 bayt UTF-8INPUT_MEDIA_WIDGET_DATA_TOO_LARGE
İstek verisi1–64 baytWidget'ta TypeError
Yanıt verisi1024 baytWIDGET_RESULT_TOO_LARGE
Yanıt süresi15 saniyeTIMEOUT; geç yanıt: query is too old
İsteklerKullanıcı ve bot başına 5 saniyede 5RATE_LIMITED
Paylaşılan widget düzenlemeleriSaniyede 1; yenileme periyodu varsayılan 30 s, cache_time 5–3600Flood wait; 5'in altında invalid cache time specified
CPUSaniyede 300 ms JavaScript; tek görevde 500 msYavaşlatılır; widget durdurulur
Bellek8 MBWidget durdurulur
DOM düğümleri2000Widget durdurulur
Zamanlayıcılar64 canlı zamanlayıcıRangeError
localStorage, sessionStorageMesaj başına alan başına 4 KBQuotaExceededError
BalonGenişlik 200 px'ten balonun azamisine, yükseklik 50–600 pxKırpılır

Durdurulan widget son karesini "Widget stopped" rozetiyle korur ve yeniden gösterildiğinde baştan kurulur; art arda iki çökmeden sonra uygulama yeniden başlayana kadar durdurulmuş kalır.

Kısaca TON cüzdanıyla ödeme

Widget, TON Connect biçimlerini kullanarak kullanıcıdan Telegram'ın yerleşik cüzdanıyla ödeme isteyebilir. Ödeme butonunu yalnızca TelegramWidget.wallet null değilken çizin. Dokunuşta widget request(data, { wallet: true }) gönderir; botun aldığı isteğin type alanı {"type": "data", "wallet_card": …} olur ve bot taze bir işlemle yanıt verir. Yanıtın handler'ında widget, 10 saniye içinde ikinci bir dokunuş gerektirmeyen wallet.sendTransaction()'ı çağırır:

TelegramWidget.request('pay:42', { wallet: true })
  .then((a) => TelegramWidget.wallet.sendTransaction(JSON.parse(a.result), 'paid:42'))
  .then((a) => show(a.result), (e) => showError(e.code));

Ardından bot, mesaj hash'ini içeren sent_transaction türünde bir istek alır ve işlemi zincir üzerinde doğrulamalıdır. TIMEOUT sonrasında ödeme gerçekleşmiş olabilir; yeniden ödeme yapmak yerine siparişin durumunu bota sorun.

Widget'lar için Bot API hataları

HataNeden
INPUT_MEDIA_WIDGET_TOO_LARGEHTML 32768 baytı veya sıkıştırılmış hâli 4096 baytı aşıyor
INPUT_MEDIA_WIDGET_HTML_INVALIDhtml içinde geçersiz UTF-8 veya NUL karakteri
INPUT_MEDIA_WIDGET_DATA_TOO_LARGEchat_data veya public_data 1024 baytı aşıyor
INPUT_MEDIA_WIDGET_DATA_INVALID / WIDGET_DATA_INVALIDGönderirken / düzenlerken geçersiz durum metni
message is not modifiedHiçbir şeyi değiştirmeyen düzenleme; başarı sayın

Metotları kendi token'ınızla Bot API Tester'da deneyin ve sendWidget parametrelerine göz atın. Bot token'ınız yoksa Telegram bot token nasıl alınır rehberine bakın; 10.4 ile gelen diğer metotlar metot başvurusunda.

Sık sorulan sorular

TelegramWidget'ı kullanmak için bir script eklemem gerekir mi?

Hayır. Telegram içinde window.TelegramWidget, widget'ın ilk script'i çalışmadan önce durum, tema ve bağlamla birlikte hazırdır. Telegram dışında undefined'dır; widget'ı tarayıcıda açacaksanız varlığını kontrol edin.

WidgetRequestError NOT_ALLOWED ne anlama gelir?

Mesaj istek gönderemez: widget allow_queries olmadan gönderilmiş, statik widget'ın iletilmiş kopyası veya bir önizleme olabilir ya da arka plan isteklerinin kapalı olduğu yerde request() dokunuş dışında çağrılmıştır.

Bot bir widget_query'yi ne kadar sürede yanıtlamalı?

15 saniye içinde, answerWidgetQuery ile. Sonrasında widget'ın promise'i TIMEOUT ile reddedilir, geç gelen yanıt query is too old ile geri çevrilir. Bir şey ters gitse bile her isteği yanıtlayın.

Widget kendi chatData veya publicData değerini değiştirebilir mi?

Hayır. İkisi de widget içinde salt okunurdur. Durumu yalnızca bot sendWidget, editMessageWidgetData veya editSharedWidgetData ile yazar; widget yalnızca TelegramWidget.request() ile bottan isteyebilir.

TelegramWidget.sendMessage diye bir metot var mı?

Hayır. Widget'larda sendMessage yoktur: kullanıcı adına sohbete hiçbir şey gönderilmez. Widget yalnızca botuna istek gönderebilir, metin kopyalayabilir, bağlantı açabilir ve titreşim çalabilir.

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.

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.

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?