REST API: automatizzi Telm dal Suo codice

1Cosa Le permette di fare l'API

La REST API di Telm dà al Suo codice la stessa portata della dashboard: far passare qualsiasi testo nella pipeline antispam, verificare un utente Telegram prima di farlo entrare, leggere e modificare le impostazioni di protezione di un gruppo, gestire regole personalizzate e whitelist, ottenere il registro di moderazione e le analisi, e registrare webhook per gli eventi in tempo reale.

In questo modo Telm smette di essere un bot che vive all'interno dei Suoi gruppi e diventa un'infrastruttura da collegare ovunque: un modulo di registrazione su un sito web, un bot CRM, i Suoi bot Telegram o uno script che configura cento gruppi contemporaneamente.

• URL di base: api.telm.com/api/public/v1, un percorso stabile e con versione (v1 è la versione del contratto).
• Tutte le richieste e le risposte sono in JSON su HTTPS.
• La documentazione interattiva e la specifica OpenAPI 3.1 leggibile dalle macchine si trovano nella pagina per sviluppatori: carichi la specifica in Postman, in un generatore di codice o in un agente IA per impostare un'integrazione in pochi minuti.
• Le chiamate conteggiate restituiscono le intestazioni X-Quota-Limit, X-Quota-Used e X-Quota-Reset in ogni risposta.

2Come una richiesta attraversa Telm

L'API pubblica ha un proprio prefisso di percorso, /api/public/, separato dalla dashboard. Ogni chiamata viene autenticata con una chiave API anziché con una sessione del browser, verificata rispetto al Suo piano e alla Sua quota, eseguita sullo stesso motore in produzione che modera i Suoi gruppi e restituita in JSON.

Poiché l'API raggiunge lo stesso motore e gli stessi dati del bot, tutto ciò che può vedere o modificare nella dashboard può farlo anche dal codice, e ogni modifica effettuata dal codice compare subito nella dashboard.

• Le richieste sono stateless: ciascuna porta con sé la propria chiave ed è indipendente.
• Una chiave agisce per conto del Suo account e può intervenire solo sui gruppi in cui il Suo account è amministratore.
• L'endpoint di controllo dello spam usa esattamente la stessa pipeline di regole di produzione, quindi il verdetto dell'API coincide con ciò che farebbe il bot nel gruppo.

3Autenticazione con le chiavi API

Ogni richiesta viene autenticata con una chiave API nel formato tk_live_ seguito da caratteri casuali, non con il Suo accesso alla dashboard. Crea le chiavi nel Suo account e invia la chiave nell'intestazione Authorization come token Bearer, oppure in un'intestazione X-API-Key.

Il segreto completo viene mostrato una sola volta, al momento della creazione. Dopodiché la dashboard elenca ogni chiave solo tramite il suo breve prefisso, così può riconoscerla senza mai conservare il valore completo. Se una chiave viene compromessa, la revochi e ne generi una nuova: la revoca ha effetto immediato.

• Invii la chiave come Authorization: Bearer tk_live_your_key_here (funziona anche un'intestazione X-API-Key).
• Le chiavi hanno un ambito di lettura o di scrittura: lettura per le richieste GET, scrittura per tutto ciò che modifica i dati. Una chiave di sola lettura non può creare né modificare.
• Può avere fino a dieci chiavi attive contemporaneamente, così da usare una chiave diversa per ogni script o servizio.
• Una chiave mancante o non valida restituisce 401; una chiave senza l'ambito richiesto restituisce 403 insufficient_scope.

4Endpoint disponibili

L'API è organizzata attorno ai controlli dello spam e degli utenti, alla gestione dei gruppi e al self-service dell'account. L'endpoint di controllo dello spam singolo è aperto a tutti i piani; il resto fa parte di Pro e Business.

• POST /spam/check: fa passare un testo nello stesso motore di regole che modera il traffico reale (tutti i piani). Su Pro e superiori è possibile attivare un controllo facoltativo con IA.
• POST /spam/check-batch: controlla fino a 20 testi in una sola chiamata, solo con le regole (Pro+).
• POST /users/check: verifica un utente Telegram: stato CAS, segnali dalle decisioni antispam di Telm e reputazione nei Suoi gruppi (Pro+).
• GET /groups e GET /groups/{id}: elenca e legge i Suoi gruppi (Pro+).
• GET e PATCH /groups/{id}/settings: legge e modifica le impostazioni di protezione di un gruppo (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules: gestisce le regole di moderazione personalizzate (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist: gestisce la whitelist del gruppo (Pro+).
• GET /groups/{id}/journal e GET /groups/{id}/analytics: legge il registro di moderazione e le analisi (Pro+).
• GET/POST/PATCH/DELETE /webhooks: gestisce i webhook per gli eventi in tempo reale (Pro+).
• GET /usage e GET /me: verifica la quota e le informazioni sulla chiave; non consumano mai quota (tutti i piani).

5L'endpoint di controllo dello spam nel dettaglio

POST /spam/check è il cuore dell'API e l'unico endpoint che può provare con qualsiasi piano. Invii un corpo JSON con il testo da controllare; la risposta restituisce un verdetto, un punteggio numerico, un valore di confidenza e un'azione consigliata da applicare nel Suo prodotto.

Un singolo testo può contenere fino a 10.000 caratteri. Su Pro e superiori può attivare un controllo con IA per i casi più difficili, scalato da una quota giornaliera separata di controlli con IA. Per volumi elevati, l'endpoint in batch controlla fino a 20 testi in una sola chiamata e conteggia la quota per elemento.

• Usi il verdetto e il punteggio per decidere cosa fa il Suo prodotto: bloccare l'invio di un modulo, segnalare un lead o rimuovere automaticamente un messaggio nel Suo bot.
• L'endpoint in batch usa solo le regole; la scala di IA è disponibile solo sull'endpoint a testo singolo.
• I corpi delle richieste hanno un limite di dimensione (circa 64 KB per un controllo singolo, 256 KB per un batch); i corpi troppo grandi restituiscono 413.

6Piani, limiti di frequenza e quote giornaliere

L'accesso viene misurato in due modi: un limite di frequenza al minuto (un tetto per i picchi) e una quota giornaliera di chiamate che si azzera a mezzanotte UTC. Entrambi vengono conteggiati per account e condivisi tra tutte le Sue chiavi API. Può provare l'endpoint di controllo dello spam singolo con qualsiasi piano, ma un'integrazione reale che usa regole, impostazioni, controlli in batch e webhook richiede Pro o un piano superiore.

• Free: 100 chiamate/giorno, solo controllo dello spam.
• Pro: 10.000 chiamate/giorno, API completa e webhook, più 1.000 controlli con IA al giorno.
• Business: 50.000 chiamate/giorno, API completa e webhook, più 10.000 controlli con IA al giorno.
• Anche i limiti di frequenza al minuto crescono: 60 richieste al minuto su Free, 600 su Pro e 1.800 su Business.
• GET /usage e GET /me non vengono mai conteggiati nella quota, così può verificare in qualsiasi momento quanto Le resta.

7Gestione degli errori e codici di stato

L'API usa codici di stato HTTP standard con un codice di errore leggibile dalle macchine nel corpo della risposta. Progetti il Suo client in modo che legga questi codici e attenda o suggerisca un upgrade invece di riprovare alla cieca.

Quando supera la quota giornaliera, una chiamata conteggiata restituisce 429 con il codice daily_quota_exceeded, un'intestazione Retry-After e un corpo che riporta il Suo piano, il limite, il numero di chiamate usate, l'orario di azzeramento e un suggerimento di upgrade. Gli endpoint che richiedono un piano superiore restituiscono 403 plan_required con il piano necessario.

• 401: chiave API mancante o non valida.
• 403 plan_required: l'endpoint richiede Pro o un piano superiore.
• 403 insufficient_scope: la chiave non ha l'ambito di scrittura per una chiamata che modifica i dati.
• 429 daily_quota_exceeded o rate_limit_exceeded: attenda l'orario di azzeramento o effettui l'upgrade; rispetti l'intestazione Retry-After.
• Legga le intestazioni di risposta X-Quota-* per anticipare il raggiungimento del limite.

8Buone pratiche per un'integrazione solida

Alcune abitudini mantengono un'integrazione affidabile e sicura man mano che cresce.

• Conservi le chiavi in un gestore di segreti, mai nel codice lato client o in un repository git; usi una chiave diversa per ogni servizio, così può revocarne una senza compromettere le altre.
• Tenga d'occhio le intestazioni X-Quota-Used e X-Quota-Limit (o interroghi GET /usage) e rallenti prima di raggiungere il limite, non dopo.
• In caso di 429, rispetti Retry-After e attenda; in caso di 403 plan_required, mostri un suggerimento di upgrade invece di riprovare.
• Per reagire in tempo reale, preferisca i webhook all'interrogazione periodica: lasci che sia Telm a inviarLe gli eventi.
• Ruoti periodicamente le chiavi, e subito se una potrebbe essere stata compromessa.

9Scenari di integrazione comuni

L'API serve a molto più che moderare i messaggi di Telegram.

• Registrazione su siti web e app: faccia passare il testo inviato o gli username tramite POST /spam/check prima di accettare una registrazione o un commento.
• I Suoi bot Telegram: riutilizzi l'intelligenza di Telm in un bot non gestito da Telm chiamando l'endpoint di controllo dal Suo handler.
• Configurazione in blocco: applichi tramite script le stesse regole, whitelist e impostazioni a decine di gruppi con gli endpoint delle impostazioni e delle regole.
• Dati e avvisi: registri webhook per inviare in tempo reale gli eventi di moderazione a un data warehouse, a una dashboard o a un canale di avvisi.