Telegram Bot API

Telegram Mini App nasıl test edilir: tarayıcıdaki mock'tan gerçek Telegram'a

· 7 dk okuma

Telegram Mini App testine normal bir tarayıcıda, taklit edilmiş (mock) bir Telegram.WebApp ile başlayın; ardından yerel derlemenizi HTTPS üzerinden yayınlayın, adresi @BotFather'a kaydedin ve uygulamayı DevTools bağlıyken Telegram içinde açın. Son adım sunucuda: kullanıcıya güvenmeden önce initData'yı doğrulayın. Aşağıda localhost'tan üretim kontrol listesine kadar tüm süreci bulacaksınız.

1. Adım: arayüzü normal tarayıcıda test edin

Telegram dışında Telegram.WebApp'in arkasında bir istemci yoktur: başlatma verisi, tema ya da yerel butonlar gelmez. Yine de kodunuz bu durumu tolere ediyorsa arayüzün büyük kısmını masaüstü tarayıcıda geliştirebilirsiniz:

const tg = window.Telegram?.WebApp;
const insideTelegram = Boolean(tg?.initData);

if (insideTelegram) {
  tg.ready();   // yükleme ekranını mümkün olduğunca erken gizleyin
  tg.expand();
} else {
  console.info("Telegram dışında: mock veriler kullanılıyor");
}

Sayfayı tema değişkenleri ve bir yedek değerle biçimlendirin, ör. var(--tg-theme-bg-color, #fff); böylece iki ortamda da okunaklı kalır.

Kod yazmadan her API çağrısının ne yaptığını görmek için Mini App Tester'ı açın. Normal tarayıcıda mock modda çalışır ve Telegram.WebApp'i taklit eder: MainButton ve BackButton'a basın, popup açın, CloudStorage'a yazın, temayı değiştirin ve günlükte 45'ten fazla olayı izleyin. Ancak mock veriler yalnızca bir yer tutucudur: initData'sı Telegram tarafından imzalanmadığı için sunucu tarafındaki doğrulamadan (doğru olarak) geçemez.

2. Adım: Telegram Mini App'i localhost'tan HTTPS ile çalıştırın

Telegram Mini App'leri yalnızca HTTPS adreslerinden açar (istisna test ortamıdır); zaten telefonunuz http://localhost adresine ulaşamaz. Telegram Mini App'i localhost'ta test etmenin standart yolu, geliştirme sunucunuza herkese açık bir HTTPS adresi veren bir tüneldir:

# geliştirme sunucusunu başlatın, ör. 5173 portunda Vite
npm run dev

# ikinci bir terminalde tünellerden birini kullanın
ngrok http 5173
cloudflared tunnel --url http://localhost:5173

Her araç herkese açık bir https:// adresi yazdırır. Sık karşılaşılan iki takılma:

3. Adım: Mini App'i @BotFather'a kaydedin

Bir Mini App her zaman bir bota bağlıdır. Henüz botunuz yoksa Telegram bot yapma rehberini izleyin. Sonra kullanıcıların adresinizi nasıl açacağını seçin:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
  -H "Content-Type: application/json" \
  -d '{"menu_button": {"type": "web_app", "text": "Uygulamayı aç",
       "web_app": {"url": "https://your-tunnel.example.com"}}}'

chat_id verilmezse bu çağrı tüm kullanıcılar için varsayılan menü butonunu ayarlar. Tünel adresiniz her değiştiğinde curl'ü yeniden yazmak yerine çağrıyı Bot API Tester'da setChatMenuButton ile tekrarlayın.

4. Adım: Telegram test ortamını kullanın

Telegram'ın ayrı bir test ortamı vardır; burada Mini App linkleri TLS'siz düz HTTP kullanabilir, bu da yerel ağda test için kullanışlıdır. Kendi hesabını ve kendi botunu gerektirir:

Test hesabında @BotFather ile bir bot oluşturun ve API çağrılarını https://api.telegram.org/bot<token>/test/METHOD_NAME adresine gönderin. Flood limitleri orada yükseltilmez, hatta daha sıkı olabilir; yük testi için uygun bir yer değildir. Bot API Tester'daki TEST anahtarı dahil tam kurulum Telegram test sunucusu rehberinde.

5. Adım: Mini App'te Telegram içinde hata ayıklayın

Chrome'da hiç görünmeyen birçok hata yalnızca gerçek WebView'da ortaya çıkar. Telegram'ın resmi Debug Mode for Mini Apps talimatlarının özeti:

PlatformNasıl incelenir
iOSAyarlar simgesine 10 kez dokunup Allow Web View Inspection'ı açın; USB ile bağlayın ve Mac'teki Safari'de Develop → cihazınız'ı açın.
AndroidUSB hata ayıklamayı açın; Telegram Ayarlar'ında en alta inin, sürüm numarasına iki kez basılı tutun, Enable WebView Debug'ı seçin; Chrome'da chrome://inspect/#devices adresini açın.
Telegram Desktop (Windows, Linux)Beta sürümü kurun; Settings → Advanced → Experimental settings → Enable webview inspection; sağ tık → Inspect.
Telegram for macOSBeta sürümü kurun; Ayarlar simgesine 5 kez tıklayıp Debug Mini Apps'i açın; sağ tık → Inspect Element.

İstemcileri hızlıca karşılaştırmak için https://telegram-bot-api.info/telegram-mini-app-tester.html adresini bir test botunun Mini App URL'si olarak ayarlayın. Telegram içinde Mini App Tester gerçek API'yi kullanır ve version, platform, colorScheme, themeParams, güvenli alanları (safe area) ve ilgili istemcinin tetiklediği her olayı gösterir. Kendi kodunuzda herkesin en yeni uygulamayı kullandığını varsaymayın; yeni özellikleri Telegram.WebApp.isVersionAtLeast("8.0") ile kontrol edin.

6. Adım: initData'yı sunucuda doğrulayın

Telegram.WebApp.initDataUnsafe yalnızca görüntüleme içindir. Ham Telegram.WebApp.initData metnini backend'inize gönderin ve doğrulayın:

  1. Query string'i ayrıştırın ve hash'i çıkarın.
  2. Kalan alanları alfabetik sıralayın ve \n ile ayrılmış key=value satırları olarak birleştirin: bu data_check_string'dir.
  3. secret_key = HMAC_SHA256(key="WebAppData", message=bot_token) değerini hesaplayın.
  4. hex(HMAC_SHA256(key=secret_key, message=data_check_string)) değeri hash'e eşitse veri gerçektir.
  5. auth_date'i kontrol ederek eski verileri reddedin.
import crypto from "node:crypto";

export function validateInitData(initData, botToken, maxAgeSec = 3600) {
  const params = new URLSearchParams(initData);
  const hash = params.get("hash") ?? "";
  params.delete("hash");

  const dataCheckString = [...params.keys()].sort()
    .map((key) => `${key}=${params.get(key)}`)
    .join("\n");

  const secretKey = crypto.createHmac("sha256", "WebAppData").update(botToken).digest();
  const expected = crypto.createHmac("sha256", secretKey).update(dataCheckString).digest("hex");

  const valid = hash.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected));
  const age = Date.now() / 1000 - Number(params.get("auth_date"));
  if (!valid || !(age <= maxAgeSec)) return null;

  return { ...Object.fromEntries(params), user: JSON.parse(params.get("user") ?? "null") };
}

İstemcide metni değiştirmeden gönderin, ör. fetch("/api/session", { method: "POST", body: Telegram.WebApp.initData }), ve uygulamayı başlatan botun token'ıyla doğrulayın. Token'ınızı bilmemesi gereken üçüncü bir taraf ise resmi dokümantasyonda anlatıldığı gibi signature alanını Telegram'ın Ed25519 açık anahtarıyla doğrulayabilir.

Bot API 10.2: Mini App origin koruması

Bot API 10.2, Mini App metotlarının asıl Mini App alan adı dışındaki origin'lerden çağrılmasını yasakladı; koruma 20 Temmuz 2026'da tüm Mini App'ler için etkinleştirildi. Test sırasında bu, uygulama kayıtlı tünel adresinden staging alan adı veya giriş sayfası gibi başka bir host'a yönlendirdiğinde can yakar: orada Telegram.WebApp çağrıları çalışmaz. Telegram ile konuşan kodu kayıtlı alan adında tutun ve tünel host'u her değiştiğinde adresi yeniden kaydedin. Korumayı @BotFather'daki Mini App ayarlarından kapatabilirsiniz, ancak bu durumda Mini App'te güvenilmeyen sitelere link olmamasını sağlamak size kalır.

Telegram Mini App test kontrol listesi

Doğrulama kodunuz bot token'ına dayanır, bu yüzden onu gizli tutun: bot token alma ve koruma rehberine bakın. Aynı backend bot güncellemelerini de alıyorsa Telegram bot webhook kurulumu ile devam edin. Tam bir web uygulaması yerine sohbet mesajının içinde küçük bir etkileşimli blok yeterliyse Bot API 10.4 ile gelen Telegram widget'larına göz atın.

Sık sorulan sorular

Telegram Mini App localhost'ta nasıl test edilir?

Telegram Mini App'leri yalnızca HTTPS adreslerinden açar. Geliştirme sunucunuzu bir HTTPS tüneliyle (ör. ngrok veya Cloudflare Tunnel) dışarı açın ve bu adresi @BotFather'da ya da setChatMenuButton ile kaydedin. Test ortamında düz HTTP linklerine izin verilir.

Telegram Mini App Telegram olmadan test edilebilir mi?

Kısmen. Normal tarayıcıda Telegram istemcisi yoktur; bu yüzden Mini App Tester'ın mock modu gibi bir Telegram.WebApp taklidi gerekir. Gerçek initData, yerel popup'lar ve titreşim (haptics) yalnızca Telegram içinde çalışır.

Telegram Mini App için DevTools nasıl açılır?

iOS'ta Ayarlar simgesine 10 kez dokunup Allow Web View Inspection'ı açın ve Safari'nin Develop menüsünü kullanın. Android'de Telegram hata ayıklama ayarlarından WebView Debug'ı açıp chrome://inspect/#devices adresine gidin. Masaüstü ve macOS'ta beta sürümlerin webview inceleme seçeneklerini kullanın.

initData doğrulaması neden başarısız oluyor?

Sık nedenler: ham initData metni yerine initDataUnsafe'i doğrulamak, başka bir botun token'ını kullanmak, değerleri URL-decode etmemek, hash'i data-check string'de bırakmak, HMAC anahtarı ile mesajı karıştırmak veya Telegram'ın hiç imzalamadığı mock verilerle test etmek.

Telegram.WebApp metotları başka bir alan adında neden çalışmıyor?

Bot API 10.2'den beri Mini App metotları, Mini App alan adından farklı bir origin'den çağrıldığında engellenir; koruma 20 Temmuz 2026'da tüm Mini App'ler için açıldı. Uygulamayı kayıtlı alan adında tutun veya @BotFather'dan bu korumayı kapatın.

Telegram Mini App için ayrı bir test sunucusu var mı?

Evet. Test ortamı üretimden tamamen ayrıdır: orada yeni bir hesap ve yeni bir bot gerekir, Bot API çağrıları https://api.telegram.org/bot<token>/test/METHOD_NAME adresine gider ve Mini App linkleri TLS'siz HTTP kullanabilir.

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 botu nasıl deploy edilir: VPS, Docker ve serverless hosting

Telegram botu sunucuya kurma: polling mi webhook mu, VPS'te systemd servisi, Docker, secret_token ile Cloudflare Workers ve yayın öncesi kontrol listesi.

Telegram Bot API 10.0–10.5: bot ayarları, widget'lar, rich mesajlar, ephemeral mesajlar, misafir modu ve dahası

Telegram Bot API 10.0–10.5'teki yenilikler: setMySettings ve BotFullInfo, HTML widget'lar, rich ve ephemeral mesajlar, misafir modu; JSON örnekleriyle.

Telegram Bot API hataları: her hata ne anlama gelir ve nasıl çözülür

Telegram Bot API hataları: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Nedenleri, çözümleri ve hata yönetimi kodu.

Telegram Bot API limitleri: mesaj gönderme hızı, 429 hatası, dosya boyutu ve mesaj uzunluğu

Telegram Bot API limitleri: saniyede 30 mesaj, sohbet başına 1 mesaj/sn, grupta dakikada 20, 429 retry_after yönetimi, dosya boyutu ve mesaj uzunluğu.

Telegram bot komutları: setMyCommands, komut kapsamları ve /start deep link

Telegram bot komutları nasıl eklenir: @BotFather /setcommands, kapsam ve dil destekli setMyCommands, /start deep link parametresi, gruplarda /komut@bot.

Telegram bot klavyeleri: inline klavye, callback butonları ve reply klavye

Telegram bot butonu ekleme: callback_data ile inline klavye, answerCallbackQuery, basıştan sonra mesajı düzenleme, reply klavye ve ForceReply örnekleri.

n8n Telegram entegrasyonu: botu bağlama, workflow tetikleme ve mesaj gönderme

n8n'i Telegram'a bağlayın: bot token'ı Access Token olarak girin, Telegram Trigger webhook'u için HTTPS kurun, chat id ile mesaj gönderin, hataları çözün.

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 inline bot: inline modu açma ve inline sorguları yanıtlama

Telegram inline bot nasıl yapılır: inline modu @BotFather veya setMySettings ile açın, inline_query güncellemelerini answerInlineQuery ile yanıtlayın.

Telegram botlarında Stars ile ödeme: fatura, ön onay, iade ve abonelikler

Telegram botunuzda Stars ile ödeme alın: XTR ile sendInvoice, pre_checkout_query, successful_payment, iade ve abonelikler; Python ve JS kodu.

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.

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?