REST API — automatizați Telm din propriul dumneavoastră cod

1Ce vă permite API-ul

API-ul REST Telm oferă codului dumneavoastră aceeași acoperire ca tabloul de bord: treceți orice text prin fluxul de verificare antispam, verificați un utilizator Telegram înainte de a-l lăsa să intre, citiți și modificați setările de protecție ale unui grup, gestionați reguli personalizate și liste albe, extrageți jurnalul de moderare și analizele și înregistrați webhook-uri pentru evenimente în timp real.

Astfel, Telm nu mai este doar un bot care trăiește în grupurile dumneavoastră, ci devine o infrastructură pe care o puteți conecta oriunde — un formular de înregistrare pe site, un bot CRM, propriii dumneavoastră boți Telegram sau un script care configurează o sută de grupuri deodată.

• URL de bază: api.telm.com/api/public/v1 — o cale stabilă, versionată (v1 este versiunea contractului).
• Toate cererile și răspunsurile sunt JSON prin HTTPS.
• Documentația interactivă și specificația OpenAPI 3.1, interpretabilă de mașină, se află pe pagina pentru dezvoltatori — încărcați specificația în Postman, într-un generator de cod sau într-un agent AI pentru a schița o integrare în câteva minute.
• Apelurile contorizate returnează anteturile X-Quota-Limit, X-Quota-Used și X-Quota-Reset la fiecare răspuns.

2Cum circulă o cerere prin Telm

API-ul public are propriul prefix de cale, /api/public/, separat de tabloul de bord. Fiecare apel este autentificat printr-o cheie API, nu printr-o sesiune de browser, verificat în raport cu planul și cota dumneavoastră, rulat pe același motor live care vă moderează grupurile și returnat ca JSON.

Deoarece API-ul ajunge la același motor și la aceleași date ca botul, tot ce puteți vedea sau modifica în tabloul de bord puteți face și din cod — iar orice modificare făcută din cod apare imediat în tabloul de bord.

• Cererile nu păstrează starea: fiecare își poartă propria cheie și este complet independentă.
• O cheie acționează în numele contului dumneavoastră și poate atinge doar grupuri unde contul dumneavoastră este administrator.
• Endpoint-ul de verificare a spamului folosește exact fluxul de reguli din producție, așa că un verdict API coincide cu ceea ce ar face botul în grup.

3Autentificarea cu chei API

Fiecare cerere este autentificată cu o cheie API de forma tk_live_ urmat de caractere aleatorii — nu cu autentificarea dumneavoastră din tabloul de bord. Creați cheile în contul dumneavoastră și trimiteți cheia în antetul Authorization ca token Bearer sau într-un antet X-API-Key.

Secretul complet este afișat o singură dată, la creare. După aceea, tabloul de bord listează o cheie doar după prefixul ei scurt, astfel încât să o puteți recunoaște fără a stoca vreodată valoarea completă. Dacă o cheie se scurge, revocați-o și emiteți una nouă — revocarea intră în vigoare imediat.

• Trimiteți cheia ca Authorization: Bearer tk_live_your_key_here (funcționează și un antet X-API-Key).
• Cheile au un domeniu de acces read sau write — read pentru cererile GET, write pentru orice operațiune care modifică date. O cheie doar de citire nu poate crea sau edita nimic.
• Puteți avea până la zece chei active simultan, așa că puteți folosi o cheie separată pentru fiecare script sau serviciu.
• O cheie lipsă sau invalidă returnează 401; o cheie fără domeniul de acces necesar returnează 403 insufficient_scope.

4Endpoint-uri disponibile

API-ul este organizat în jurul verificărilor de spam și de utilizatori, al gestionării grupurilor și al gestionării propriului cont. Endpoint-ul individual de verificare a spamului este deschis tuturor planurilor; restul API-ului face parte din Pro și Business.

• POST /spam/check — trece un text prin același motor de reguli care moderează traficul live (toate planurile). O verificare AI opțională poate fi activată pe Pro sau superior.
• POST /spam/check-batch — verifică până la 20 de texte într-un singur apel, doar cu reguli (Pro+).
• POST /users/check — verifică un utilizator Telegram: statusul CAS, semnalele deciziilor de spam Telm și reputația în grupurile dumneavoastră (Pro+).
• GET /groups și GET /groups/{id} — listează și citește grupurile dumneavoastră (Pro+).
• GET și PATCH /groups/{id}/settings — citește și modifică setările de protecție ale unui grup (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — gestionează regulile de moderare personalizate (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — gestionează lista albă a grupului (Pro+).
• GET /groups/{id}/journal și GET /groups/{id}/analytics — citesc jurnalul de moderare și analizele (Pro+).
• GET/POST/PATCH/DELETE /webhooks — gestionează webhook-urile pentru evenimente în timp real (Pro+).
• GET /usage și GET /me — verifică cota și informațiile despre cheie; acestea nu consumă niciodată din cotă (toate planurile).

5Endpoint-ul de verificare a spamului în detaliu

POST /spam/check este inima API-ului și singurul endpoint pe care îl puteți încerca pe orice plan. Trimiteți un corp JSON cu textul de verificat; răspunsul returnează un verdict, un scor numeric, o valoare de încredere și o acțiune recomandată pe care o puteți aplica în propriul dumneavoastră produs.

Un singur text poate avea până la 10.000 de caractere. Pe Pro sau superior puteți opta pentru o verificare AI în cazurile mai dificile, din limita zilnică separată de verificări AI. Pentru volume mari, endpoint-ul de lot verifică până la 20 de texte într-un singur apel și consumă cotă per element.

• Folosiți verdictul și scorul pentru a decide ce face propriul dumneavoastră produs — blocați trimiterea unui formular, marcați un potențial client sau eliminați automat un mesaj în propriul dumneavoastră bot.
• Endpoint-ul de lot folosește doar reguli; nivelul AI este disponibil doar pe endpoint-ul pentru un singur text.
• Corpurile cererilor sunt plafonate (aproximativ 64 KB pentru o verificare individuală, 256 KB pentru un lot); corpurile prea mari returnează 413.

6Planuri, limite de rată și cote zilnice

Accesul este contorizat în două moduri: o limită de rată pe minut (un plafon de vârf) și o cotă zilnică de apeluri care se resetează la miezul nopții UTC. Ambele sunt numărate per cont și partajate între toate cheile dumneavoastră API. Puteți încerca endpoint-ul individual de verificare a spamului pe orice plan, dar o integrare reală care lucrează cu reguli, setări, verificări în lot și webhook-uri necesită Pro sau superior.

• Free — 100 de apeluri/zi, doar verificarea spamului.
• Pro — 10.000 de apeluri/zi, API complet și webhook-uri, plus 1.000 de verificări AI pe zi.
• Business — 50.000 de apeluri/zi, API complet și webhook-uri, plus 10.000 de verificări AI pe zi.
• Limitele de rată pe minut cresc și ele — 60 de cereri pe minut pe Free, 600 pe Pro și 1.800 pe Business.
• GET /usage și GET /me nu se scad niciodată din cotă, așa că vă puteți verifica bugetul rămas oricând.

7Gestionarea erorilor și codurile de status

API-ul folosește coduri de status HTTP standard, cu un cod de eroare interpretabil de mașină în corp. Construiți-vă clientul astfel încât să citească aceste coduri și să încetinească sau să propună un upgrade, în loc să reîncerce orbește.

Când vă depășiți cota zilnică, un apel contorizat returnează 429 cu un cod daily_quota_exceeded, un antet Retry-After și un corp care indică planul, limita, numărul de apeluri consumate, momentul resetării și o sugestie de upgrade. Endpoint-urile care necesită un plan superior returnează 403 plan_required, împreună cu planul necesar.

• 401 — cheie API lipsă sau invalidă.
• 403 plan_required — endpoint-ul necesită Pro sau superior.
• 403 insufficient_scope — cheii îi lipsește domeniul de acces write pentru un apel care modifică date.
• 429 daily_quota_exceeded sau rate_limit_exceeded — așteptați momentul resetării sau faceți upgrade; respectați antetul Retry-After.
• Citiți anteturile de răspuns X-Quota-* pentru a anticipa atingerea limitei.

8Bune practici pentru o integrare solidă

Câteva obiceiuri mențin o integrare fiabilă și sigură pe măsură ce crește.

• Păstrați cheile într-un manager de secrete, niciodată în cod de partea clientului sau într-un depozit git; folosiți o cheie separată pentru fiecare serviciu, astfel încât să puteți revoca una fără să le afectați pe celelalte.
• Urmăriți anteturile X-Quota-Used și X-Quota-Limit (sau interogați GET /usage) și încetiniți înainte de a atinge limita, nu după.
• La 429, respectați Retry-After și reduceți ritmul; la 403 plan_required, afișați o invitație de upgrade în loc să reîncercați.
• Pentru reacții în timp real, preferați webhook-urile în locul interogării repetate — lăsați Telm să vă trimită evenimentele.
• Rotiți cheile periodic și imediat dacă una s-ar fi putut scurge.

9Scenarii de integrare frecvente

API-ul este folosit pentru mult mai mult decât moderarea mesajelor din Telegram.

• Înregistrare pe site și în aplicații: treceți textul trimis sau numele de utilizator prin POST /spam/check înainte de a accepta o înregistrare sau un comentariu.
• Propriii dumneavoastră boți Telegram: refolosiți inteligența Telm într-un bot pe care Telm nu îl gestionează, apelând endpoint-ul de verificare din handlerul dumneavoastră.
• Configurare în masă: aplicați prin script aceleași reguli, liste albe și setări în zeci de grupuri, cu endpoint-urile de setări și de reguli.
• Date și alerte: înregistrați webhook-uri pentru a transmite evenimentele de moderare în timp real către un depozit de date, un tablou de bord sau un canal de alertare.