REST API — अपने कोड से Telm को स्वचालित करें

1API से आप क्या कर सकते हैं

Telm REST API आपके अपने कोड को डैशबोर्ड जितनी ही पहुँच देता है: किसी भी टेक्स्ट को एंटी-स्पैम पाइपलाइन से गुज़ारें, किसी Telegram उपयोगकर्ता को अंदर आने देने से पहले उसकी जाँच करें, किसी ग्रुप की सुरक्षा सेटिंग्स पढ़ें और बदलें, कस्टम नियम और व्हाइटलिस्ट प्रबंधित करें, मॉडरेशन जर्नल और विश्लेषण निकालें, और रियल-टाइम घटनाओं के लिए वेबहुक रजिस्टर करें।

इससे Telm आपके ग्रुपों के अंदर रहने वाले एक बॉट से बढ़कर ऐसा इंफ्रास्ट्रक्चर बन जाता है जिसे आप कहीं भी जोड़ सकते हैं — किसी वेबसाइट का साइन-अप फ़ॉर्म, कोई CRM बॉट, आपके अपने Telegram बॉट, या कोई स्क्रिप्ट जो एक साथ सौ ग्रुप कॉन्फ़िगर करती है।

• Base URL: api.telm.com/api/public/v1 — एक स्थिर, संस्करण वाला पाथ (v1 अनुबंध का संस्करण है)।
• हर अनुरोध और प्रतिक्रिया HTTPS पर JSON में होती है।
• इंटरैक्टिव दस्तावेज़ और मशीन-पठनीय OpenAPI 3.1 स्पेसिफ़िकेशन डेवलपर्स पेज पर हैं — मिनटों में इंटीग्रेशन का ढाँचा तैयार करने के लिए स्पेसिफ़िकेशन को Postman, किसी कोड जनरेटर या किसी AI एजेंट में लोड करें।
• मीटर की गई कॉल हर प्रतिक्रिया में X-Quota-Limit, X-Quota-Used और X-Quota-Reset हेडर लौटाती हैं।

2Telm में एक अनुरोध कैसे आगे बढ़ता है

सार्वजनिक API अपने अलग पाथ प्रीफ़िक्स /api/public/ पर रहता है, जो डैशबोर्ड से अलग है। हर कॉल ब्राउज़र सत्र के बजाय एक API कुंजी से प्रमाणित होती है, आपके प्लान और कोटा के विरुद्ध जाँची जाती है, उसी लाइव इंजन पर चलती है जो आपके ग्रुपों को मॉडरेट करता है, और JSON के रूप में लौटाई जाती है।

क्योंकि API उसी इंजन और डेटा तक पहुँचता है जिस तक बॉट, इसलिए जो कुछ आप डैशबोर्ड में देख या बदल सकते हैं वह कोड से भी कर सकते हैं — और कोड से किया गया कोई भी बदलाव डैशबोर्ड में तुरंत दिखता है।

• अनुरोध स्टेटलेस होते हैं: हर अनुरोध अपनी कुंजी साथ लाता है और अपने-आप में पूरा होता है।
• कुंजी आपके खाते की ओर से काम करती है और केवल उन ग्रुपों को छू सकती है जहाँ आपका खाता एडमिन है।
• स्पैम-जाँच एंडपॉइंट ठीक उसी प्रोडक्शन नियम पाइपलाइन तक पहुँचता है, इसलिए API का निर्णय वही होता है जो बॉट ग्रुप में लेता।

3API कुंजियों से प्रमाणीकरण

हर अनुरोध एक API कुंजी से प्रमाणित होता है, जो tk_live_ और उसके बाद यादृच्छिक अक्षरों से बनी होती है — आपके डैशबोर्ड लॉगिन से नहीं। आप कुंजियाँ अपने खाते में बनाते हैं और कुंजी को Authorization हेडर में Bearer token के रूप में, या X-API-Key हेडर में भेजते हैं।

पूरा गुप्त मान केवल एक बार, बनाते समय दिखाया जाता है। उसके बाद डैशबोर्ड कुंजी को केवल उसके छोटे प्रीफ़िक्स से दिखाता है, ताकि आप पूरा मान कहीं सहेजे बिना उसे पहचान सकें। अगर कोई कुंजी लीक हो जाए, तो उसे रद्द करें और नई जारी करें — रद्दीकरण तुरंत प्रभावी होता है।

• कुंजी को Authorization: Bearer tk_live_your_key_here के रूप में भेजें (X-API-Key हेडर भी काम करता है)।
• कुंजियों का स्कोप read या write होता है — GET अनुरोधों के लिए read, डेटा बदलने वाली हर चीज़ के लिए write। केवल read वाली कुंजी कुछ बना या संपादित नहीं कर सकती।
• आप एक साथ दस तक सक्रिय कुंजियाँ रख सकते हैं, ताकि हर स्क्रिप्ट या सेवा के लिए अलग कुंजी इस्तेमाल कर सकें।
• गुम या अमान्य कुंजी पर 401 लौटता है; आवश्यक स्कोप के बिना कुंजी पर 403 insufficient_scope लौटता है।

4उपलब्ध एंडपॉइंट

API स्पैम और उपयोगकर्ता जाँच, ग्रुप प्रबंधन और खाता स्व-सेवा के इर्द-गिर्द व्यवस्थित है। एकल स्पैम-जाँच एंडपॉइंट हर प्लान के लिए खुला है; बाक़ी सब Pro और Business का हिस्सा है।

• POST /spam/check — एक टेक्स्ट को उसी नियम इंजन से गुज़ारें जो लाइव ट्रैफ़िक को मॉडरेट करता है (हर प्लान)। Pro और उससे ऊपर पर एक वैकल्पिक AI जाँच चालू की जा सकती है।
• POST /spam/check-batch — एक कॉल में 20 तक टेक्स्ट जाँचें, केवल नियमों से (Pro+)।
• POST /users/check — किसी Telegram उपयोगकर्ता की जाँच करें: CAS स्थिति, Telm के स्पैम-निर्णय संकेत और आपके ग्रुपों में प्रतिष्ठा (Pro+)।
• GET /groups और GET /groups/{id} — अपने ग्रुपों की सूची देखें और उन्हें पढ़ें (Pro+)।
• GET और PATCH /groups/{id}/settings — किसी ग्रुप की सुरक्षा सेटिंग्स पढ़ें और बदलें (Pro+)।
• GET/POST/PUT/DELETE /groups/{id}/rules — कस्टम मॉडरेशन नियम प्रबंधित करें (Pro+)।
• GET/POST/DELETE /groups/{id}/whitelist — ग्रुप की व्हाइटलिस्ट प्रबंधित करें (Pro+)।
• GET /groups/{id}/journal और GET /groups/{id}/analytics — मॉडरेशन लॉग और विश्लेषण पढ़ें (Pro+)।
• GET/POST/PATCH/DELETE /webhooks — रियल-टाइम घटनाओं के वेबहुक प्रबंधित करें (Pro+)।
• GET /usage और GET /me — अपना कोटा और कुंजी की जानकारी देखें; ये कभी कोटा ख़र्च नहीं करते (हर प्लान)।

5स्पैम-जाँच एंडपॉइंट विस्तार से

POST /spam/check API का केंद्र है और अकेला ऐसा एंडपॉइंट है जिसे आप किसी भी प्लान पर आज़मा सकते हैं। जाँचने वाले टेक्स्ट के साथ एक JSON body भेजें; प्रतिक्रिया में एक निर्णय, एक संख्यात्मक स्कोर, एक विश्वसनीयता मान और एक अनुशंसित कार्रवाई लौटती है, जिसे आप अपने उत्पाद में लागू कर सकते हैं।

एक टेक्स्ट 10,000 अक्षरों तक का हो सकता है। Pro और उससे ऊपर पर आप कठिन मामलों के लिए AI जाँच चुन सकते हैं, जो एक अलग दैनिक AI-जाँच सीमा से गिनी जाती है। अधिक मात्रा के लिए, बैच एंडपॉइंट एक कॉल में 20 तक टेक्स्ट जाँचता है और कोटा हर आइटम के हिसाब से गिनता है।

• निर्णय और स्कोर से तय करें कि आपका उत्पाद क्या करे — कोई फ़ॉर्म सबमिशन रोकना, किसी लीड को चिह्नित करना, या अपने बॉट में किसी संदेश को अपने-आप हटाना।
• बैच एंडपॉइंट केवल नियमों पर चलता है; AI जाँच केवल एकल-टेक्स्ट एंडपॉइंट पर उपलब्ध है।
• अनुरोध body का आकार सीमित है (एकल जाँच के लिए लगभग 64 KB, बैच के लिए 256 KB); इससे बड़ी body पर 413 लौटता है।

6प्लान, रेट लिमिट और दैनिक कोटा

पहुँच दो तरह से मीटर होती है: प्रति-मिनट रेट लिमिट (अचानक उछाल की ऊपरी सीमा) और एक दैनिक कॉल कोटा, जो मध्यरात्रि UTC पर रीसेट होता है। दोनों प्रति खाता गिने जाते हैं और आपकी सभी API कुंजियों में साझा होते हैं। एकल स्पैम-जाँच एंडपॉइंट आप किसी भी प्लान पर आज़मा सकते हैं, लेकिन नियमों, सेटिंग्स, बैच जाँचों और वेबहुक से जुड़े असली इंटीग्रेशन के लिए Pro या उससे ऊपर चाहिए।

• Free — 100 कॉल/दिन, केवल स्पैम जाँच।
• Pro — 10,000 कॉल/दिन, पूरा API और वेबहुक, साथ में प्रति दिन 1,000 AI जाँच।
• Business — 50,000 कॉल/दिन, पूरा API और वेबहुक, साथ में प्रति दिन 10,000 AI जाँच।
• प्रति-मिनट रेट लिमिट भी प्लान के साथ बढ़ती है — Free पर प्रति मिनट 60 अनुरोध, Pro पर 600 और Business पर 1,800।
• GET /usage और GET /me आपके कोटा में कभी नहीं गिने जाते, इसलिए आप किसी भी समय अपना बचा हुआ बजट देख सकते हैं।

7त्रुटियों को संभालना और स्टेटस कोड

API मानक HTTP स्टेटस कोड इस्तेमाल करता है, और body में एक मशीन-पठनीय त्रुटि कोड होता है। अपना क्लाइंट ऐसा बनाएँ कि वह इन कोड को पढ़े और आँख मूँदकर दोबारा कोशिश करने के बजाय रुके या अपग्रेड का सुझाव दिखाए।

जब आप अपना दैनिक कोटा पार कर लेते हैं, तो मीटर की गई कॉल 429 लौटाती है, साथ में daily_quota_exceeded कोड, एक Retry-After हेडर, और एक body जिसमें आपका प्लान, सीमा, इस्तेमाल हुई कॉल की संख्या, रीसेट का समय और अपग्रेड का संकेत होता है। जिन एंडपॉइंट के लिए ऊँचा प्लान चाहिए, वे आवश्यक प्लान के साथ 403 plan_required लौटाते हैं।

• 401 — API कुंजी गुम या अमान्य है।
• 403 plan_required — एंडपॉइंट के लिए Pro या उससे ऊपर चाहिए।
• 403 insufficient_scope — डेटा बदलने वाली कॉल के लिए कुंजी में write स्कोप नहीं है।
• 429 daily_quota_exceeded या rate_limit_exceeded — रीसेट के समय तक प्रतीक्षा करें या अपग्रेड करें; Retry-After हेडर का पालन करें।
• सीमा तक पहुँचने से पहले ही सतर्क रहने के लिए X-Quota-* प्रतिक्रिया हेडर पढ़ते रहें।

8मज़बूत इंटीग्रेशन के लिए सर्वोत्तम अभ्यास

कुछ आदतें इंटीग्रेशन के बढ़ने के साथ उसे भरोसेमंद और सुरक्षित बनाए रखती हैं।

• कुंजियाँ किसी सीक्रेट्स मैनेजर में रखें, कभी क्लाइंट-साइड कोड या git रिपॉज़िटरी में नहीं; हर सेवा के लिए अलग कुंजी इस्तेमाल करें, ताकि बाक़ी को तोड़े बिना एक को रद्द कर सकें।
• X-Quota-Used और X-Quota-Limit हेडर पर नज़र रखें (या समय-समय पर GET /usage कॉल करें) और सीमा से टकराने से पहले ही अनुरोधों की गति धीमी करें, बाद में नहीं।
• 429 पर Retry-After का पालन करें और रुकें; 403 plan_required पर दोबारा कोशिश करने के बजाय अपग्रेड का सुझाव दिखाएँ।
• रियल-टाइम प्रतिक्रिया के लिए पोलिंग के बजाय वेबहुक चुनें — Telm को घटनाएँ आप तक पहुँचाने दें।
• कुंजियाँ समय-समय पर बदलें, और अगर किसी के लीक होने की आशंका हो तो तुरंत बदलें।

9आम इंटीग्रेशन परिदृश्य

API का इस्तेमाल Telegram संदेशों को मॉडरेट करने से कहीं आगे तक होता है।

• वेबसाइट और ऐप साइन-अप: कोई रजिस्ट्रेशन या कमेंट स्वीकार करने से पहले सबमिट किए गए टेक्स्ट या यूज़रनेम को POST /spam/check से गुज़ारें।
• आपके अपने Telegram बॉट: अपने हैंडलर से जाँच एंडपॉइंट कॉल करके Telm की समझ का इस्तेमाल ऐसे बॉट में करें जिसे Telm प्रबंधित नहीं करता।
• बल्क कॉन्फ़िगरेशन: सेटिंग्स और नियम एंडपॉइंट की मदद से दर्जनों ग्रुपों में एक जैसे नियम, व्हाइटलिस्ट और सेटिंग्स स्क्रिप्ट से लागू करें।
• डेटा और अलर्ट: मॉडरेशन घटनाओं को रियल टाइम में किसी डेटा वेयरहाउस, डैशबोर्ड या अलर्ट चैनल तक भेजने के लिए वेबहुक रजिस्टर करें।