Telegram, Bot API için OpenAPI Şemasını Yayınladı

Telegram, Bot API açıklamasını OpenAPI formatında yayınladı: tek bir api.json dosyası tüm metotları, nesneleri, yanıtları ve hataları, ayrıca Telegram'ın bot'a webhook üzerinden gönderdiği istekleri listeliyor. Bu durum bot geliştiricilerini ve kütüphane yazarlarını ilgilendiriyor. Artık herhangi bir dildeki istemci, ayrıştırılmış bir HTML dokümantasyon sayfasından değil, resmi dosyadan oluşturulabilir. Dosya, dokümantasyonun güncellenmiş versiyonunun bulunduğu corefork.telegram.org adresinde yer alıyor ve Bot API 10.3'ün mevcut sürümünü açıklıyor.

Bu Dosya Nedir?

OpenAPI (eskiden Swagger olarak biliniyordu), HTTP arayüzünün veriler olarak tanımlandığı standart bir formattır: adresler, parametreler, alan tipleri, yanıt kodları. Bu tür bir açıklama sayesinde kod üreteçleri istemci kütüphaneleri oluşturur, doğrulayıcılar istekleri kontrol eder ve editörler etkileşimli dokümantasyonlar çizer.

Dosya 1.83 MB boyutundadır ve başlığında "openapi": "3.2.0" ile "version": "10.3" yer almaktadır. 3.2.0 revizyonu, standardın en güncelidir ve 19 Eylül 2025 tarihinde yayınlanmıştır. Yenilikleri arasında şema, kendi adresini içeren $self alanını, adlandırılmış sunucuları ve tekrarlayan yanıt gövdeleri için ayrı bir mediaTypes bölümünü kullanır.

Dosyanın doğrudan sayımına göre içinde neler var:

185 metottan sekizinin parametresi yoktur, bu nedenle 177 parametre seti bulunmaktadır. Dosya indirme, kendi sunucusu api.telegram.org/file/bot{token} ile ayrı bir downloadFile operasyonu olarak tanımlanmıştır: HTML dokümantasyonunda bu, bir metot değil, düz yazı bir paragraftı.

Dokümantasyonla Uyumlu mu?

Metot seti tamamen uyumludur. core.telegram.org/bots/api HTML sayfasından 185 metot adı, şemadan ise 185 operasyon çıkarılır ve listeler arasında hiçbir tutarsızlık yoktur.

Nesnelerle durum daha karmaşıktır, çünkü şu anda dokümantasyonun iki versiyonu bulunmaktadır. Ana domainde 400 nesne açıklanmıştır. corefork.telegram.org/bots/api adresinde ise 429 nesne vardır: 30 adet daha fazla giriş tipi (InputRichText ve varyantları, InputInlineKeyboardMarkup, InputLocation ve diğerleri) ve bir adet daha az — RichBlockThinking, bu, güncellenmiş versiyonda Bot API 10.3 değişiklik listesinden çıkarılmıştır. Şema, corefork versiyonuyla uyumludur: 429 nesnesinin tamamı dosyada mevcuttur.

Dosyada sadece 19 şema daha bulunmaktadır. Bunlar, düz yazıda ayrı nesneler olarak yer almayan hizmet yapılarıdır: sekiz hata yanıtı (BadRequest, Unauthorized, TooManyRequests ve diğerleri), ChatId, ReplyMarkup, FileInput, UploadInput birleşimleri ve InputMessageEntity ve InputChatPermissions gibi mevcut nesnelerin yedi giriş varyantı. Giriş varyantı, botun aldığı değil, gönderdiği şeyi tanımlar: sunucunun kendisinin doldurduğu alanlar bu varyantta bulunmaz.

Birleşimler ve Dosyalar Nasıl Tanımlanır?

Daha önce HTML'i ayrıştırmış olanlar için en zor kısım, tek bir alanın birden fazla tip aldığı yerlerdir. Şemada bunlar makine tarafından tanımlanmıştır.

Diskriminatörlü birleşimler. ChatMember, altı varyanttan oluşan bir oneOf'tur ve varyantı status alanı seçer: creator, ChatMemberOwner'a, kicked ise ChatMemberBanned'a yönlendirir. MessageOrigin, InputMedia, BotCommandScope, ReactionType ve diğer 17 tip de benzer şekilde yapılandırılmıştır. Bu tür bir açıklama sayesinde kod üreteci, tüm alanları içeren bir nesne yerine gerçek bir toplam tip (sum type) oluşturur.

Dosyalar. InputFile, application/octet-stream tipiyle ikili içerik olarak tanımlanmıştır. sendPhoto'daki fotoğraf alanı doğrudan ona değil, FileInput'e referans verir: bu ya yüklenecek bir dosya ya da boş olmayan bir dize — file_id veya URL'dir. Albümlerdeki ekler için UploadInput vardır: dosya veya attach://<isim> şeklinde bir dize. sendPhoto'nun gövdesi multipart/form-data olarak bildirilmiştir ve metot parametrelerinin ötesindeki tüm alanlara, dosya olmaları durumunda izin verilir. Bu, attach:// için dosyanın formun ayrı bir parçası olarak geldiği durumu tanımlar. Form içindeki caption_entities gibi iç içe geçmiş alanlar JSON olarak işaretlenmiştir.

Yanıtlar. Her metot {"ok": true, "result": …} zarfıyla yanıt verir ve result tipi her metot için ayrı ayrı belirtilmiştir. Hatalar kodlara göre ayrılmıştır: sendPhoto için bunlar 400, 401, 403, 421, 429 ve 500'dür.

Şemanın dokümantasyonun ötesinde tanımladığı diğer şeyler

Webhook, ayrı bir receiveUpdate operasyonu olarak tanımlanmıştır. Telegram bir güncelleme gönderir ve isteği X-Telegram-Bot-Api-Secret-Token başlığı veya URL'den temel yetkilendirme ile imzalayabilir; her iki yöntem de güvenlik şemaları olarak bildirilmiştir. Webhook'a yanıt olarak bot hemen bir metot çağırabilir ve şemada bu, method alanı ile tüm izin verilen metotların birleşimidir. Adı get ile başlayan metotlar, ayrıca setWebhook, deleteWebhook, close ve logOut bu şekilde çağrılamaz.

23 bağlantı (links), bir operasyonun sonucunun nereye aktarıldığını açıklar. Bir mesajdaki animasyonun file_id'si sendAnimation'a aktarılabilirken, getFile'dan alınan file_path eğik çizgi ile downloadFile adresinin iki parçasına bölünebilir. Bölme işlemi için Telegram, kendi uzantısı olan x-split-parameters'ı kullanmıştır — bu, tüm dosyadaki tek standart dışı alandır.

İstemci Oluştururken Nelere Dikkat Edilmeli?

Güncellenmiş corefork sayfasında, ana domainde henüz bulunmayan üç bölüm ortaya çıktı. Üçü de şema ile sunucu davranışı arasındaki tutarsızlıklarla ilgilidir.

64-bit tanımlayıcılar — dizelerdir. Özel emojilerin, hediyelerin, callback sorgularının ve inline sorguların tanımlayıcılarını Bot API dize olarak döndürür ve bunları da dize olarak iletmek gerekir. Örneğin, şemada CallbackQuery.id, Sticker.custom_emoji_id ve Gift.id string tipindedir. Kullanıcı ve sohbetlerin sayısal tanımlayıcıları, dokümantasyona göre anlamlı bitleri 52'den fazla olmasa da int64 formatında tam sayı olarak kalır.

Metin uzunluk limiti, biçimlendirme ayrıştırıldıktan sonra hesaplanır. Mesaj metninin maxLength değeri 4096'dır, ancak sunucu karakterleri HTML veya Markdown biçimlendirmesi olmadan sayar. Şema doğrulayıcısı bunları dize olarak olduğu gibi sayar. Etiketli 4100 karakterlik bir metni sunucu kabul ederken, katı bir doğrulayıcı reddedecektir, bu nedenle parse_mode ile gönderilen alanlar için şemaya göre uzunluk kontrolünü devre dışı bırakmak faydalı olabilir.

Hatalar ayrı bir dosyada bulunur. Şemanın yanında errors.json adında bir dosya ortaya çıktı: her hata için, onu döndürebilecek metotların bir listesi. Dosyada sürüm 10.3, MTProto katmanı 227 ve 945 hata açıklaması bulunmaktadır: 901 tanesi 400 kodlu, 31 tanesi 500 kodlu, 12 tanesi 403 kodlu ve bir tanesi 429 kodludur. Ayrıca 343 MTProto hatası ayrı ayrı eşleştirilmiştir. Dokümantasyon, hata metinlerinin her an değişebileceğini belirtir, bu nedenle liste referans için uygundur, ancak kodda dizeleri karşılaştırmak için değildir.

Standardın 3.2 sürümü bir yıl önce yayınlandı. Belirli bir kod üretecinin bileşenlerdeki mediaTypes'ı ve diğer yeniliklerini destekleyip desteklemediğini, çalışan bir kütüphaneyi şemaya geçirmeden önce kontrol etmek en iyisidir.

Dosya Nerede ve Ne Zamandan Beri Mevcut?

Şema yalnızca corefork.telegram.org adresinden sunulmaktadır. İçindeki $self alanı core.telegram.org/bots/api.json adresini işaret etse de, 13 Ekim itibarıyla bu adreste "Sayfa bulunamadı" hatası açılmaktadır, ana domaindeki errors.json adresinde olduğu gibi. Ana HTML dokümantasyonu henüz şemadan bahsetmemektedir.

Sunucu yanıtında yayın tarihi yoktur: Last-Modified başlığını döndürmez, dosya beş dakika önbelleğe alınır ve X-Robots-Tag: noindex başlığıyla indekslemeden kapatılmıştır. Web arşivindeki ilk kopya 9 Ekim 2026, 10:16 UTC tarihlidir.

Şemanın başlığında, hem dokümantasyonun hem de şemanın Bot API sunucusunun kaynak koduyla birlikte yayınlanan bir kod üreteci tarafından derlendiği belirtilmektedir. 13 Ekim itibarıyla bağlantı mevcut olmayan bir klasöre yönlendirmektedir: tdlib/telegram-bot-api deposunda generator dizini bulunmamaktadır. Oradaki son commit 25 Ağustos tarihlidir, ondan bir gün önce sunucu sürümü 10.3'e yükselmiştir.

Daha Önce Neler Kullanılıyordu?

Bot API'nin daha önce resmi makine tarafından okunabilir bir şeması yoktu ve topluluk bunu HTML sayfasından kendisi derliyordu. En bilinen örnek telegram-bot-api-spec'tir: bir betik her gün dokümantasyonu ayrıştırır ve metotlar, alanlar ve alt tiplerle birlikte JSON yayınlar. Mevcut sürümünde Bot API 10.3, 185 metot ve 400 nesne bulunmaktadır. Benzer ayrıştırıcılar ve kod üreteçleri tg-bot-api'de mevcuttur ve eski sürümlere ait şema arşivi telegram-bot-api-versions'da saklanmaktadır.

HTML ayrıştırması, alan açıklamasının başındaki "Optional" kelimesine, tipler arasındaki "or" kelimelerine ve tabloların sırasına gibi metinsel ifadelere dayanır. Dokümantasyonun biçimlendirmesinde yapılacak bir değişiklik, API'nin kendisinde tek bir değişiklik olmaksızın böyle bir ayrıştırıcıyı bozabilir. Resmi dosya bu işi Telegram'ın tarafına taşır: birleşimlerin diskriminatörleri, alanların zorunluluğu, uzunluk limitleri ve hata kodları artık metinden çıkarılmak yerine şemada tanımlanmıştır.