REST API — আপনার নিজের কোড থেকে Telm স্বয়ংক্রিয় করুন

1API আপনাকে কী করতে দেয়

Telm REST API আপনার নিজের কোডকে ড্যাশবোর্ডের মতোই নাগাল দেয়: যেকোনো টেক্সট অ্যান্টি-স্প্যাম পাইপলাইনের মধ্য দিয়ে চালান, ভেতরে ঢুকতে দেওয়ার আগে একজন Telegram ইউজার খুঁজুন, একটি গ্রুপের প্রোটেকশন সেটিংস পড়ুন ও পরিবর্তন করুন, কাস্টম নিয়ম ও হোয়াইটলিস্ট পরিচালনা করুন, মডারেশন জার্নাল ও অ্যানালিটিক্স টানুন, এবং রিয়েল-টাইম ইভেন্টের জন্য webhook নিবন্ধন করুন।

এটি 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। একটি read-only কী তৈরি বা সম্পাদনা করতে পারে না।
• আপনি একসঙ্গে দশটি পর্যন্ত সক্রিয় কী রাখতে পারেন, তাই প্রতিটি স্ক্রিপ্ট বা সার্ভিসের জন্য একটি আলাদা কী ব্যবহার করতে পারেন।
• একটি অনুপস্থিত বা অবৈধ কী 401 ফেরত দেয়; প্রয়োজনীয় স্কোপ ছাড়া একটি কী 403 insufficient_scope ফেরত দেয়।

4উপলব্ধ এন্ডপয়েন্ট

API স্প্যাম ও ইউজার চেক, গ্রুপ পরিচালনা, এবং অ্যাকাউন্ট সেলফ-সার্ভিসকে ঘিরে সাজানো। একক স্প্যাম-চেক এন্ডপয়েন্টটি প্রতিটি প্ল্যানের জন্য উন্মুক্ত; বাকি অংশটি Pro ও Business-এর অংশ।

• POST /spam/check — একই নিয়ম ইঞ্জিনের মধ্য দিয়ে একটি টেক্সট চালান যা সরাসরি ট্রাফিক মডারেট করে (প্রতিটি প্ল্যান)। Pro ও তার উপরে একটি ঐচ্ছিক AI চেক চালু করা যায়।
• POST /spam/check-batch — এক কলে ২০টি পর্যন্ত টেক্সট যাচাই করুন, কেবল নিয়ম (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 — রিয়েল-টাইম ইভেন্ট webhook পরিচালনা করুন (Pro+)।
• GET /usage ও GET /me — আপনার কোটা ও কী তথ্য যাচাই করুন; এগুলো কখনও কোটা খরচ করে না (প্রতিটি প্ল্যান)।

5স্প্যাম-চেক এন্ডপয়েন্ট বিস্তারিত

POST /spam/check হলো API-এর হৃদয় এবং একমাত্র এন্ডপয়েন্ট যা আপনি যেকোনো প্ল্যানে চেষ্টা করতে পারেন। যাচাই করার টেক্সটসহ একটি JSON বডি পাঠান; রেসপন্স একটি রায়, একটি সংখ্যাগত স্কোর, একটি আত্মবিশ্বাস মান এবং একটি সুপারিশকৃত পদক্ষেপ ফেরত দেয় যা আপনি আপনার নিজের পণ্যে প্রয়োগ করতে পারেন।

একটি একক টেক্সট ১০,০০০ অক্ষর পর্যন্ত হতে পারে। Pro ও তার উপরে আপনি কঠিন ক্ষেত্রগুলোর জন্য একটি AI চেক বেছে নিতে পারেন, একটি আলাদা দৈনিক AI-চেক বরাদ্দ থেকে নেওয়া। উচ্চ ভলিউমের জন্য, ব্যাচ এন্ডপয়েন্ট এক কলে ২০টি পর্যন্ত টেক্সট যাচাই করে এবং প্রতি আইটেম কোটা গণনা করে।

• আপনার নিজের পণ্য কী করে তা সিদ্ধান্ত নিতে রায় ও স্কোর ব্যবহার করুন — একটি ফর্ম জমা ব্লক করুন, একটি লিড ফ্ল্যাগ করুন, বা আপনার নিজের বটে একটি বার্তা স্বয়ংক্রিয়ভাবে সরান।
• ব্যাচ এন্ডপয়েন্ট কেবল নিয়ম-ভিত্তিক; AI ল্যাডার কেবল একক-টেক্সট এন্ডপয়েন্টে উপলব্ধ।
• অনুরোধ বডির সীমা আছে (একটি একক চেকের জন্য প্রায় ৬৪ KB, একটি ব্যাচের জন্য ২৫৬ KB); অতিরিক্ত বড় বডি 413 ফেরত দেয়।

6প্ল্যান, রেট লিমিট ও দৈনিক কোটা

অ্যাক্সেস দুইভাবে মিটার করা হয়: একটি প্রতি-মিনিট রেট লিমিট (একটি বার্স্ট সীমা) এবং একটি দৈনিক কল কোটা যা মধ্যরাত UTC-তে রিসেট হয়। দুটোই আপনার প্ল্যানের সঙ্গে বাড়ে এবং প্রতি অ্যাকাউন্ট গণনা করা হয়, আপনার সব কীজুড়ে ভাগ করা। আপনি যেকোনো প্ল্যানে একক স্প্যাম-চেক এন্ডপয়েন্ট চেষ্টা করতে পারেন, তবে নিয়ম, সেটিংস, ব্যাচ চেক ও webhook স্পর্শ করে এমন একটি বাস্তব ইন্টিগ্রেশনের জন্য Pro বা তার বেশি প্রয়োজন।

• Free — দিনে ১০০ কল, কেবল স্প্যাম-চেক।
• Basic — দিনে ১,০০০ কল, কেবল স্প্যাম-চেক।
• Pro — দিনে ১০,০০০ কল, পূর্ণ API ও webhook, পাশাপাশি একটি দৈনিক AI-চেক বরাদ্দ।
• Business — দিনে ৫০,০০০ কল, পূর্ণ API ও webhook, বড় 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-এ, পুনরায় চেষ্টা করার বদলে একটি আপগ্রেড প্রম্পট দেখান।
• রিয়েল-টাইম প্রতিক্রিয়ার জন্য, পোলিংয়ের বদলে webhook পছন্দ করুন — Telm-কে আপনার কাছে ইভেন্ট পুশ করতে দিন।
• কী পর্যায়ক্রমে ঘোরান, এবং একটি ফাঁস হতে পারে বলে সন্দেহ হলে সঙ্গে সঙ্গে।

9সাধারণ ইন্টিগ্রেশন পরিস্থিতি

API Telegram বার্তা মডারেট করার চেয়ে অনেক বেশি কিছুর জন্য ব্যবহৃত হয়।

• ওয়েবসাইট ও অ্যাপ সাইন-আপ: একটি নিবন্ধন বা একটি মন্তব্য গ্রহণ করার আগে জমা দেওয়া টেক্সট বা ইউজারনেম POST /spam/check-এর মধ্য দিয়ে চালান।
• আপনার নিজের Telegram বট: আপনার হ্যান্ডলার থেকে চেক এন্ডপয়েন্ট কল করে Telm পরিচালনা করে না এমন একটি বটে Telm বুদ্ধিমত্তা পুনরায় ব্যবহার করুন।
• বাল্ক কনফিগারেশন: সেটিংস ও নিয়ম এন্ডপয়েন্ট দিয়ে ডজন ডজন গ্রুপজুড়ে একই নিয়ম, হোয়াইটলিস্ট ও সেটিংস স্ক্রিপ্ট করুন।
• ডেটা ও সতর্কতা: রিয়েল টাইমে একটি ডেটা ওয়্যারহাউস, একটি ড্যাশবোর্ড বা একটি সতর্কতা চ্যানেলে মডারেশন ইভেন্ট স্ট্রিম করতে webhook নিবন্ধন করুন।