Telegram Bot API

Web siteniz için Telegram widget'ları: Telegram ile giriş, gönderi gömme, yorumlar ve paylaş butonu

· 9 dk okuma

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ış

WidgetNe yaparBot gerekir mi?Kod nereden alınır
Telegram LoginTelegram hesabıyla kayıt ve giriş (OpenID Connect)Evet; ayrıca @BotFather'dan Allowed URLs ve Client IDcore.telegram.org/bots/telegram-login üzerindeki yapılandırıcı
Login Widget (eski)Eski iframe tabanlı giriş butonu, artık arşivdeEvet; 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ömerHayırt.me bağlantısı → EMBED ya da gönderi yapılandırıcısı
Tartışma widget'ıKanal gönderisini yorumlarıyla birlikte gösterirHayırTartışma yapılandırıcısı
Paylaş butonuZiyaretçinin bağlantınızı bir sohbete, gruba, kanala veya Kayıtlı Mesajlar'a göndermesini sağlarHayırPaylaş 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.

  1. 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.
  2. 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.
  3. Client ID ve Client Secret değerlerini kaydedin; aynı bölümde gösterilirler. Secret yalnızca sunucuda kalmalı.
  4. Butonu sayfanıza ekleyin.
  5. 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.js bir popup penceresiyle haberleşir. Siteniz Cross-Origin-Opener-Policy: same-origin başlığı gönderiyorsa giriş başarısız olur; başlığı kaldırın veya same-origin-allow-popups kullanın.

Scope'lar ve OIDC uç noktaları

ScopeNe verirClaim'ler
openidZorunlu. Benzersiz kimlik ve giriş zamanısub, iss, iat, exp
profileKullanıcı ID'si, ad, kullanıcı adı, fotoğraf URL'siid, name, preferred_username, picture
phoneKullanıcı onayıyla doğrulanmış telefon numarasıphone_number
telegram:bot_accessGiriş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.

  1. Sitenizin alan adını bota bağlamak için @BotFather'a /setdomain gönderin.
  2. 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

Sonraki adımlar

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.

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?