1Ce include fiecare plan
Linia de demarcație este simplă. Verificarea textului pentru spam este disponibilă pe orice plan, așa că până și nivelul gratuit poate folosi detecția Telm ca filtru în propriul său produs. Suprafața completă — verificarea utilizatorilor cu niveluri de risc, registrul de decizii și analiza, gestionarea setărilor și a regulilor, și webhook-urile — face parte din planurile Pro și Business.
Fiecare plan primește o cotă zilnică de cereri, dimensionată astfel încât integrările mai grele să stea pe planuri mai grele:
- **Free** — 100 de cereri API pe zi, doar verificare spam.
- **Basic** — 1.000 de cereri API pe zi, doar verificare spam.
- **Pro** — 10.000 de cereri API pe zi, plus suprafața completă a API-ului și webhook-urile.
- **Business** — 50.000 de cereri API pe zi, plus suprafața completă a API-ului și webhook-urile.
- Creează-ți cheile la Settings → API & Webhooks, păstrează-le în seiful tău de secrete, verifică semnătura fiecărui webhook, iar același motor care îți păzește grupurile devine parte din propriul tău stack.
2O evidență interogabilă a fiecărei decizii
Tot ce decide motorul este înregistrat, iar `GET journal` predă acea evidență codului tău. Fiecare intrare este o decizie: verdictul, scorul din spatele lui, ce reguli s-au declanșat și acțiunea care a urmat. Fiindcă este paginată pe cursor, poți parcurge întregul istoric în mod fiabil — pagină după pagină, fără lacune sau duplicate — și îl poți extrage oriunde îți ții evidențele.
Asta face din registru coloana vertebrală a unei arhive de conformitate. Echipele care trebuie să arate de ce a fost eliminat un membru — pentru o politică de platformă, un contract cu clientul sau un reglementator — exportă registrul în propriul lor depozit pe termen lung, după un program, obținând astfel o evidență independentă și interogabilă a fiecărei acțiuni de aplicare, care nu depinde de derularea înapoi prin Telegram. Este aceeași dovadă pe care registrul de audit din tabloul de bord o prezintă oamenilor, pusă la dispoziția sistemelor tale.
Alături de el, un endpoint de analiză returnează serii zi cu zi — volume și tendințe în timp — astfel încât să poți reprezenta grafic sarcina de moderare în propriile tale instrumente de business intelligence, lângă tot ce mai urmărești, în loc să o citești de pe un ecran. Atât registrul, cât și analiza fac parte din planurile Pro și Business.
3Livrare pe care te poți baza
Un model push este demn de încredere doar dacă face față momentelor în care endpoint-ul tău este lent, repornește sau este căzut pentru scurt timp — iar cel al Telm face. Livrarea este cel puțin o dată: fiecare eveniment poartă un `id` stabil, iar Telm continuă să încerce până când endpoint-ul tău îl confirmă. Fiindcă „cel puțin o dată” înseamnă că același eveniment poate sosi în mod legitim de două ori, deduplică pe acel `id` — înregistrează-le pe cele procesate și ignoră repetările — și gestionarea ta rămâne corectă indiferent de câte ori este reîncercată o livrare.
Reîncercările urmează un program care se lărgește, în loc să bombardeze un endpoint în dificultate: imediat, apoi după un minut, cinci minute, treizeci de minute, două ore și șase ore — șase încercări în total, distribuite pentru a da unui serviciu în refacere spațiu să revină. Dacă un endpoint rămâne căzut — douăzeci de eșecuri consecutive și șaptezeci și două de ore fără nicio livrare reușită — Telm încetează automat să îi mai trimită și te anunță pe Telegram, așa că un URL mort devine un avertisment clar de a-ți repara receptorul, în loc de un torent tăcut de eșecuri care se adună.
Pentru a face bine o integrare nouă, nu trebuie să provoci evenimente reale ca să o testezi. Un ping de test îți permite să declanșezi o livrare de probă către endpoint-ul tău la cerere și să confirmi că verificarea semnăturii și handlerul funcționează, iar un istoric al livrărilor arată ce a fost trimis și cum a decurs fiecare încercare — așa că poți depana un receptor care se comportă greșit din evidență, în loc să ghicești.
4Moderare care vorbește cu restul stack-ului tău
Un bot de moderare care trăiește în întregime în interiorul Telegram este util, dar este și o insulă. Deciziile pe care le ia — fiecare mesaj pe care îl elimină, fiecare utilizator pe care îl verifică, fiecare raid pe care îl respinge — rămân blocate într-o fereastră de chat, dacă nu deschide cineva Telegram să se uite. Pentru o singură comunitate, e în regulă. Pentru o echipă care rulează moderarea ca parte a unei operațiuni mai mari, înseamnă că singurul sistem care știe cel mai mult despre cine îți abuzează spațiile este singurul sistem care nu poate comunica cu nimic altceva din ce rulezi.
API-ul REST public și webhook-urile închid acest gol. Ele transformă Telm dintr-un bot autonom într-o componentă pe care o poți conecta la instrumentele pe care le ai deja: configurația ta de monitorizare și de gardă, arhiva ta de conformitate, propriul tău produs, tablourile tale de bord interne. Același motor care îți protejează grupurile devine ceva ce celelalte sisteme ale tale pot interoga, asculta și acționa.
Acest ghid parcurge ceea ce expun cu adevărat API-ul și webhook-urile — endpoint-urile, evenimentele, modelul de securitate — și lucrurile concrete pe care echipele le construiesc cu ele. Tot ce urmează este o capacitate reală, disponibilă astăzi; nu există niciun SDK de așteptat și nimic descris aici pe care produsul doar plănuiește să îl facă.
5Verificarea textelor și a utilizatorilor la cerere
Două endpoint-uri îți permit să rulezi judecata Telm la cerere, din propriul tău cod, fără ca vreun mesaj să treacă vreodată printr-un grup Telegram.
`POST /spam/check` trimite o bucată de text prin exact același motor de producție care îți păzește comunitățile — semnalele partajate despre spammeri, regulile de tipar, clasificatoarele — și returnează un verdict. Acesta este singurul apel disponibil pe orice plan, ceea ce îl face un filtru de spam natural pentru propriul tău produs: verifică comentarii, biografii de înregistrare, tichete de suport sau anunțuri de marketplace cu aceeași detecție care îți protejează spațiile Telegram. Adaugă `include_ai` pentru a include un verdict AI în cazurile mai dificile și mai ambigue (disponibil pe Pro și Business), iar pe aceste planuri poți grupa până la douăzeci de texte într-o singură cerere, în loc să apelezi o dată pentru fiecare element.
`POST /users/check` verifică o persoană, nu un mesaj. Combină lista globală de blocare CAS, setul de date propriu al Telm construit din moderarea în multe comunități, și returnează un nivel de risc (pe Pro și Business), astfel încât să poți decide câtă fricțiune să aplici — lasă un cont curat să treacă direct, reține unul riscant pentru revizuire. Conectarea lui în propriul tău proces de înscriere îți permite să prinzi un actor rău cunoscut chiar la ușa site-ului sau a aplicației tale, nu abia după ce a intrat într-un grup Telegram.
Ambele apeluri răspund pe loc: trimiți textul sau utilizatorul, primești evaluarea înapoi în răspuns. Nu există nicio coadă de interogat și niciun callback de așteptat — decizia vine odată cu răspunsul.
6Să fii împins în clipa în care se întâmplă
Interogarea registrului este bună pentru arhivare, dar când vrei să *reacționezi* la ceva în clipa în care se produce, vrei să fii împins, nu să întrebi. Webhook-urile (pe Pro și Business) fac exact asta: înregistrezi un endpoint, iar Telm îi trimite o cerere HTTP în clipa în care se declanșează un eveniment relevant. Evenimentele acoperă momentele care contează — `spam.detected` și `message.suspicious` pentru conținut, și `user.banned`, `user.kicked`, `user.muted`, `user.joined` și `user.left` pentru apartenență.
Utilizarea evidentă este transformarea unui val de spam într-o alertă. Îndreaptă `spam.detected` către sistemul tău de monitorizare sau de gardă, iar o creștere bruscă devine un apel către cine e de serviciu, în același loc unde ajung celelalte incidente ale tale — nimeni nu trebuie să urmărească Telegram ca să observe începutul unui atac. Același flux alimentează tablouri de bord în timp real, menține un sistem extern sincronizat cu interdicțiile sau declanșează orice proces dorești.
Fiindcă aceste cereri vin din lumea exterioară către infrastructura ta, fiecare livrare este semnată. Fiecare cerere poartă un antet `X-Telm-Signature` de forma `v1=hex(hmac_sha256(secret, "timestamp.body"))` — un HMAC-SHA256 peste marcajul temporal și corpul brut, cu cheie dintr-un secret pe care doar tu și Telm îl împărțiți. Recalcularea acelei semnături de partea ta dovedește că cererea a venit cu adevărat de la Telm și nu a fost falsificată sau modificată în tranzit; marcajul temporal îți permite să respingi reluările vechi. Verifică semnătura înainte să ai încredere în sarcina utilă — sunt câteva linii de cod și cel mai important pas dintr-un receptor de webhook sigur.
7API-ul REST și cheile tale
API-ul se află la `https://api.telm.com/api/public/v1`. Este o interfață REST simplă — o apelezi cu cereri HTTPS obișnuite și JSON, din orice limbaj, fără vreo bibliotecă de client specială. Dacă codul tău poate face o cerere HTTP, poate comunica cu Telm.
Autentificarea se face prin cheie API. Creezi chei în tabloul de bord, la Settings → API & Webhooks, iar fiecare îți este afișată exact o dată la creare — copiaz-o în seiful tău de secrete pe loc, pentru că nu poate fi recuperată ulterior. Cheile au prefixul `tk_live_`, ca să fie ușor de recunoscut în jurnale și configurație. Fiecare cheie poartă un domeniu — citire sau scriere — așa că un serviciu care are nevoie doar să extragă registrul de decizii poate deține o cheie doar-citire, în timp ce automatizarea care modifică setări primește o cheie de scriere. Emite câte o cheie per sistem, iar revocarea unei chei scurse sau retrase nu deranjează niciodată celelalte chei.
Consumul este guvernat de o cotă zilnică de cereri legată de planul tău, așa că debitul este previzibil și un singur script scăpat de sub control nu poate epuiza totul. Cea mai ușoară verificare — scanarea textului pentru spam — este disponibilă pe orice plan, în limita acelei cote; suprafața mai amplă, de la registrul de decizii la gestionarea setărilor și la webhook-uri, face parte din planurile Pro și Business. Cifrele exacte sunt prezentate la final.
8Gestionarea multor grupuri din cod
API-ul nu doar citește și ascultă — el scrie. Pe Pro și Business poți face `PATCH` la setările unui grup și poți rula create/read/update/delete complet asupra regulilor și a listei albe, totul programatic. Orice ai configura manual în tabloul de bord, poți configura dintr-un script.
Asta face practică rularea moderării la scară. O agenție sau un operator mare care gestionează zeci de comunități nu vrea să deschidă fiecare grup și să facă clic prin aceleași modificări; vrea să definească politica o singură dată și să o aplice peste tot. Cu API-ul lansezi o regulă nouă, ajustezi un prag sau adaugi o adresă în fiecare listă albă din toată flota, într-o singură trecere automatizată, și menții grupurile aliniate pe măsură ce standardele tale evoluează.
De asemenea, îți permite ca politica de moderare să trăiască în propriul tău control al versiunilor. Păstrează configurația dorită sub formă de cod, aplic-o prin API, iar fiecare schimbare a modului în care sunt guvernate grupurile tale este revizuită și versionată ca restul infrastructurii tale — departe de a-ți aminti ce setări ai comutat în ce chat.