Telegram Merilis Skema OpenAPI untuk Bot API

Telegram telah merilis deskripsi Bot API dalam format OpenAPI: satu file api.json mencantumkan semua metode, objek, respons, dan kesalahan, serta permintaan yang dikirim Telegram sendiri ke bot melalui webhook. Ini relevan bagi pengembang bot dan pembuat pustaka (libraries). Klien dalam bahasa apa pun kini dapat dibuat dari file resmi, bukan dari halaman dokumentasi HTML yang diuraikan. File ini tersedia di corefork.telegram.org, tempat versi dokumentasi yang diperbarui dipublikasikan, dan menjelaskan Bot API versi 10.3 saat ini.

Apa Itu File Ini?

OpenAPI (sebelumnya dikenal sebagai Swagger) adalah format standar di mana antarmuka HTTP dijelaskan sebagai data: alamat, parameter, tipe bidang, kode respons. Berdasarkan deskripsi tersebut, generator dapat membangun pustaka klien, validator memeriksa permintaan, dan editor dapat membuat dokumentasi interaktif.

File ini berukuran 1,83 MB, dengan header yang menunjukkan "openapi": "3.2.0" dan "version": "10.3". Revisi 3.2.0 adalah yang terbaru dari standar tersebut, diterbitkan pada 19 September 2025. Di antara fitur barunya, skema ini menggunakan bidang $self dengan alamatnya sendiri, server bernama, dan bagian mediaTypes terpisah untuk badan respons yang berulang.

Berikut adalah isinya, berdasarkan perhitungan langsung dari file:

Delapan dari 185 metode tidak memiliki parameter, sehingga ada 177 set parameter. Pengunduhan file dijelaskan sebagai operasi downloadFile terpisah dengan servernya sendiri api.telegram.org/file/bot{token}: dalam dokumentasi HTML, ini adalah paragraf prosa, bukan metode.

Apakah Sesuai dengan Dokumentasi?

Set metode sepenuhnya cocok. Dari halaman HTML core.telegram.org/bots/api diekstrak 185 nama metode, dari skema juga 185 operasi, dan tidak ada perbedaan di antara daftar tersebut.

Dengan objek, situasinya lebih rumit, karena saat ini ada dua versi dokumentasi. Di domain utama, 400 objek dijelaskan. Di corefork.telegram.org/bots/api ada 429: 30 tipe input lebih banyak (InputRichText dan variannya, InputInlineKeyboardMarkup, InputLocation, dan lainnya) dan satu lebih sedikit — RichBlockThinking, yang dalam versi terbaru telah dihapus dari daftar perubahan Bot API 10.3. Skema ini cocok dengan versi corefork: semua 429 objeknya ada dalam file.

Ada 19 skema lain yang hanya ada dalam file. Ini adalah konstruksi layanan yang tidak ada dalam prosa sebagai objek terpisah: delapan respons kesalahan (BadRequest, Unauthorized, TooManyRequests, dan lainnya), union ChatId, ReplyMarkup, FileInput, UploadInput, dan tujuh varian input dari objek yang ada seperti InputMessageEntity dan InputChatPermissions. Varian input menjelaskan apa yang dikirim bot, bukan apa yang diterima: bidang yang diisi sendiri oleh server tidak ada di dalamnya.

Bagaimana Union dan File Dijelaskan?

Hal tersulit bagi mereka yang sebelumnya menguraikan HTML adalah tempat di mana satu bidang menerima beberapa tipe. Dalam skema, ini dijelaskan secara mesin.

Union dengan diskriminator. ChatMember adalah oneOf dari enam varian, dan bidang status memilih varian: creator mengarah ke ChatMemberOwner, kicked mengarah ke ChatMemberBanned. Hal yang sama berlaku untuk MessageOrigin, InputMedia, BotCommandScope, ReactionType, dan 17 tipe lainnya. Generator, berdasarkan deskripsi ini, membangun tipe-sum yang sebenarnya, bukan objek dengan semua bidang sekaligus.

File. InputFile dijelaskan sebagai konten biner dengan tipe application/octet-stream. Bidang foto di sendPhoto tidak merujuk langsung ke sana, melainkan ke FileInput: ini bisa berupa file yang diunggah, atau string non-kosong — file_id atau URL. Untuk lampiran dalam album, ada UploadInput: file atau string berbentuk attach://<nama>. Badan sendPhoto dideklarasikan sebagai multipart/form-data, dan semua bidang di luar parameter metode diizinkan jika itu adalah file. Ini menjelaskan teknik di mana file untuk attach:// datang sebagai bagian terpisah dari formulir. Bidang bersarang seperti caption_entities di dalam formulir ditandai sebagai JSON.

Respons. Setiap metode merespons dengan amplop {"ok": true, "result": …}, dan tipe result ditentukan untuk setiap metode secara terpisah. Kesalahan dipecah berdasarkan kode: untuk sendPhoto ini adalah 400, 401, 403, 421, 429, dan 500.

Apa lagi yang dijelaskan skema di luar dokumentasi

Webhook dijelaskan sebagai operasi receiveUpdate terpisah. Telegram mengirimkan pembaruan dan dapat menandatangani permintaan dengan header X-Telegram-Bot-Api-Secret-Token atau otorisasi dasar dari URL; kedua metode ini dideklarasikan sebagai skema keamanan. Sebagai respons terhadap webhook, bot dapat langsung memanggil metode, dan dalam skema ini adalah union dari semua metode yang diizinkan dengan bidang method. Metode yang namanya dimulai dengan get, serta setWebhook, deleteWebhook, close, dan logOut tidak dapat dipanggil dengan cara ini.

23 koneksi (links) menjelaskan ke mana hasil satu operasi ditransfer. file_id animasi dari pesan dapat diteruskan ke sendAnimation, dan file_path dari getFile dapat dipisahkan oleh garis miring menjadi dua bagian alamat downloadFile. Untuk pemisahan, Telegram memperkenalkan ekstensi x-split-parameters sendiri — satu-satunya bidang non-standar di seluruh file.

Apa yang Perlu Dipertimbangkan Jika Membuat Klien

Di halaman corefork yang diperbarui, ada tiga bagian yang belum ada di domain utama. Ketiganya berkaitan dengan perbedaan antara skema dan perilaku server.

ID 64-bit — string. ID emoji kustom, hadiah, permintaan callback, dan permintaan inline dikembalikan oleh Bot API sebagai string, dan harus diteruskan juga sebagai string. Dalam skema, misalnya, CallbackQuery.id, Sticker.custom_emoji_id, dan Gift.id memiliki tipe string. ID numerik pengguna dan chat tetap berupa bilangan bulat format int64, meskipun menurut dokumentasi, bit signifikan mereka tidak lebih dari 52.

Batas panjang teks dihitung setelah parsing markup. maxLength untuk teks pesan adalah 4096, tetapi server menghitung karakter tanpa markup HTML atau Markdown. Validator skema menghitungnya berdasarkan string apa adanya. Teks 4100 karakter dengan tag akan diterima oleh server, tetapi validator ketat akan menolaknya, jadi untuk bidang yang dikirim dengan parse_mode, pemeriksaan panjang berdasarkan skema harus dinonaktifkan.

Kesalahan ada dalam file terpisah. Di samping skema, muncul errors.json: untuk setiap kesalahan — daftar metode yang dapat mengembalikannya. Dalam file versi 10.3, lapisan MTProto 227 dan 945 deskripsi kesalahan: 901 dengan kode 400, 31 dengan kode 500, 12 dengan kode 403, dan satu dengan 429. Secara terpisah, 343 kesalahan MTProto dipetakan. Dokumentasi menyatakan bahwa teks kesalahan dapat berubah kapan saja, jadi daftar ini berguna sebagai referensi, tetapi tidak untuk membandingkan string dalam kode.

Standar versi 3.2 dirilis setahun yang lalu. Apakah generator tertentu mendukung mediaTypes dalam komponen dan inovasi lainnya, lebih baik diperiksa sebelum mengadaptasi pustaka kerja ke skema.

Di Mana File Tersedia dan Sejak Kapan

Skema hanya tersedia dari corefork.telegram.org. Bidang $self di dalamnya menunjuk ke core.telegram.org/bots/api.json, tetapi pada 13 Oktober, alamat ini menampilkan halaman "Page not found", sama seperti alamat errors.json di domain utama. Dokumentasi HTML utama belum menyebutkan skema tersebut.

Tanggal publikasi tidak ada dalam respons server: tidak ada header Last-Modified yang dikirim, file di-cache selama lima menit dan ditutup dari pengindeksan oleh header X-Robots-Tag: noindex. Salinan pertama di arsip web bertanggal 9 Oktober 2026, 10:16 UTC.

Di bagian atas skema disebutkan bahwa baik dokumentasi maupun skema dikompilasi oleh generator yang dipublikasikan bersama dengan kode sumber server Bot API. Pada 13 Oktober, tautan tersebut mengarah ke folder yang tidak ada: di repositori tdlib/telegram-bot-api tidak ada direktori generator. Komit terakhir di sana bertanggal 25 Agustus, sehari sebelumnya versi server naik ke 10.3.

Apa yang Digunakan Sebelumnya

Sebelumnya, Bot API tidak memiliki skema yang dapat dibaca mesin secara resmi, dan komunitas membuatnya sendiri dari halaman HTML. Contoh paling terkenal adalah telegram-bot-api-spec: skrip setiap hari menguraikan dokumentasi dan mempublikasikan JSON dengan metode, bidang, dan subtipe. Dalam versi saat ini, Bot API 10.3 memiliki 185 metode dan 400 objek. Parser dan generator serupa ada di tg-bot-api, dan arsip skema untuk versi lama disimpan di telegram-bot-api-versions.

Penguraian HTML bergantung pada teks naratif: kata "Optional" di awal deskripsi bidang, kata "or" di antara tipe data, dan urutan tabel. Perubahan pada tata letak dokumentasi dapat merusak parser semacam itu, bahkan tanpa ada perubahan sedikit pun pada API itu sendiri. File resmi ini mengalihkan pekerjaan tersebut ke pihak Telegram: discriminator field dari union type, status wajib/opsional bidang, batasan panjang, dan kode kesalahan kini ditentukan dalam skema, bukan lagi disimpulkan dari teks.