Telegram Bot API

Telegram test sunucusu: Telegram botunu test ortamında nasıl test edersiniz?

· 7 dk okuma

Telegram test sunucusu, kendi hesapları ve botları olan ayrı bir test ortamıdır; botunuz burada Bot API'yi https://api.telegram.org/bot<token>/test/METHOD_NAME adresinden çağırır. Mini App'ler veya Web Login için düz HTTP bağlantılarına, harcanabilir test kullanıcılarına ya da şu an yalnızca orada açık Bot API özelliklerine ihtiyacınız varsa bu ortamı kullanın. Günlük testler için çoğu zaman üretimdeki ikinci bir bot yeterlidir. Bu rehberde iki seçeneği de, iOS, Desktop ve macOS'ta test ortamına girişi ve test API'sini curl, Python, JavaScript ve Bot API Tester üzerinden çağırmayı anlatıyoruz.

Seçenek 1: üretimde ayrı bir test botu

Bir Telegram botunu kullanıcılarını etkilemeden test etmenin en hızlı yolu, kodunuzun ikinci bir kopyasını farklı bir bot hesabıyla çalıştırmaktır:

  1. @BotFather'da /newbot ile yeni bir bot oluşturun (bkz. Telegram bot nasıl oluşturulur).
  2. Bu botun token'ını test kopyanızın yapılandırmasına, örneğin ayrı bir .env dosyasına yazın.
  3. Yeni botla kendi başınıza hata ayıklayın; üretimdeki bot hiç etkilenmeden çalışmaya devam eder.

Dikkat edilmesi gereken bir nokta var: file_id tek bir bot id'sine bağlıdır. Test botu, ana botun kaydettiği file_id değerlerini kullanamaz; medya dosyalarının test botu tarafından yeniden yüklenmesi gerekir.

Seçenek 2: Telegram'ın özel test ortamı

Telegram daha kapsamlı testler için ayrıca özel bir test ortamı sunar. Bu ortam ana (üretim) ortamdan tamamen ayrıdır: üretimdeki hesaplar, botlar, sohbetler ve token'lar orada bulunmaz. Değişenler şunlar:

ÜretimTest sunucusu
Kullanıcı hesabıNormal Telegram hesabınızTest ortamında oluşturulan yeni bir hesap
Botlar ve token'larÜretimde @BotFather ile oluşturulurTest hesabı içinde @BotFather ile oluşturulur; token'lar ayrıdır
Bot API adresi/bot<token>/METHOD_NAME/bot<token>/test/METHOD_NAME
Mini App ve Web Login bağlantılarıYalnızca HTTPSTLS'siz HTTP'ye izin verilir
Flood limitleriStandart limitlerArtırılmaz, zaman zaman daha sıkı olabilir
Widget'lar (Bot API 10.4)Yalnızca botla özel sohbetteGruplarda, inline modda ve iletilen mesajlarda da

iOS, Desktop veya macOS'ta test hesabı oluşturma

Telegram test ortamına resmî uygulamalardan şöyle giriş yapılır:

Test hesabı normal hesabınızın yanına eklenir; böylece aynı uygulamada ortamlar arasında geçiş yapabilirsiniz. Orada yaptığınız her şey, test botunuzla sohbetler dahil, test ortamında kalır.

Test sunucusunda bot oluşturma ve token alma

Test hesabında @BotFather'ı açın ve botu her zamanki gibi oluşturun: /newbot, görünen ad, ardından bot ile biten bir kullanıcı adı. BotFather size test ortamına ait bir token gönderir. Görünüşü diğer token'larla aynıdır, ancak yalnızca /test/ içeren API adresiyle çalışır. Üretim token'ıyla asla karışmaması için onu ayrı bir isimle, örneğin TEST_BOT_TOKEN olarak saklayın; bot token rehberindeki kurallar burada da geçerlidir.

Telegram test sunucusunda Bot API'yi çağırma

Tüm Bot API metotları aynı şekilde çalışır; tek fark token'dan sonra gelen /test/ kısmıdır. Token'ı getMe ile kontrol edin:

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/getMe"

Kodda temel adresi tek bir sabitte tutun; böylece ortam değiştirmek tek satırlık bir iş olur. Aşağıdaki minimal echo botu token'ı kontrol eder, ardından güncellemeleri getUpdates long polling ile alır ve 429 aldığında retry_after kadar bekler:

import os
import time
import requests

TOKEN = os.environ["TEST_BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}/test"  # üretim için "/test" kısmını kaldırın


def call(method, **params):
    while True:
        data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
        if data["ok"]:
            return data["result"]
        if data.get("error_code") == 429:  # flood limiti: söylenen süre kadar bekle
            time.sleep(data["parameters"]["retry_after"])
            continue
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")


me = call("getMe")
print("Test sunucusunda çalışıyor: @" + me["username"])

offset = 0
while True:
    for update in call("getUpdates", offset=offset, timeout=30):
        offset = update["update_id"] + 1
        msg = update.get("message")
        if msg and "text" in msg:
            call("sendMessage", chat_id=msg["chat"]["id"], text="Test yankısı: " + msg["text"])
const TOKEN = process.env.TEST_BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}/test`; // üretim için "/test" kısmını kaldırın

async function call(method, params = {}) {
  while (true) {
    const res = await fetch(`${API}/${method}`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(params),
      signal: AbortSignal.timeout(40_000),
    });
    const data = await res.json();
    if (data.ok) return data.result;
    if (data.error_code === 429) { // flood limiti: söylenen süre kadar bekle
      await new Promise((resolve) => setTimeout(resolve, data.parameters.retry_after * 1000));
      continue;
    }
    throw new Error(`${method}: ${data.error_code} ${data.description}`);
  }
}

const me = await call("getMe");
console.log("Test sunucusunda çalışıyor: @" + me.username);

let offset = 0;
while (true) {
  for (const update of await call("getUpdates", { offset, timeout: 30 })) {
    offset = update.update_id + 1;
    const msg = update.message;
    if (msg?.text) {
      await call("sendMessage", { chat_id: msg.chat.id, text: "Test yankısı: " + msg.text });
    }
  }
}

Test hesabınızdan bota /start gönderin, bot yanıt verecektir. JavaScript sürümü top-level await kullandığı için dosyayı bot.mjs olarak kaydedin ve Node.js 18 veya üzeriyle çalıştırın.

Webhook'lar da aynı şekilde çalışır: setWebhook'u test adresi üzerinden çağırın; url, portlar ve secret_token için bilinen kurallar geçerlidir. Sonucu yine /test/ üzerinden getWebhookInfo ile kontrol edin:

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/setWebhook" \
  -d "url=https://example.com/telegram/webhook"
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/getWebhookInfo"

Ayrıntılı webhook kurulumu için webhook rehberine bakabilirsiniz. Bot kütüphaneleri istek adreslerini genellikle bir temel adresten oluşturur. Kullandığınız kütüphane Bot API temel adresini değiştirmeye izin veriyorsa, istekler …/bot<token>/test/METHOD_NAME adresine gidecek şekilde ayarlayın; seçeneğin adı kütüphaneden kütüphaneye değiştiği için kütüphanenizin dokümantasyonuna bakın.

Test sunucusunu Bot API Tester'da deneyin

Bot API Tester, test ortamına kod yazmadan istek gönderebilir:

  1. Bot API Tester'da getMe metodunu açın.
  2. Token alanının yanındaki TEST anahtarına basın ya da tester sayfasını adres çubuğunda ?env=test ile açın.
  3. Test botunuzun token'ını yapıştırıp Execute'a basın. İstekler artık https://api.telegram.org/bot<token>/test/METHOD adresine gider.

Anahtar açıkken getUpdates long polling dahil her metot test adresini kullanır; böylece test hesabınızdan gelen güncellemelerin güncelleme geçmişine düştüğünü görebilirsiniz. Tester anahtarın durumunu tarayıcınızda hatırlar; üretim token'ı yapıştırmadan önce kapatmayı unutmayın. Her zamanki gibi token tarayıcınızın localStorage'ında kalır ve istekler doğrudan api.telegram.org'a gider.

Düz HTTP üzerinden Mini App ve Web Login

Mini App geliştiricilerinin test ortamını kullanmasının asıl nedeni şu: orada WebAppInfo (Mini App'ler) ve LoginUrl (Web Login butonları) içindeki url, TLS'siz bir HTTP bağlantısı olabilir. Bu sayede test botunun menü butonunu veya web_app butonunu, sertifika ya da tünel kurmadan yerel ağınızdaki geliştirme sunucusuna yönlendirebilirsiniz. Üretimde bağlantılar HTTPS olmak zorundadır. Mini App'in arayüzünü önce tarayıcıda denemek için Mini App Tester'ın mock modunu kullanabilirsiniz.

Test sunucusunda Bot API 10.4 widget'ları

Bot API 10.4 ile gelen mesaj içi HTML widget'ları üretimde şu an yalnızca botla özel sohbette çalışır. Gruplardaki, inline moddaki ve iletilen mesajlardaki widget'lar şimdilik yalnızca test sunucusunda çalışıyor; bu senaryoları orada deneyebilirsiniz. Widget'ların nasıl çalıştığı Telegram widget'ları rehberinde anlatılıyor.

Limitler ve iyi uygulamalar

Sorun giderme

BelirtiOlası nedenÇözüm
401 UnauthorizedÜretim token'ı /test/ adresine ya da test token'ı /test/ olmadan gönderilmişOrtamlar ayrıdır: token'ı adresle eşleştirin (tester'da TEST anahtarıyla)
400 Bad Request: chat not foundChat id üretimden alınmış; bu kullanıcılar ve sohbetler test sunucusunda yokTest hesabınızdan test botuna yazın ve chat id'yi getUpdates ile alın
Bot aramada bulunamıyorÜretim hesabınızdan arama yapıyorsunuzBotun oluşturulduğu test hesabından arayın
429 Too Many RequestsTest sunucusunda artırılmayan flood limitleriretry_after saniye bekleyin ve istek hızını düşürün
HTTP üzerinden Mini App açılmıyorBot veya hesap üretim ortamındaTest ortamında oluşturulmuş bir bot kullanın ve test hesabından açın

Sık sorulan sorular

Telegram test sunucusu nedir?

Üretim (production) Telegram'dan tamamen ayrı, özel bir test ortamıdır. Kendi kullanıcı hesapları ve botları vardır; botlar Bot API'yi https://api.telegram.org/bot<token>/test/METHOD_NAME adresinden çağırır.

Telegram test ortamına nasıl giriş yapılır?

iOS'ta Ayarlar simgesine 10 kez dokunun → Accounts → Login to another account → Test. Telegram Desktop'ta ☰ Ayarlar'ı açın, Shift + Alt basılıyken "Add Account"a sağ tıklayıp "Test Server"ı seçin. macOS'ta Debug Menu'yü açmak için Ayarlar simgesine 10 kez tıklayın, ardından ⌘ + tık ile "Add Account".

Üretimdeki bot token'ımı test sunucusunda kullanabilir miyim?

Hayır. Ortamlar birbirinden ayrıdır: üretimde oluşturulan bot test sunucusunda yoktur, tersi de geçerlidir. Test hesabınızda @BotFather ile yeni bir bot oluşturun; yanlış ortamın token'ı genellikle 401 Unauthorized ile sonuçlanır.

Telegram test sunucusunda istek limitleri daha yüksek mi?

Hayır. Test ortamında flood limitleri artırılmaz, hatta zaman zaman daha sıkı olabilir. 429 Too Many Requests hatasını retry_after ile ele alın ve limit değerlerini koda gömmeyin.

Mini App test ortamında düz HTTP kullanabilir mi?

Evet. Test ortamında WebAppInfo (Mini App'ler) ve LoginUrl (Web Login) içindeki url, TLS'siz bir HTTP bağlantısı olabilir. Üretimde HTTPS zorunludur.

Bir botu test etmek için her zaman test sunucusu gerekir mi?

Hayır. Çoğu iş için üretimde @BotFather ile oluşturulan ikinci bir bot yeterlidir: kendi token'ı vardır ve gerçek kullanıcılarınızı etkilemez. HTTP bağlantılarına, ayrı test hesaplarına veya yalnızca orada açık özelliklere ihtiyacınız olduğunda test sunucusunu kullanın.

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.

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?