1Moderacja, która rozmawia z resztą Twojego stacku
Bot moderacyjny żyjący wyłącznie wewnątrz Telegrama jest przydatny, ale jest też wyspą. Decyzje, które podejmuje — każda usunięta wiadomość, każdy zweryfikowany użytkownik, każdy odparty nalot — pozostają zamknięte w oknie czatu, dopóki ktoś nie otworzy Telegrama, żeby zajrzeć. Dla jednej społeczności to w porządku. Dla zespołu prowadzącego moderację jako część większej operacji oznacza to, że jedyny system, który wie najwięcej o tym, kto nadużywa Twoich przestrzeni, jest zarazem jedynym systemem, który nie potrafi rozmawiać z niczym innym, co uruchamiasz.
Publiczne REST API i webhooki domykają tę lukę. Zamieniają Telm z samowystarczalnego bota w komponent, który wpleciesz w narzędzia, które już masz: Twój monitoring i dyżury, Twoje archiwum zgodności, Twój własny produkt, Twoje wewnętrzne pulpity. Ten sam silnik, który chroni Twoje grupy, staje się czymś, co inne Twoje systemy mogą odpytywać, czego mogą słuchać i czym mogą sterować.
Ten przewodnik przechodzi przez to, co API i webhooki faktycznie udostępniają — endpointy, zdarzenia, model bezpieczeństwa — oraz przez konkretne rzeczy, które zespoły na nich budują. Wszystko poniżej to realna funkcja dostępna już dziś; nie ma żadnego SDK, na które trzeba czekać, ani niczego opisanego tu, co produkt dopiero planuje zrobić.
2REST API i Twoje klucze
API mieszka pod `https://api.telm.com/api/public/v1`. To zwykły interfejs REST — wywołujesz go najzwyklejszymi żądaniami HTTPS i JSON-em, z dowolnego języka, bez potrzeby specjalnej biblioteki klienckiej. Jeśli Twój kod potrafi wykonać żądanie HTTP, potrafi rozmawiać z Telm.
Uwierzytelnianie odbywa się kluczem API. Klucze tworzysz w panelu w sekcji Settings → API & Webhooks, a każdy z nich jest pokazywany dokładnie raz przy tworzeniu — skopiuj go od razu do swojego magazynu sekretów, bo później nie da się go już odzyskać. Klucze mają przedrostek `tk_live_`, więc łatwo je rozpoznać w logach i konfiguracji. Każdy klucz niesie zakres — odczyt lub zapis — więc usługa, która potrzebuje tylko pobierać dziennik decyzji, może mieć klucz tylko do odczytu, podczas gdy automatyzacja zmieniająca ustawienia dostaje klucz do zapisu. Wybij po jednym kluczu na system, a unieważnienie wycieklego lub wycofanego klucza nigdy nie zakłóci pozostałych.
Wykorzystaniem rządzi dzienny limit żądań powiązany z Twoim planem, więc przepustowość jest przewidywalna, a jeden rozszalały skrypt nie wyczerpie wszystkiego. Najlżejsze sprawdzenie — skanowanie tekstu pod kątem spamu — jest dostępne w każdym planie w ramach tego limitu; pełniejszy zakres, od dziennika decyzji po zarządzanie ustawieniami i webhooki, jest częścią planów Pro i Business. Dokładne liczby wyłożone są na końcu.
3Weryfikacja tekstów i użytkowników na żądanie
Dwa endpointy pozwalają uruchomić ocenę Telm na żądanie, z poziomu własnego kodu, bez konieczności, by wiadomość kiedykolwiek przeszła przez grupę Telegrama.
`POST /spam/check` przepuszcza fragment tekstu przez dokładnie ten produkcyjny silnik, który strzeże Twoich społeczności — wspólne sygnały o spamerach, reguły wzorców, klasyfikatory — i zwraca werdykt. To jedyne wywołanie dostępne w każdym planie, co czyni je naturalnym filtrem spamu dla Twojego własnego produktu: weryfikuj komentarze, biogramy z rejestracji, zgłoszenia do wsparcia czy ogłoszenia na marketplace tym samym wykrywaniem, które chroni Twoje przestrzenie na Telegramie. Dodaj `include_ai`, by dołączyć werdykt AI dla trudniejszych, bardziej niejednoznacznych przypadków (dostępne w Pro i Business), a w tych planach możesz zebrać do dwudziestu tekstów w jednym żądaniu zamiast wołać raz na pozycję.
`POST /users/check` weryfikuje osobę, a nie wiadomość. Łączy globalną listę blokad CAS z własnym zbiorem danych Telm, zbudowanym z moderacji w wielu społecznościach, i zwraca poziom ryzyka (w Pro i Business), byś mógł zdecydować, ile tarcia zastosować — czyste konto przepuść od razu, ryzykowne wstrzymaj do przeglądu. Wpięcie go we własny onboarding pozwala złapać znanego szkodnika już u bram Twojej strony czy aplikacji, a nie dopiero po tym, jak dołączy do grupy Telegrama.
Oba wywołania odpowiadają od ręki: wysyłasz tekst lub użytkownika, a ocenę dostajesz z powrotem w odpowiedzi. Nie ma kolejki do odpytywania ani callbacku, na który trzeba czekać — decyzja przychodzi razem z odpowiedzią.
4Bądź wypychany w chwili, gdy się dzieje
Odpytywanie dziennika sprawdza się przy archiwizacji, ale gdy chcesz *zareagować* na coś w chwili, gdy się dzieje, chcesz być wypychany, a nie pytać. Webhooki (w Pro i Business) robią dokładnie to: rejestrujesz endpoint, a Telm wysyła na niego żądanie HTTP w chwili, gdy uruchomi się istotne zdarzenie. Zdarzenia obejmują momenty, które się liczą — `spam.detected` i `message.suspicious` dla treści oraz `user.banned`, `user.kicked`, `user.muted`, `user.joined` i `user.left` dla członkostwa.
Oczywiste zastosowanie to zamiana fali spamu w alert. Skieruj `spam.detected` do swojego monitoringu lub systemu dyżurów, a nagły skok stanie się wezwaniem dla tego, kto akurat pełni służbę, w tym samym miejscu, w którym lądują inne Twoje incydenty — nikt nie musi wpatrywać się w Telegram, żeby zauważyć początek ataku. Ten sam strumień zasila pulpity czasu rzeczywistego, utrzymuje zewnętrzny system w synchronizacji z banami albo wyzwala dowolny proces, jaki lubisz.
Ponieważ te żądania przychodzą ze świata zewnętrznego do Twojej infrastruktury, każde dostarczenie jest podpisane. Każde żądanie niesie nagłówek `X-Telm-Signature` w postaci `v1=hex(hmac_sha256(secret, "timestamp.body"))` — HMAC-SHA256 z znacznika czasu i surowej treści, kluczowany sekretem, który znasz tylko Ty i Telm. Przeliczenie tego podpisu po swojej stronie dowodzi, że żądanie naprawdę pochodzi z Telm i nie zostało podrobione ani naruszone w tranzycie; znacznik czasu pozwala odrzucić stare powtórzenia (replay). Zweryfikuj podpis, zanim zaufasz ładunkowi — to kilka linijek kodu i najważniejszy pojedynczy krok w bezpiecznym odbiorniku webhooków.
5Dostarczanie, na którym można polegać
Model wypychania jest godny zaufania tylko wtedy, gdy radzi sobie z chwilami, w których Twój endpoint jest wolny, restartuje się albo krótko pada — i model Telm sobie radzi. Dostarczanie jest co najmniej raz: każde zdarzenie niesie stabilne `id`, a Telm próbuje dalej, aż Twój endpoint je potwierdzi. Ponieważ „co najmniej raz” oznacza, że to samo zdarzenie może zgodnie z prawem przyjść dwa razy, deduplikuj po tym `id` — zapisuj te, które przetworzyłeś, i ignoruj powtórki — a Twoja obsługa pozostanie poprawna niezależnie od tego, ile razy dostarczenie zostanie ponowione.
Ponowienia idą wg rozszerzającego się harmonogramu, zamiast młócić borykający się endpoint: natychmiast, potem po jednej minucie, pięciu minutach, trzydziestu minutach, dwóch godzinach i sześciu godzinach — łącznie sześć prób, rozłożonych tak, by dać wracającej do formy usłudze przestrzeń na powrót. Jeśli endpoint pozostaje zepsuty — dwadzieścia niepowodzeń z rzędu i siedemdziesiąt dwie godziny bez ani jednego udanego dostarczenia — Telm automatycznie przestaje na niego wysyłać i powiadamia Cię na Telegramie, więc martwy URL staje się jasnym sygnałem do naprawy odbiornika, a nie cichą lawiną piętrzących się niepowodzeń.
By dopiąć nową integrację na ostatni guzik, nie musisz prowokować prawdziwych zdarzeń, żeby ją przetestować. Testowy ping pozwala wystrzelić przykładowe dostarczenie na Twój endpoint na żądanie i potwierdzić, że Twoje sprawdzanie podpisu i handler działają, a historia dostarczeń pokazuje, co zostało wysłane i jak wypadła każda próba — więc niesprawny odbiornik zdebugujesz z zapisu, zamiast zgadywać.
6Odpytywalny zapis każdej decyzji
Wszystko, co silnik rozstrzygnie, jest zapisywane, a `GET journal` wręcza ten zapis Twojemu kodowi. Każdy wpis to jedna decyzja: werdykt, ocena za nim stojąca, które reguły się uruchomiły i jakie działanie po tym nastąpiło. Ponieważ używa paginacji kursorowej, możesz przejść całą historię niezawodnie — strona po stronie, bez luk i duplikatów — i wciągnąć ją tam, gdzie trzymasz swoje zapisy.
To czyni z dziennika kręgosłup archiwum zgodności. Zespoły, które muszą wykazać, dlaczego członek został usunięty — dla polityki platformy, kontraktu z klientem czy regulatora — eksportują dziennik do własnego długoterminowego magazynu wg harmonogramu, zyskując niezależny, odpytywalny zapis każdego działania egzekucyjnego, który nie zależy od przewijania w tył Telegrama. To ten sam materiał dowodowy, który dziennik audytu w panelu prezentuje ludziom, udostępniony Twoim systemom.
Obok niego endpoint analityki zwraca serie dzień po dniu — wolumeny i trendy w czasie — więc obciążenie moderacji możesz wykreślać we własnych narzędziach business intelligence obok wszystkiego, co śledzisz, zamiast odczytywać je z ekranu. Zarówno dziennik, jak i analityka są częścią planów Pro i Business.
7Zarządzanie wieloma grupami z poziomu kodu
API nie tylko odczytuje i słucha — także zapisuje. W Pro i Business możesz metodą `PATCH` zmienić ustawienia grupy oraz wykonywać pełne tworzenie/odczyt/aktualizację/usuwanie na jej regułach i białej liście, wszystko programowo. Cokolwiek skonfigurowałbyś ręcznie w panelu, skonfigurujesz ze skryptu.
To właśnie sprawia, że prowadzenie moderacji na dużą skalę staje się praktyczne. Agencja albo duży operator zarządzający dziesiątkami społeczności nie chce otwierać każdej z osobna i przeklikiwać tych samych zmian; chce zdefiniować politykę raz i zastosować ją wszędzie. Z API wdrażasz nową regułę, dostrajasz próg albo dodajesz adres do każdej białej listy w całej flocie jednym zautomatyzowanym przebiegiem i utrzymujesz grupy w jednym rytmie, w miarę jak Twoje standardy ewoluują.
Pozwala też polityce moderacji żyć we własnej kontroli wersji. Trzymaj pożądaną konfigurację jako kod, stosuj ją przez API, a każda zmiana w tym, jak rządzone są Twoje grupy, jest recenzowana i wersjonowana jak reszta Twojej infrastruktury — daleko od pamiętania, które ustawienia przełączyłeś w którym czacie.
8Co obejmuje każdy plan
Linia podziału jest prosta. Sprawdzanie tekstu pod kątem spamu jest dostępne w każdym planie, więc nawet darmowy poziom może użyć wykrywania Telm jako filtra we własnym produkcie. Pełny zakres — weryfikacja użytkowników z poziomami ryzyka, dziennik decyzji i analityka, zarządzanie ustawieniami i regułami oraz webhooki — jest częścią planów Pro i Business.
Każdy plan dostaje dzienny limit żądań, dobrany tak, by cięższe integracje siadały na cięższych planach:
- **Free** — 100 żądań API dziennie, tylko sprawdzanie spamu.
- **Basic** — 1 000 żądań API dziennie, tylko sprawdzanie spamu.
- **Pro** — 10 000 żądań API dziennie, plus pełny zakres API i webhooki.
- **Business** — 50 000 żądań API dziennie, plus pełny zakres API i webhooki.
- Utwórz swoje klucze w sekcji Settings → API & Webhooks, trzymaj je w magazynie sekretów, weryfikuj podpis każdego webhooka, a ten sam silnik, który strzeże Twoich grup, stanie się częścią Twojego własnego stacku.