TelegramWidget JavaScript API: özellikler, olaylar, hata kodları ve sınırlar
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;isForwardveyachatType: "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
| Özellik | Tür | Açıklama |
|---|---|---|
profile | Integer | Uygulamanın uyguladığı widget profili: bu sürümde 1 |
colorScheme | String | Sohbetin şeması: light veya dark (ayrıca --tg-color-scheme) |
themeParams | Object | Balonun paleti, #rrggbb metinleri; anahtarlar Mini App'lerdeki themeParams ile aynı |
isActive | Boolean | Widget görünür (!document.hidden) |
isPreview | Boolean | Gönderilmeden önce gösterilen inline sonuç: dokunuş ve istek yok |
isForward | Boolean | İletilmiş bir kopya |
chatType | String | private, group, supergroup, channel; iletilen mesajda veya önizlemede null |
viewer | Object | Bakan 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 |
publicData | String | Paylaşılan durum, en fazla 1024 bayt veya null. Salt okunur |
chatData | String | Sohbet durumu, en fazla 1024 bayt veya null; iletilen mesajda hep null. Salt okunur |
contentSafeAreaInset | Object | top, right, bottom, left, cornerLeft, cornerRight: mesaj saatinin kapladığı alan |
wallet | Object | Telegram cüzdanı veya null (uygulamada cüzdan yok, istek izni yok, önizleme) |
HapticFeedback | Object | Dokunsal geri bildirim, aşağıya bakın |
TelegramWidget metotları
| Metot | Ne 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
| Olay | Ne zaman |
|---|---|
themeChanged | Sohbet teması değişti; colorScheme, themeParams ve CSS değişkenleri zaten güncel |
activated / deactivated | Widget görünür / gizli oldu (visibilitychange sonrasında) |
chatDataChanged | Bot sohbet durumunu değiştirdi; chatData zaten yeni. İletilen mesajda asla gelmez |
publicDataChanged | Bot 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 |
contentSafeAreaChanged | Mesaj 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'
);
});
| code | Anlamı |
|---|---|
NOT_ALLOWED | allow_queries yok, statik widget'ın iletilmiş kopyası, arka plan isteklerinin kapalı olduğu yerde dokunuş yok, önizleme veya istekleri iletmeyen bir uygulama |
BUSY | Bu widget'ın başka bir isteği veya cüzdan çağrısı sürüyor |
RATE_LIMITED | Sonuncusundan 5 saniye içinde yapılan arka plan çağrısı veya kullanıcı ve bot başına 5 saniyede 5 istekten fazlası |
TIMEOUT | Bot 15 saniyede yanıt vermedi (kapalı, yavaş veya widget_query / shared_widget_query almıyor) |
FAILED | Diğer her şey: bot engellendi veya silindi, mesaj yok, ağ hatası |
INVALID_ANSWER | Botun yanıtı sınırları aştı |
REJECTED, BAD_REQUEST | Yalnı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şken | Anlamı |
|---|---|
--tg-theme-bg-color, --tg-theme-text-color, --tg-theme-hint-color, --tg-theme-link-color | Balon arka planı, metin, ikincil metin, bağlantılar |
--tg-theme-button-color, --tg-theme-button-text-color | Uygulamanı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-scheme | light veya dark |
--tg-text-font-size, --tg-text-line-height, --tg-text-padding | Mesaj 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-opacity | Varsayılan <button>'ın kullandığı uygulama buton stili |
--tg-content-safe-area-inset-*, --tg-content-safe-area-corner-left / -right | Mesaj 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ı
- Form kontrolleri (
input,select,textarea); tek kontrol<button>'dır. Klavye olayı ve odak yoktur. - Tüm ağ API'leri (
fetch,XMLHttpRequest,WebSocketve diğerleriNetworkDisabledErrorfırlatır), harici script, stil, font ve görseller,locationvehistory. vhve yüksekliğe göreli diğer birimler,overflow: auto / scroll(hiddenolur),position: sticky,@font-face,:has(), CSS nesting.alert,confirm,prompt,navigator.clipboard(yerinecopyText),iframe,video,audio, WebGL.
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ır | Değer | Aşılınca |
|---|---|---|
| HTML | 32768 bayt; zlib seviye 9 sonrası 4096 bayt | INPUT_MEDIA_WIDGET_TOO_LARGE |
chat_data, public_data | Her biri 1024 bayt UTF-8 | INPUT_MEDIA_WIDGET_DATA_TOO_LARGE |
| İstek verisi | 1–64 bayt | Widget'ta TypeError |
| Yanıt verisi | 1024 bayt | WIDGET_RESULT_TOO_LARGE |
| Yanıt süresi | 15 saniye | TIMEOUT; geç yanıt: query is too old |
| İstekler | Kullanıcı ve bot başına 5 saniyede 5 | RATE_LIMITED |
| Paylaşılan widget düzenlemeleri | Saniyede 1; yenileme periyodu varsayılan 30 s, cache_time 5–3600 | Flood wait; 5'in altında invalid cache time specified |
| CPU | Saniyede 300 ms JavaScript; tek görevde 500 ms | Yavaşlatılır; widget durdurulur |
| Bellek | 8 MB | Widget durdurulur |
| DOM düğümleri | 2000 | Widget durdurulur |
| Zamanlayıcılar | 64 canlı zamanlayıcı | RangeError |
localStorage, sessionStorage | Mesaj başına alan başına 4 KB | QuotaExceededError |
| Balon | Genişlik 200 px'ten balonun azamisine, yükseklik 50–600 px | Kı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.
Depolama, bağlantılar, titreşim ve copyText
- Web Storage bu cihazdaki bu mesaja aittir. Uygulama yeniden başlasa da kalır, bota asla gönderilmez ve cihazlar arasında eşitlenmez.
setItem'ıtry/catchiçine alın. - Bağlantılar:
openLink,openTelegramLink,copyTextverequestgerçek bir dokunuş ister: onlarıclickhandler'ında senkron çağırın,awaitveya zamanlayıcı sonrasında değil. Bir dokunuş böyle tek bir çağrının kilidini açar. Geçersiz URLTypeErrorfırlatır; dokunulan bir<a href="https://…">da çalışır. - Titreşimler yalnızca widget görünürken çalar, bir seferde en fazla 5 ve saniyede 10; dokunuş sırasında ve sonraki 5 saniye serbesttir. Masaüstü ve web uygulamaları hiçbir şey çalmaz.
- copyText 1–256 karakter kopyalar ve her zaman kopyalanan metni içeren bir bildirim gösterir.
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ı
| Hata | Neden |
|---|---|
INPUT_MEDIA_WIDGET_TOO_LARGE | HTML 32768 baytı veya sıkıştırılmış hâli 4096 baytı aşıyor |
INPUT_MEDIA_WIDGET_HTML_INVALID | html içinde geçersiz UTF-8 veya NUL karakteri |
INPUT_MEDIA_WIDGET_DATA_TOO_LARGE | chat_data veya public_data 1024 baytı aşıyor |
INPUT_MEDIA_WIDGET_DATA_INVALID / WIDGET_DATA_INVALID | Gönderirken / düzenlerken geçersiz durum metni |
message is not modified | Hiç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.
İ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.
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?