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

1API आपको क्या करने देता है

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

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

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

2एक अनुरोध Telm के ज़रिए कैसे बहता है

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

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

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

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

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

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

• कुंजी को Authorization: Bearer tk_live_your_key_here के रूप में भेजें (एक X-API-Key हेडर भी काम करता है)।
• कुंजियाँ read या write स्कोप ले जाती हैं — GET अनुरोधों के लिए read, डेटा बदलने वाली किसी भी चीज़ के लिए write। एक केवल-पढ़ने वाली कुंजी बना या संपादित नहीं कर सकती।
• आप एक साथ दस तक सक्रिय कुंजियाँ रख सकते हैं, इसलिए आप प्रति स्क्रिप्ट या सेवा एक अलग कुंजी का उपयोग कर सकते हैं।
• एक अनुपस्थित या अमान्य कुंजी 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 बॉडी भेजें; प्रतिक्रिया एक निर्णय, एक संख्यात्मक स्कोर, एक विश्वास मान और एक अनुशंसित कार्रवाई लौटाती है जिसे आप अपने ख़ुद के उत्पाद में लागू कर सकते हैं।

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

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

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

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

• Free — 100 कॉल/दिन, केवल स्पैम-जाँच।
• Basic — 1,000 कॉल/दिन, केवल स्पैम-जाँच।
• Pro — 10,000 कॉल/दिन, पूरा API और वेबहुक, साथ ही एक दैनिक AI-जाँच भत्ता।
• Business — 50,000 कॉल/दिन, पूरा API और वेबहुक, बड़ा AI भत्ता।
• प्रति-मिनट रेट लिमिट भी बढ़ती हैं — ऊँचे प्लान को बहुत बड़ी बर्स्ट सीमा मिलती है।

7त्रुटि संचालन और स्थिति कोड

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

जब आप अपना दैनिक कोटा पार करते हैं, तो एक मीटर किया गया कॉल एक daily_quota_exceeded कोड, एक Retry-After हेडर, और एक बॉडी के साथ 429 लौटाता है जो आपका प्लान, सीमा, उपयोग की गई गिनती, रीसेट समय और एक अपग्रेड संकेत सूचीबद्ध करती है। जिन एंडपॉइंट को एक ऊँचे प्लान की ज़रूरत है वे आवश्यक प्लान के साथ 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 बुद्धिमत्ता का फिर से उपयोग करें।
• थोक कॉन्फ़िगरेशन: सेटिंग्स और नियम एंडपॉइंट के साथ दर्जनों ग्रुपों में वही नियम, व्हाइटलिस्ट और सेटिंग्स स्क्रिप्ट करें।
• डेटा और अलर्टिंग: मॉडरेशन घटनाओं को वास्तविक समय में एक डेटा वेयरहाउस, एक डैशबोर्ड या एक अलर्टिंग चैनल में स्ट्रीम करने के लिए वेबहुक रजिस्टर करें।