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

1Ce vă permite API-ul să faceți

REST API-ul Telm oferă propriului dumneavoastră cod aceeași putere ca tabloul de bord: rulați orice text prin fluxul anti-spam, căutaț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.

Asta transformă Telm dintr-un bot care trăiește în interiorul grupurilor dumneavoastră într-o infrastructură pe care o puteți conecta oriunde — un formular de înregistrare pe un site web, 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ă, cu versiune (v1 este versiunea contractului).
• Fiecare cerere și răspuns este JSON prin HTTPS.
• Documentația interactivă și specificația OpenAPI 3.1 care poate fi citită automat se află pe pagina dezvoltatorilor — încărcați specificația în Postman, un generator de cod sau un agent AI pentru a schița o integrare în câteva minute.
• Apelurile măsurate returnează antetele X-Quota-Limit, X-Quota-Used și X-Quota-Reset la fiecare răspuns.

2Cum circulă o cerere prin Telm

API-ul public trăiește pe propriul său prefix de cale, /api/public/, separat de tabloul de bord. Fiecare apel este autentificat de o cheie API în loc de 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 aceleași date ca botul, orice puteți vedea sau modifica în tabloul de bord puteți face și în cod — iar orice modificare pe care o faceți în cod apare imediat în tabloul de bord.

• Cererile sunt fără stare: fiecare își poartă propria cheie și se susține de una singură.
• O cheie acționează în numele contului dumneavoastră și poate atinge doar grupuri unde contul dumneavoastră este administrator.
• Punctul final de verificare a spamului ajunge la fluxul exact de reguli de producție, așa că un verdict API se potrivește 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 autentificarea dumneavoastră la tabloul de bord. Creați chei î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 momentul creării. După aceea, tabloul de bord listează o cheie doar prin prefixul ei scurt, așa că 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 în aproximativ un minut.

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

4Puncte finale disponibile

API-ul este organizat în jurul verificărilor de spam și de utilizatori, gestionării grupurilor și autoservirii contului. Punctul final unic de verificare a spamului este deschis fiecărui plan; restul suprafeței face parte din Pro și Business.

• POST /spam/check — rulați un text prin același motor de reguli care moderează traficul live (fiecare plan). O verificare AI opțională poate fi activată pe Pro și superioare.
• POST /spam/check-batch — verificați până la 20 de texte într-un singur apel, doar cu reguli (Pro+).
• POST /users/check — căutați un utilizator Telegram: statut CAS, semnale de decizie de spam Telm și reputație în grupurile dumneavoastră (Pro+).
• GET /groups și GET /groups/{id} — listați și citiți grupurile dumneavoastră (Pro+).
• GET și PATCH /groups/{id}/settings — citiți și modificați setările de protecție ale unui grup (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — gestionați reguli de moderare personalizate (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — gestionați lista albă a grupului (Pro+).
• GET /groups/{id}/journal și GET /groups/{id}/analytics — citiți jurnalul de moderare și analizele (Pro+).
• GET/POST/PATCH/DELETE /webhooks — gestionați webhook-urile de evenimente în timp real (Pro+).
• GET /usage și GET /me — verificați cota și informațiile despre cheie; acestea nu consumă niciodată cotă (fiecare plan).

5Punctul final de verificare a spamului în detaliu

POST /spam/check este inima API-ului și singurul punct final 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 și superioare puteți opta pentru o verificare AI pentru cazurile mai dificile, extrasă dintr-o alocație zilnică separată de verificări AI. Pentru volum mare, punctul final în lot verifică până la 20 de texte într-un singur apel și numără cota per element.

• Folosiți verdictul și scorul pentru a decide ce face propriul dumneavoastră produs — blocați o trimitere de formular, semnalați un lead sau eliminați automat un mesaj în propriul dumneavoastră bot.
• Punctul final în lot este doar pe bază de reguli; scara AI este disponibilă doar pe punctul final cu un singur text.
• Corpurile cererilor sunt plafonate (aproximativ 64 KB pentru o verificare unică, 256 KB pentru un lot); corpurile supradimensionate returnează 413.

6Planuri, limite de rată și cote zilnice

Accesul este măsurat î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 se scalează cu planul dumneavoastră și se numără pe cont, partajate între toate cheile dumneavoastră. Puteți încerca punctul final unic de verificare a spamului pe orice plan, dar o integrare reală care atinge reguli, setări, verificări în lot și webhook-uri necesită Pro sau superior.

• Free — 100 de apeluri/zi, doar verificare de spam.
• Basic — 1.000 de apeluri/zi, doar verificare de spam.
• Pro — 10.000 de apeluri/zi, API complet și webhook-uri, plus o alocație zilnică de verificări AI.
• Business — 50.000 de apeluri/zi, API complet și webhook-uri, alocație AI mai mare.
• Limitele de rată pe minut se scalează și ele — planurile superioare primesc un plafon de vârf mult mai mare.

7Gestionarea erorilor și coduri de status

API-ul folosește coduri de status HTTP standard, cu un cod de eroare care poate fi citit automat în corp. Construiți-vă clientul să citească aceste coduri și să se retragă sau să solicite un upgrade, în loc să reîncerce orbește.

Când depășiți cota zilnică, un apel măsurat returnează 429 cu un cod daily_quota_exceeded, un antet Retry-After și un corp care listează planul, limita, numărul folosit, ora de resetare și un indiciu de upgrade. Punctele finale care necesită un plan superior returnează 403 plan_required cu planul necesar.

• 401 — cheie API lipsă sau nevalidă.
• 403 plan_required — punctul final necesită Pro sau superior.
• 403 insufficient_scope — cheii îi lipsește domeniul de scriere pentru un apel care modifică.
• 429 daily_quota_exceeded sau rate_limit_exceeded — așteptați ora de resetare sau faceți upgrade; respectați antetul Retry-After.
• Citiți antetele de răspuns X-Quota-* pentru a rămâne înaintea limitei.

8Bune practici pentru o integrare solidă

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

• Stocaț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, ca să puteți revoca una fără a le strica pe celelalte.
• Urmăriți antetele X-Quota-Used și X-Quota-Limit (sau interogați GET /usage) și temperați ritmul înainte de a atinge limita, nu după.
• La 429, respectați Retry-After și retrageți-vă; la 403 plan_required, afișați un mesaj de upgrade în loc să reîncercați.
• Pentru reacții în timp real, preferați webhook-urile în locul interogării — lăsați Telm să vă trimită evenimentele.
• Rotiți cheile periodic și imediat dacă una s-ar putea să se fi scurs.

9Scenarii de integrare frecvente

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

• Înregistrare pe site și în aplicație: rulați textul sau numele de utilizator trimise prin POST /spam/check înainte de a accepta o înregistrare sau un comentariu.
• Propriii dumneavoastră boți Telegram: reutilizați inteligența Telm într-un bot pe care Telm nu îl gestionează, apelând punctul final de verificare din handlerul dumneavoastră.
• Configurare în masă: scriptați aceleași reguli, liste albe și setări în zeci de grupuri cu punctele finale de setări și reguli.
• Date și alertare: înregistrați webhook-uri pentru a transmite evenimentele de moderare într-un depozit de date, un tablou de bord sau un canal de alertare în timp real.