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 হেডার ফেরত দেয়।

2Telm-এর মধ্য দিয়ে একটি অনুরোধ যেভাবে যায়

পাবলিক 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 কী কিছু তৈরি বা সম্পাদনা করতে পারে না।
• আপনি একসঙ্গে সর্বোচ্চ দশটি সক্রিয় কী রাখতে পারেন, তাই প্রতি স্ক্রিপ্ট বা সেবার জন্য আলাদা কী ব্যবহার করতে পারেন।
• অনুপস্থিত বা অবৈধ কী 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-তে রিসেট হয়। দুটোই প্রতি অ্যাকাউন্টে গণনা করা হয় এবং আপনার সব 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 স্ট্যাটাস কোড ব্যবহার করে, সঙ্গে বডিতে একটি মেশিন-পাঠযোগ্য ত্রুটি কোড থাকে। আপনার ক্লায়েন্ট এমনভাবে তৈরি করুন যাতে এটি এই কোডগুলো পড়ে এবং অন্ধভাবে পুনরায় চেষ্টা না করে পিছিয়ে যায় বা আপগ্রেডের প্রস্তাব দেখায়।

আপনার দৈনিক কোটা অতিক্রম করলে একটি মিটার করা কল 429 ফেরত দেয়, সঙ্গে থাকে daily_quota_exceeded কোড, একটি Retry-After হেডার এবং এমন একটি বডি যাতে আপনার প্ল্যান, সীমা, ব্যবহৃত কলের সংখ্যা, রিসেট সময় ও একটি আপগ্রেড ইঙ্গিত থাকে। উচ্চতর প্ল্যান দরকার এমন এন্ডপয়েন্ট প্রয়োজনীয় প্ল্যানের উল্লেখসহ 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-এর বুদ্ধিমত্তা কাজে লাগান।
• বাল্ক কনফিগারেশন: সেটিংস ও নিয়ম এন্ডপয়েন্ট দিয়ে কয়েক ডজন গ্রুপে একই নিয়ম, হোয়াইটলিস্ট ও সেটিংস স্ক্রিপ্টের মাধ্যমে প্রয়োগ করুন।
• ডেটা ও সতর্কতা: মডারেশন ইভেন্ট রিয়েল টাইমে একটি ডেটা ওয়্যারহাউস, একটি ড্যাশবোর্ড বা একটি সতর্কতা চ্যানেলে পাঠাতে ওয়েবহুক নিবন্ধন করুন।