Web siteniz için Telegram widget'ları: Telegram ile giriş, gönderi gömme, yorumlar ve paylaş butonu
Telegram, web siteleri için dört widget sunar: Telegram Login (kullanıcılar Telegram hesabıyla giriş yapar), gönderi widget'ı (herkese açık bir kanal ya da gruptan mesaj gömme), tartışma widget'ı (kanal gönderisinin yorumlarını gösterme) ve paylaş butonu. Hepsi kendi HTML'inize yapıştırdığınız küçük kod parçalarıdır. Bunlar, Bot API 10.4 ile botların sohbet mesajlarına gönderdiği etkileşimli widget'lar değildir; onlar için bot mesajlarındaki Telegram widget'ları rehberine bakın.
Web siteleri için Telegram widget'larına genel bakış
| Widget | Ne yapar | Bot gerekir mi? | Kod nereden alınır |
|---|---|---|---|
| Telegram Login | Telegram hesabıyla kayıt ve giriş (OpenID Connect) | Evet; ayrıca @BotFather'dan Allowed URLs ve Client ID | core.telegram.org/bots/telegram-login üzerindeki yapılandırıcı |
| Login Widget (eski) | Eski iframe tabanlı giriş butonu, artık arşivde | Evet; alan adı /setdomain ile bağlanmış olmalı | core.telegram.org/widgets/login-legacy |
| Gönderi widget'ı | Herkese açık kanal veya gruptan bir mesajı gömer | Hayır | t.me bağlantısı → EMBED ya da gönderi yapılandırıcısı |
| Tartışma widget'ı | Kanal gönderisini yorumlarıyla birlikte gösterir | Hayır | Tartışma yapılandırıcısı |
| Paylaş butonu | Ziyaretçinin bağlantınızı bir sohbete, gruba, kanala veya Kayıtlı Mesajlar'a göndermesini sağlar | Hayır | Paylaş oluşturucusu ya da düz bir bağlantı |
Telegram Login: yeni "Telegram ile giriş" (OpenID Connect)
Güncel Telegram Login, bir JavaScript kütüphanesi ile PKCE'li Authorization Code Flow kullanan standart bir OpenID Connect sağlayıcısından oluşur. Kütüphanenin butonunu, OIDC uyumlu herhangi bir kütüphaneyi veya kimlik platformunu (Telegram örnek olarak Keycloak, Authentik ve Auth0'ı sayıyor) ya da iOS ve Android için yerel SDK'ları kullanabilirsiniz.
- Sitenizi temsil edecek bir bot hazırlayın (Telegram bot oluşturma rehberi). Kullanıcılar onay penceresinde botun adını ve profil fotoğrafını görür; bunları sitenizin adı ve logosuyla uyumlu yapın.
- Allowed URLs kaydedin. @BotFather mini uygulamasını açın, botu seçin, ardından Login Widget'a girin. Butonu yerleştirdiğiniz origin'leri (ör.
https://example.com) ve OIDC yönlendirme URI'lerinizi (ör.https://example.com/auth/callback) ekleyin. Telegram girişleri ve yönlendirmeleri yalnızca önceden kaydedilmiş bu adresler için işler. - Client ID ve Client Secret değerlerini kaydedin; aynı bölümde gösterilirler. Secret yalnızca sunucuda kalmalı.
- Butonu sayfanıza ekleyin.
- ID token'ı sunucuda doğrulayın; bundan önce hiçbir kullanıcı verisine güvenmeyin.
Resmi yapılandırıcının ürettiği kod şuna benzer (data-request-access isteğe bağlıdır: write botunuzun kullanıcıya mesaj yazmasına izin verir, phone doğrulanmış telefon numarasını ister):
<script async src="https://oauth.telegram.org/js/telegram-login.js?6" data-client-id="123456789" data-onauth="onTelegramAuth(data)" data-request-access="write"></script>
<button class="tg-auth-button">Telegram ile giriş yap</button>
<script>
function onTelegramAuth(data) {
if (data.error) return console.warn(data.error);
// data.id_token değerini sunucunuza gönderin ve orada doğrulayın
fetch('/auth/telegram', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({id_token: data.id_token})
});
}
</script>
Callback'e id_token (OIDC JWT), user (çözülmüş claim'ler) ya da error gelir. Kütüphanenin bir JS API'si de var: Telegram.Login.init(InitOptions, callback), Telegram.Login.open([callback]) ve Telegram.Login.auth(InitOptions, callback); seçenekler client_id, scope, lang ve nonce'tur (nonce, tekrar oynatma saldırılarına karşı id_token'a yazılan, sunucuda üretilmiş rastgele bir dizedir).
Popup ve COOP:telegram-login.jsbir popup penceresiyle haberleşir. SitenizCross-Origin-Opener-Policy: same-originbaşlığı gönderiyorsa giriş başarısız olur; başlığı kaldırın veyasame-origin-allow-popupskullanın.
Scope'lar ve OIDC uç noktaları
| Scope | Ne verir | Claim'ler |
|---|---|---|
openid | Zorunlu. Benzersiz kimlik ve giriş zamanı | sub, iss, iat, exp |
profile | Kullanıcı ID'si, ad, kullanıcı adı, fotoğraf URL'si | id, name, preferred_username, picture |
phone | Kullanıcı onayıyla doğrulanmış telefon numarası | phone_number |
telegram:bot_access | Girişten sonra botunuz kullanıcıya mesaj yazabilir | — |
Bir OIDC istemcisi için discovery belgesi https://oauth.telegram.org/.well-known/openid-configuration, response type code ve S256 ile PKCE kullanın. Akışı elle yazıyorsanız uç noktalar şunlardır: https://oauth.telegram.org/auth, https://oauth.telegram.org/token (Basic auth base64(client_id:client_secret) ile sunucu tarafında POST) ve https://oauth.telegram.org/.well-known/jwks.json. Ayrı bir UserInfo uç noktası yoktur: tüm veriler ID token içindedir, kütüphaneniz userinfo isteği bekliyorsa bunu atlayacak şekilde ayarlayın.
ID token'ı doğrulama
JWT imzasını JWKS uç noktasındaki anahtarlarla doğrulayın; ardından iss değerinin https://oauth.telegram.org olduğunu, aud değerinin bot ID'nizle (client_id olarak verdiğiniz değer) eşleştiğini ve exp süresinin dolmadığını kontrol edin. Token'lar varsayılan olarak RS256 ile imzalanır; @BotFather'da Login Widget > Advanced altından ES256, EdDSA ve ES256K seçilebilir (EdDSA ve ES256K yalnızca openid scope'una izin verir). jose kütüphanesiyle bir Node.js örneği:
import { createRemoteJWKSet, jwtVerify } from 'jose';
const JWKS = createRemoteJWKSet(new URL('https://oauth.telegram.org/.well-known/jwks.json'));
export async function verifyTelegramIdToken(idToken) {
const { payload } = await jwtVerify(idToken, JWKS, {
issuer: 'https://oauth.telegram.org',
audience: '123456789' // Client ID'niz (bot ID)
});
return payload; // sub, id, name, preferred_username, picture, phone_number...
}
Klasik Telegram Login Widget (eski sürüm)
Pek çok site hâlâ orijinal, iframe tabanlı Login Widget'ı kullanıyor. Belgeleri arşivlendiği için yeni projelerde yukarıdaki akışı seçin; mevcut bir entegrasyonun bakımını yapıyorsanız eski sürüm şöyle çalışır.
- Sitenizin alan adını bota bağlamak için @BotFather'a
/setdomaingönderin. - Script'i ekleyin. Callback ile:
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-login="your_bot" data-size="large" data-onauth="onTelegramAuth(user)" data-request-access="write"></script>
<script type="text/javascript">
function onTelegramAuth(user) {
alert('Giriş yapıldı: ' + user.first_name + ' ' + user.last_name + ' (' + user.id + (user.username ? ', @' + user.username : '') + ')');
}
</script>
data-onauth yerine data-auth-url="https://example.com/auth/telegram" da verebilirsiniz: kullanıcı bu adrese id, first_name, last_name, username, photo_url, auth_date ve hash query parametreleriyle yönlendirilir. Yapılandırıcıdaki diğer seçenekler: data-size (large, medium, small), data-userpic="false", data-radius ve data-request-access="write".
Hash'i sunucuda kontrol edin
Doğrulamadan veriye asla güvenmeyin. Algoritma: hash dışındaki tüm alanları alın, alfabetik sıralayın ve key=value biçiminde satır sonuyla (\n) birleştirerek data-check-string'i elde edin; gizli anahtar bot token'ının SHA256 özetidir (ham baytlar); data-check-string'in bu anahtarla HMAC-SHA-256 değerini hesaplayıp hex hâlini hash ile karşılaştırın. Ardından auth_date'in (Unix zaman damgası) yeni olduğunu kontrol edin. Yalnızca Telegram'ın gönderdiği alanları kullanın, kendi query parametrelerinizi katmayın.
import hashlib
import hmac
import time
def check_telegram_auth(data: dict, bot_token: str, max_age: int = 86400) -> bool:
fields = {k: v for k, v in data.items() if k != "hash"}
data_check_string = "\n".join(f"{k}={fields[k]}" for k in sorted(fields))
secret_key = hashlib.sha256(bot_token.encode()).digest()
calc_hash = hmac.new(secret_key, data_check_string.encode(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(calc_hash, str(data.get("hash", ""))):
return False
return time.time() - int(fields["auth_date"]) <= max_age
# Flask: check_telegram_auth(request.args.to_dict(), BOT_TOKEN)const crypto = require('crypto');
function checkTelegramAuth(data, botToken, maxAgeSec = 86400) {
const { hash, ...fields } = data;
const dataCheckString = Object.keys(fields).sort()
.map((k) => `${k}=${fields[k]}`)
.join('\n');
const secretKey = crypto.createHash('sha256').update(botToken).digest();
const calcHash = crypto.createHmac('sha256', secretKey).update(dataCheckString).digest('hex');
if (typeof hash !== 'string' || hash.length !== calcHash.length) return false;
if (!crypto.timingSafeEqual(Buffer.from(calcHash), Buffer.from(hash))) return false;
return Date.now() / 1000 - Number(fields.auth_date) <= maxAgeSec;
}
// Express: checkTelegramAuth(req.query, process.env.BOT_TOKEN)Uyuşmazlığın en sık nedeni yanlış token'dır. Sunucudaki token'ın giriş botuna ait olduğunu Bot API Tester'da getMe ile kontrol edin: dönen username, data-telegram-login değerine eşit olmalı. Token'ı bulmanız ya da yenilemeniz gerekiyorsa bot token rehberine bakın. Bu kontrolün Mini App initData doğrulamasından farklı olduğunu unutmayın; orada anahtar HMAC ve WebAppData dizesiyle türetilir.
Telegram gönderisini siteye gömme
Herkese açık bir kanal veya gruptaki herhangi bir mesajı gömebilirsiniz. Mesajın t.me bağlantısını (ör. t.me/durov/43) tarayıcıda açıp < > EMBED'e tıklayın ya da bağlantıyı gönderi widget yapılandırıcısına yapıştırın. Sonuç tek bir script etiketidir:
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-post="durov/43" data-width="100%"></script>
Yapılandırıcıdaki seçenekler: genişlik (data-width, varsayılan 100%), yazar fotoğrafı (her zaman göstermek için data-userpic="true", gizlemek için "false", otomatik için hiç yazmayın), vurgu rengi (13B4C6 gibi hex değerle data-color) ve koyu tema (data-dark="1"; renk seçildiğinde yapılandırıcı data-dark-color da ekleyebilir).
Tartışma widget'ı: sitenizde Telegram yorumları
Tartışma widget'ı, herkese açık bir kanal gönderisini yorumlarıyla birlikte gösterir. Yorumları açık bir gönderinin bağlantısını verin:
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-discussion="contest/198" data-comments-limit="5"></script>
Yalnızca kanalı da verebilirsiniz (data-telegram-discussion="your_channel"). Bu durumda her makale sayfası, o sayfaya bağlantı veren kanal gönderisinin tartışmasını gösterir; bağlantıyı kanalda paylaştığınız anda görünür. Bu mod için sayfanızın head bölümünde sayfanın kanonik adresiyle <link rel="canonical" href="%page_url%"> bulunmalı. Seçenekler: yorum sayısı (data-comments-limit, yapılandırıcıda 3–50), data-height, farklı isim renkleri için data-colorful="1", data-color ve data-dark="1".
Telegram paylaş butonu
Ziyaretçi paylaş butonuna bastığında Telegram bir sohbet, grup veya kanal seçmesini ister ve isteğe bağlı metni göndermeden önce düzenlemesine izin verir. core.telegram.org/widgets/share adresindeki oluşturucu şu kodu üretir:
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-share-url="https://example.com/article" data-comment="Şuna bir bakın!" data-size="large"></script>
Orta boy buton için data-size'ı yazmayın; data-text="notext" yalnızca simgeyi gösterir. Kendi tasarımınız için iki değeri de URL-encode ederek https://t.me/share/url?url={url}&text={text} adresine bağlantı verin:
<a href="https://t.me/share/url?url=https%3A%2F%2Fexample.com%2Farticle&text=%C5%9Euna%20bir%20bak%C4%B1n%21">Telegram'da paylaş</a>
const shareUrl = 'https://t.me/share/url?url=' + encodeURIComponent(location.href)
+ '&text=' + encodeURIComponent(document.title);
document.querySelector('#tg-share').href = shareUrl;
Sorun giderme
- Eski widget "Bot domain invalid" gösteriyor. Alan adı bota bağlı değil. O bot için @BotFather'a
/setdomaingönderin ve sayfanın tam alan adını girin. - Yeni giriş hiçbir şey yapmıyor veya reddediliyor. Sayfanın origin'i ya da yönlendirme URI'si @BotFather'daki Allowed URLs listesinde yok veya
Cross-Origin-Opener-Policy: same-originbaşlığı popup'ı engelliyor. - Widget görünmüyor.
telegram-widget.js,telegram.orgadresinden yüklenir ve bir iframe ekler: gönderi, tartışma ve paylaş butonu içint.me'den, eski giriş içinoauth.telegram.org'dan. Katı bir Content-Security-Policy (script-src,frame-src) veya reklam engelleyici bunları durdurabilir. - Hash uyuşmuyor. Yanlış bot token'ı, anahtar olarak SHA256 özeti yerine token'ın kendisini kullanmak, data-check-string'e fazladan alan (kendi query parametreleriniz) eklemek, değiştirilmiş alan değerleri veya yanlış ayırıcı.
&değil\nkullanın. - Gönderi gömülemiyor. Yalnızca herkese açık kanal ve grupların mesajları gömülebilir; özel sohbetlerin herkese açık t.me bağlantısı yoktur.
- Makale sayfasında tartışma boş. Sayfada canonical link etiketi olduğunu ve kanalda paylaştığınız bağlantının tam olarak bu kanonik adrese işaret ettiğini kontrol edin.
Sonraki adımlar
- Giriş penceresinde sitenizi temsil edecek bir Telegram botu oluşturun.
- Eski hash kontrolü için gereken bot token'ını bulun, kontrol edin ve iptal edin.
- Bot mesajlarındaki Telegram widget'ları: Bot API 10.4'ün HTML widget'ları, tamamen ayrı bir özellik.
- Resmi belgeler: core.telegram.org/widgets.
Sık sorulan sorular
Siteme Telegram ile giriş butonu nasıl eklerim?
Bir bot seçin, @BotFather mini uygulamasını açın, botu ve ardından Login Widget bölümünü seçin; sitenizin origin'ini ve yönlendirme URI'lerini Allowed URLs olarak ekleyip Client ID'yi kopyalayın. Sonra sayfanıza data-client-id içeren telegram-login.js kodunu ekleyin ve dönen id_token'ı sunucuda doğrulayın.
Eski Telegram Login Widget hâlâ destekleniyor mu?
Belgeleri core.telegram.org/widgets/login-legacy adresinde arşivlenmiş durumda. Telegram artık Telegram Login kütüphanesini ve OpenID Connect akışını ana giriş yöntemi olarak anlatıyor; yeni projelerde bunları tercih edin.
Telegram Login Widget verisini sunucuda nasıl doğrularım?
Eski widget için hash dışındaki tüm alanları alfabetik sıralayıp key=value satırlarını \n ile birleştirin. Bu metnin HMAC-SHA-256 değerini SHA256(bot_token) anahtarıyla hesaplayın, hex sonucu hash ile karşılaştırın ve auth_date'i kontrol edin. Yeni girişte id_token JWT'sini Telegram'ın JWKS anahtarlarıyla doğrulayın.
Telegram gönderisi siteye nasıl gömülür?
Gönderinin t.me bağlantısını (ör. t.me/durov/43) tarayıcıda açıp EMBED'e tıklayın ya da core.telegram.org/widgets/post adresindeki yapılandırıcıyı kullanın. Yalnızca herkese açık kanal ve grupların gönderileri gömülebilir.
Özel tasarımlı Telegram paylaş butonu nasıl yapılır?
https://t.me/share/url?url={url}&text={text} adresine bağlantı verin; iki değer de URL-encode edilmelidir, JavaScript'te encodeURIComponent ile. Metin isteğe bağlıdır ve kullanıcı göndermeden önce düzenleyebilir.
İ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.
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.
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?