टेलीग्राम ने बॉट एपीआई के लिए ओपनएपीआई स्कीमा जारी किया

टेलीग्राम ने बॉट एपीआई का विवरण ओपनएपीआई प्रारूप में जारी किया है। एक फ़ाइल api.json सभी विधियों (methods), ऑब्जेक्ट्स (objects), प्रतिक्रियाओं (responses) और त्रुटियों (errors) को सूचीबद्ध करती है, साथ ही उन अनुरोधों (requests) को भी जो टेलीग्राम स्वयं बॉट को वेबहुक (webhook) पर भेजता है। यह बॉट डेवलपर्स और लाइब्रेरी लेखकों के लिए प्रासंगिक है। अब किसी भी भाषा में क्लाइंट को आधिकारिक फ़ाइल से जेनरेट किया जा सकता है, न कि दस्तावेज़ के पार्स किए गए HTML पेज से। यह फ़ाइल corefork.telegram.org पर उपलब्ध है, जहाँ दस्तावेज़ का अद्यतन संस्करण पोस्ट किया गया है, और यह बॉट एपीआई 10.3 के वर्तमान संस्करण का वर्णन करती है।

यह फ़ाइल क्या है

ओपनएपीआई (पहले स्वैगर कहा जाता था) एक मानक प्रारूप है जिसमें HTTP इंटरफ़ेस को डेटा के रूप में वर्णित किया जाता है: पते, पैरामीटर, फ़ील्ड के प्रकार, प्रतिक्रिया कोड। ऐसे विवरण का उपयोग करके, कोड जनरेटर क्लाइंट लाइब्रेरी बनाते हैं, वैलिडेटर अनुरोधों की जाँच करते हैं, और संपादक इंटरैक्टिव दस्तावेज़ बनाते हैं।

फ़ाइल का आकार 1.83 MB है, और हेडर में "openapi": "3.2.0" और "version": "10.3" लिखा है। संशोधन 3.2.0 मानक का सबसे नवीनतम संस्करण है, जिसे 19 सितंबर 2025 को प्रकाशित किया गया था। इसके नए फीचर्स में, स्कीमा अपने स्वयं के पते के साथ $self फ़ील्ड, नामित सर्वर और दोहराए जाने वाले प्रतिक्रिया निकायों के लिए एक अलग mediaTypes अनुभाग का उपयोग करती है।

फ़ाइल के सीधे गणना के अनुसार इसमें क्या है:

185 विधियों में से आठ में कोई पैरामीटर नहीं है, इसलिए पैरामीटर सेट की संख्या 177 है। फ़ाइल डाउनलोड करना एक अलग downloadFile ऑपरेशन के रूप में वर्णित है, जिसका अपना सर्वर api.telegram.org/file/bot{token} है: HTML दस्तावेज़ में यह एक गद्य पैराग्राफ था, न कि एक विधि।

क्या यह दस्तावेज़ से मेल खाता है

विधियों का सेट पूरी तरह से मेल खाता है। core.telegram.org/bots/api के HTML पेज से 185 विधि नाम निकाले जाते हैं, और स्कीमा से 185 ऑपरेशन निकाले जाते हैं, और सूचियों के बीच कोई विसंगति नहीं है।

ऑब्जेक्ट्स के साथ अधिक जटिलता है, क्योंकि दस्तावेज़ के अब दो संस्करण हैं। मुख्य डोमेन पर 400 ऑब्जेक्ट्स वर्णित हैं। corefork.telegram.org/bots/api पर 429 हैं: 30 अतिरिक्त इनपुट प्रकार (InputRichText और इसके वेरिएंट, InputInlineKeyboardMarkup, InputLocation और अन्य) और एक कम - RichBlockThinking, जो अद्यतन संस्करण में बॉट एपीआई 10.3 की परिवर्तन सूची से गायब हो गया। स्कीमा corefork संस्करण से मेल खाती है: इसके सभी 429 ऑब्जेक्ट फ़ाइल में मौजूद हैं।

फ़ाइल में 19 और स्कीमा हैं। ये सेवा संरचनाएं हैं जो गद्य में अलग ऑब्जेक्ट के रूप में मौजूद नहीं हैं: आठ त्रुटि प्रतिक्रियाएं (BadRequest, Unauthorized, TooManyRequests और अन्य), ChatId, ReplyMarkup, FileInput, UploadInput के यूनियन, और मौजूदा ऑब्जेक्ट्स के सात इनपुट वेरिएंट जैसे InputMessageEntity और InputChatPermissions। इनपुट वेरिएंट वह वर्णन करता है जो बॉट भेजता है, न कि वह जो प्राप्त करता है: वे फ़ील्ड जो सर्वर स्वयं भरता है, इसमें अनुपस्थित होते हैं।

यूनियन और फ़ाइलों का वर्णन कैसे किया जाता है

उन लोगों के लिए सबसे मुश्किल बात, जिन्होंने पहले HTML को पार्स किया है, वे स्थान हैं जहाँ एक फ़ील्ड कई प्रकारों को स्वीकार करता है। स्कीमा में, उन्हें मशीन-पठनीय रूप में वर्णित किया गया है।

डिस्क्रिमिनेटर के साथ यूनियन। ChatMember छह वेरिएंट का oneOf है, और status फ़ील्ड वेरिएंट का चयन करता है: creator ChatMemberOwner की ओर ले जाता है, kicked ChatMemberBanned की ओर। MessageOrigin, InputMedia, BotCommandScope, ReactionType और 17 अन्य प्रकार भी इसी तरह संरचित हैं। इस विवरण के आधार पर एक कोड जनरेटर एक वास्तविक योग प्रकार (sum type) बनाता है, न कि सभी फ़ील्ड के साथ एक ऑब्जेक्ट।

फ़ाइलें। InputFile को application/octet-stream प्रकार के साथ बाइनरी सामग्री के रूप में वर्णित किया गया है। sendPhoto में फ़ोटो फ़ील्ड सीधे इस पर नहीं, बल्कि FileInput पर संदर्भित होता है: यह या तो एक अपलोड की जाने वाली फ़ाइल है, या एक गैर-खाली स्ट्रिंग - file_id या URL। एल्बम में अटैचमेंट के लिए UploadInput है: एक फ़ाइल या attach://<नाम> जैसा एक स्ट्रिंग। sendPhoto का बॉडी multipart/form-data के रूप में घोषित किया गया है, और विधि पैरामीटर के अलावा सभी फ़ील्ड की अनुमति है यदि वे फ़ाइलें हैं। यह उस तरीके का वर्णन करता है जब attach:// के लिए फ़ाइल फॉर्म के एक अलग हिस्से के रूप में आती है। फॉर्म के भीतर caption_entities जैसे नेस्टेड फ़ील्ड को JSON के रूप में चिह्नित किया गया है।

प्रतिक्रियाएँ। प्रत्येक विधि {"ok": true, "result": …} के लिफाफे के साथ प्रतिक्रिया देती है, और result का प्रकार प्रत्येक विधि के लिए अलग से निर्दिष्ट होता है। त्रुटियों को कोड के अनुसार वर्गीकृत किया जाता है: sendPhoto के लिए यह 400, 401, 403, 421, 429 और 500 है।

स्कीमा दस्तावेज़ के अलावा और क्या वर्णन करती है

वेबहुक को एक अलग ऑपरेशन receiveUpdate के रूप में वर्णित किया गया है। टेलीग्राम एक अपडेट भेजता है और X-Telegram-Bot-Api-Secret-Token हेडर या URL से बेसिक ऑथराइजेशन के साथ अनुरोध पर हस्ताक्षर कर सकता है; दोनों तरीकों को सुरक्षा स्कीमा के रूप में घोषित किया गया है। वेबहुक के जवाब में, बॉट तुरंत एक विधि को कॉल कर सकता है, और स्कीमा में यह method फ़ील्ड के साथ सभी अनुमत विधियों का एक यूनियन है। get से शुरू होने वाली विधियों, साथ ही setWebhook, deleteWebhook, close और logOut को इस तरह से कॉल नहीं किया जा सकता है।

23 संबंध (links) वर्णन करते हैं कि एक ऑपरेशन का परिणाम कहाँ स्थानांतरित किया जाता है। एक संदेश से एनीमेशन का file_id sendAnimation में पारित किया जा सकता है, और getFile से file_path को downloadFile के पते के दो भागों में स्लैश द्वारा काटा जा सकता है। काटने के लिए, टेलीग्राम ने अपना स्वयं का एक्सटेंशन x-split-parameters बनाया है - पूरी फ़ाइल में एकमात्र गैर-मानक फ़ील्ड।

यदि क्लाइंट जेनरेट करना हो तो क्या ध्यान रखें

अद्यतन corefork पेज पर तीन अनुभाग दिखाई दिए हैं, जो मुख्य डोमेन पर अभी तक नहीं हैं। तीनों स्कीमा और सर्वर के व्यवहार के बीच विसंगतियों से संबंधित हैं।

64-बिट पहचानकर्ता - स्ट्रिंग। कस्टम इमोजी, उपहार, कॉलबैक क्वेरी और इनलाइन क्वेरी के पहचानकर्ता बॉट एपीआई द्वारा स्ट्रिंग के रूप में लौटाए जाते हैं, और उन्हें स्ट्रिंग के रूप में भी पारित किया जाना चाहिए। स्कीमा में, उदाहरण के लिए, CallbackQuery.id, Sticker.custom_emoji_id और Gift.id का प्रकार string है। उपयोगकर्ताओं और चैट के संख्यात्मक पहचानकर्ता int64 प्रारूप के पूर्णांक बने रहते हैं, हालांकि दस्तावेज़ के अनुसार उनमें 52 से अधिक महत्वपूर्ण बिट्स नहीं होते हैं।

पाठ की लंबाई की सीमा मार्कअप को पार्स करने के बाद गिनी जाती है। संदेश के पाठ की maxLength 4096 है, लेकिन सर्वर HTML- या Markdown-मार्कअप के बिना वर्णों की गणना करता है। स्कीमा वैलिडेटर उन्हें स्ट्रिंग के रूप में गिनता है। टैग के साथ 4100 वर्णों का पाठ सर्वर स्वीकार करेगा, लेकिन एक सख्त वैलिडेटर इसे अस्वीकार कर देगा, इसलिए parse_mode के साथ भेजे जाने वाले फ़ील्ड के लिए, स्कीमा द्वारा लंबाई की जाँच को अक्षम करना उचित है।

त्रुटियाँ एक अलग फ़ाइल में हैं। स्कीमा के बगल में errors.json दिखाई दिया है: प्रत्येक त्रुटि के लिए - उन विधियों की सूची जो इसे वापस कर सकती हैं। फ़ाइल में संस्करण 10.3, MTProto लेयर 227 और 945 त्रुटि विवरण हैं: 901 कोड 400 के साथ, 31 कोड 500 के साथ, 12 कोड 403 के साथ और एक 429 के साथ। 343 MTProto त्रुटियों को अलग से मैप किया गया है। दस्तावेज़ में कहा गया है कि त्रुटि संदेश किसी भी समय बदल सकते हैं, इसलिए सूची संदर्भ के लिए उपयुक्त है, लेकिन कोड में स्ट्रिंग की तुलना के लिए नहीं।

मानक का संस्करण 3.2 एक साल पहले जारी किया गया था। क्या एक विशिष्ट कोड जनरेटर घटकों में mediaTypes और इसकी अन्य नवीनताओं का समर्थन करता है, यह जाँच करना बेहतर है कि कार्यशील लाइब्रेरी को स्कीमा में बदलने से पहले।

फ़ाइल कहाँ और कब से उपलब्ध है

स्कीमा केवल corefork.telegram.org से प्राप्त की जा सकती है। इसके भीतर $self फ़ील्ड core.telegram.org/bots/api.json को इंगित करता है, लेकिन 13 अक्टूबर को इस पते पर "Page not found" पेज खुलता है, जैसा कि मुख्य डोमेन पर errors.json के पते पर भी होता है। मुख्य HTML दस्तावेज़ में अभी तक स्कीमा का उल्लेख नहीं है।

सर्वर प्रतिक्रिया में प्रकाशन की कोई तारीख नहीं है: यह Last-Modified हेडर नहीं देता है, फ़ाइल को पाँच मिनट के लिए कैश किया जाता है और X-Robots-Tag: noindex हेडर द्वारा अनुक्रमण से बंद कर दिया जाता है। वेब-आर्काइव में पहली कॉपी 9 अक्टूबर 2026, 10:16 UTC को दिनांकित है।

स्कीमा के हेडर में कहा गया है कि दस्तावेज़ और स्कीमा दोनों एक कोड जनरेटर द्वारा संकलित किए जाते हैं, जिसे बॉट एपीआई सर्वर के स्रोत कोड के साथ प्रकाशित किया गया है। 13 अक्टूबर तक, लिंक एक गैर-मौजूद फ़ोल्डर की ओर ले जाता है: tdlib/telegram-bot-api रिपॉजिटरी में कोई generator डायरेक्टरी नहीं है। वहाँ अंतिम कमिट 25 अगस्त को किया गया था, उससे एक दिन पहले सर्वर का संस्करण 10.3 तक बढ़ गया था।

इससे पहले क्या उपयोग किया जाता था

बॉट एपीआई के पास पहले कोई आधिकारिक मशीन-पठनीय स्कीमा नहीं थी, और समुदाय इसे HTML पेज से स्वयं इकट्ठा करता था। सबसे प्रसिद्ध उदाहरण telegram-bot-api-spec है: एक स्क्रिप्ट हर दिन दस्तावेज़ को पार्स करती है और विधियों, फ़ील्ड और सबटाइप के साथ JSON प्रकाशित करती है। इसके वर्तमान संस्करण में बॉट एपीआई 10.3, 185 विधियाँ और 400 ऑब्जेक्ट हैं। tg-bot-api में समान पार्सर और कोड जनरेटर हैं, और पुराने संस्करणों के लिए स्कीमा का एक संग्रह telegram-bot-api-versions में संग्रहीत है।

Telegram ने Bot API के लिए OpenAPI स्कीमा प्रकाशित किया

HTML पार्सिंग गद्य पर निर्भर करती है: जैसे फ़ील्ड विवरण की शुरुआत में "Optional" शब्द, प्रकारों के बीच "or" शब्द, और तालिकाओं का क्रम। डॉक्यूमेंटेशन के लेआउट में बदलाव स्वयं API में एक भी बदलाव किए बिना ऐसे पार्सर को तोड़ सकता है। आधिकारिक फ़ाइल इस काम को Telegram की ओर स्थानांतरित करती है: यूनियनों के डिस्क्रिमिनेटर, फ़ील्ड्स की अनिवार्यता, लंबाई की सीमाएँ और त्रुटि कोड अब स्कीमा में परिभाषित हैं, न कि टेक्स्ट से निकाले जाते हैं।