REST API — automatyzuj Telm z własnego kodu

1Co umożliwia API

Telm REST API daje Twojemu własnemu kodowi te same możliwości co panel: przepuszczanie dowolnego tekstu przez potok antyspamowy, sprawdzanie użytkownika Telegrama, zanim go wpuścisz, odczyt i zmianę ustawień ochrony grupy, zarządzanie własnymi regułami i białymi listami, pobieranie dziennika moderacji i analityki oraz rejestrowanie webhooków dla zdarzeń w czasie rzeczywistym.

Dzięki temu Telm przestaje być tylko botem żyjącym w Twoich grupach i staje się infrastrukturą, którą możesz podpiąć wszędzie — do formularza rejestracji na stronie, bota CRM, własnych botów Telegram albo skryptu, który konfiguruje sto grup naraz.

• Bazowy URL: api.telm.com/api/public/v1 — stabilna, wersjonowana ścieżka (v1 to wersja kontraktu).
• Każde żądanie i każda odpowiedź to JSON przez HTTPS.
• Interaktywna dokumentacja i maszynowo czytelna specyfikacja OpenAPI 3.1 znajdują się na stronie dla deweloperów — wczytaj specyfikację do Postmana, generatora kodu lub agenta AI, aby w kilka minut zbudować szkielet integracji.
• Mierzone wywołania zwracają nagłówki X-Quota-Limit, X-Quota-Used i X-Quota-Reset w każdej odpowiedzi.

2Jak żądanie przechodzi przez Telm

Publiczne API ma własny prefiks ścieżki, /api/public/, oddzielny od panelu. Każde wywołanie jest uwierzytelniane kluczem API, a nie sesją przeglądarki, sprawdzane względem Twojego planu i przydziału, wykonywane na tym samym działającym silniku, który moderuje Twoje grupy, i zwracane jako JSON.

Ponieważ API sięga do tego samego silnika i tych samych danych co bot, wszystko, co możesz zobaczyć lub zmienić w panelu, możesz też zrobić w kodzie — a każda zmiana wprowadzona w kodzie od razu pojawia się w panelu.

• Żądania są bezstanowe: każde niesie własny klucz i jest niezależne od pozostałych.
• Klucz działa w imieniu Twojego konta i może dotykać tylko grup, w których Twoje konto jest administratorem.
• Endpoint sprawdzania spamu korzysta z dokładnie tego samego produkcyjnego potoku reguł, więc werdykt API odpowiada temu, co bot zrobiłby w grupie.

3Uwierzytelnianie kluczami API

Każde żądanie jest uwierzytelniane kluczem API w postaci tk_live_, po którym następują losowe znaki — a nie Twoim loginem do panelu. Klucze tworzysz na swoim koncie i wysyłasz je w nagłówku Authorization jako token Bearer albo w nagłówku X-API-Key.

Pełny sekret jest pokazywany tylko raz, w chwili utworzenia. Potem panel wyświetla klucz wyłącznie po jego krótkim prefiksie, abyś mógł go rozpoznać bez przechowywania pełnej wartości. Jeśli klucz wycieknie, unieważnij go i wydaj nowy — unieważnienie działa natychmiast.

• Wysyłaj klucz jako Authorization: Bearer tk_live_your_key_here (nagłówek X-API-Key też działa).
• Klucze mają zakres odczytu lub zapisu — odczyt dla żądań GET, zapis dla wszystkiego, co zmienia dane. Klucz tylko do odczytu nie może niczego tworzyć ani edytować.
• Możesz mieć jednocześnie do dziesięciu aktywnych kluczy, więc dla każdego skryptu lub usługi możesz używać osobnego klucza.
• Brakujący lub nieprawidłowy klucz zwraca 401; klucz bez wymaganego zakresu zwraca 403 insufficient_scope.

4Dostępne endpointy

API jest zorganizowane wokół sprawdzania spamu i użytkowników, zarządzania grupami oraz samoobsługi konta. Pojedynczy endpoint sprawdzania spamu jest otwarty dla każdego planu; reszta API wchodzi w skład planów Pro i Business.

• POST /spam/check — przepuść jeden tekst przez ten sam silnik reguł, który moderuje ruch na żywo (każdy plan). W planie Pro i wyższych można włączyć opcjonalne sprawdzenie AI.
• POST /spam/check-batch — sprawdź do 20 tekstów w jednym wywołaniu, tylko na regułach (Pro+).
• POST /users/check — sprawdź użytkownika Telegrama: status CAS, sygnały z decyzji antyspamowych Telm i reputację w Twoich grupach (Pro+).
• GET /groups i GET /groups/{id} — wyświetl listę swoich grup i odczytaj dane grupy (Pro+).
• GET i PATCH /groups/{id}/settings — odczytaj i zmień ustawienia ochrony grupy (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — zarządzaj własnymi regułami moderacji (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — zarządzaj białą listą grupy (Pro+).
• GET /groups/{id}/journal i GET /groups/{id}/analytics — odczytaj dziennik moderacji i analitykę (Pro+).
• GET/POST/PATCH/DELETE /webhooks — zarządzaj webhookami zdarzeń w czasie rzeczywistym (Pro+).
• GET /usage i GET /me — sprawdź swój przydział i informacje o kluczu; te wywołania nigdy nie zużywają przydziału (każdy plan).

5Endpoint sprawdzania spamu w szczegółach

POST /spam/check to serce API i jedyny endpoint, który możesz wypróbować w każdym planie. Wyślij treść JSON z tekstem do sprawdzenia; odpowiedź zwraca werdykt, wynik liczbowy, wartość pewności i zalecane działanie, które możesz zastosować we własnym produkcie.

Pojedynczy tekst może mieć do 10 000 znaków. W planie Pro i wyższych możesz włączyć sprawdzenie AI dla trudniejszych przypadków, rozliczane z osobnego dziennego przydziału sprawdzeń AI. Przy dużym wolumenie endpoint wsadowy sprawdza do 20 tekstów w jednym wywołaniu i liczy przydział za każdy element.

• Na podstawie werdyktu i wyniku zdecyduj, co robi Twój produkt — zablokuj wysłanie formularza, oznacz leada albo automatycznie usuń wiadomość we własnym bocie.
• Endpoint wsadowy działa tylko na regułach; drabina AI jest dostępna wyłącznie w endpoincie pojedynczego tekstu.
• Rozmiar treści żądania jest ograniczony (około 64 KB dla pojedynczego sprawdzenia, 256 KB dla wsadu); zbyt duże żądania zwracają 413.

6Plany, limity na minutę i dzienne przydziały

Dostęp jest mierzony na dwa sposoby: limitem na minutę (pułap serii) i dziennym przydziałem wywołań, który resetuje się o północy UTC. Oba są liczone per konto i współdzielone przez wszystkie Twoje klucze API. Pojedynczy endpoint sprawdzania spamu możesz wypróbować w każdym planie, ale prawdziwa integracja, która korzysta z reguł, ustawień, sprawdzeń wsadowych i webhooków, wymaga planu Pro lub wyższego.

• Free — 100 wywołań dziennie, tylko sprawdzanie spamu.
• Pro — 10 000 wywołań dziennie, pełne API i webhooki oraz 1 000 sprawdzeń AI dziennie.
• Business — 50 000 wywołań dziennie, pełne API i webhooki oraz 10 000 sprawdzeń AI dziennie.
• Limity na minutę też rosną — 60 żądań na minutę w Free, 600 w Pro i 1800 w Business.
• GET /usage i GET /me nigdy nie są wliczane do przydziału, więc pozostały budżet możesz sprawdzić w dowolnej chwili.

7Obsługa błędów i kody statusu

API używa standardowych kodów statusu HTTP z maszynowo czytelnym kodem błędu w treści odpowiedzi. Zbuduj klienta tak, aby odczytywał te kody i wycofywał się albo proponował ulepszenie planu, zamiast ponawiać na ślepo.

Gdy przekroczysz dzienny przydział, mierzone wywołanie zwraca 429 z kodem daily_quota_exceeded, nagłówkiem Retry-After i treścią zawierającą Twój plan, limit, liczbę zużytych wywołań, czas resetu i podpowiedź o ulepszeniu. Endpointy wymagające wyższego planu zwracają 403 plan_required z nazwą wymaganego planu.

• 401 — brakujący lub nieprawidłowy klucz API.
• 403 plan_required — endpoint wymaga planu Pro lub wyższego.
• 403 insufficient_scope — klucz nie ma zakresu zapisu dla wywołania zmieniającego dane.
• 429 daily_quota_exceeded lub rate_limit_exceeded — poczekaj do czasu resetu lub ulepsz plan; respektuj nagłówek Retry-After.
• Odczytuj nagłówki odpowiedzi X-Quota-*, aby wyprzedzać limit.

8Dobre praktyki solidnej integracji

Kilka nawyków sprawia, że integracja pozostaje niezawodna i bezpieczna w miarę jej rozwoju.

• Przechowuj klucze w menedżerze sekretów, nigdy w kodzie po stronie klienta ani w repozytorium git; używaj osobnego klucza dla każdej usługi, aby móc unieważnić jeden bez psucia pozostałych.
• Obserwuj nagłówki X-Quota-Used i X-Quota-Limit (albo odpytuj GET /usage) i zwalniaj, zanim uderzysz w ścianę, a nie po fakcie.
• Przy 429 respektuj Retry-After i wycofaj się; przy 403 plan_required pokaż propozycję ulepszenia planu zamiast ponawiać.
• Do reakcji w czasie rzeczywistym wybieraj webhooki zamiast odpytywania — niech Telm sam wypycha do Ciebie zdarzenia.
• Rotuj klucze okresowo, a natychmiast, jeśli któryś mógł wyciec.

9Typowe scenariusze integracji

API służy do znacznie więcej niż moderowania wiadomości na Telegramie.

• Rejestracja na stronie i w aplikacji: przepuść przesłany tekst lub nazwy użytkowników przez POST /spam/check, zanim zaakceptujesz rejestrację lub komentarz.
• Własne boty Telegram: wykorzystaj inteligencję Telm w bocie, którym Telm nie zarządza, wywołując endpoint sprawdzania z kodu obsługi wiadomości.
• Konfiguracja hurtowa: zautomatyzuj skryptem te same reguły, białe listy i ustawienia w dziesiątkach grup za pomocą endpointów ustawień i reguł.
• Dane i alerty: zarejestruj webhooki, aby przesyłać zdarzenia moderacji w czasie rzeczywistym do hurtowni danych, pulpitu analitycznego lub kanału alertów.