Collega la moderazione di Telegram al tuo stack: API e webhook

1Una moderazione che dialoga con il resto del tuo stack

Un bot di moderazione che vive interamente dentro Telegram è utile, ma è anche un'isola. Le decisioni che prende — ogni messaggio che rimuove, ogni utente che analizza, ogni raid che respinge — restano chiuse in una finestra di chat a meno che qualcuno non apra Telegram per guardarle. Per una singola community va bene. Per un team che gestisce la moderazione come parte di un'operazione più grande, significa che l'unico sistema che sa di più su chi abusa dei tuoi spazi è l'unico sistema che non può dialogare con nient'altro di quello che fai girare.

L'API REST pubblica e i webhook colmano questa lacuna. Trasformano Telm da bot autonomo in un componente che puoi collegare agli strumenti che hai già: il tuo sistema di monitoraggio e reperibilità, il tuo archivio di conformità, il tuo prodotto, le tue dashboard interne. Lo stesso motore che protegge i tuoi gruppi diventa qualcosa che i tuoi altri sistemi possono interrogare, ascoltare e pilotare.

Questa guida illustra ciò che l'API e i webhook espongono davvero — gli endpoint, gli eventi, il modello di sicurezza — e le cose concrete che i team costruiscono con essi. Tutto ciò che segue è una funzionalità reale disponibile oggi; non c'è alcun SDK da attendere e nulla di descritto qui che il prodotto solo si proponga di fare.

2L'API REST e le tue chiavi

L'API si trova su `https://api.telm.com/api/public/v1`. È una semplice interfaccia REST — la chiami con normali richieste HTTPS e JSON, da qualsiasi linguaggio, senza bisogno di una libreria client speciale. Se il tuo codice può fare una richiesta HTTP, può dialogare con Telm.

L'autenticazione avviene tramite chiave API. Crei le chiavi nella dashboard, in Impostazioni → API e Webhook, e ognuna ti viene mostrata esattamente una volta alla creazione — copiala nel tuo gestore di segreti in quel momento, perché non potrà essere recuperata in seguito. Le chiavi hanno il prefisso `tk_live_` così sono facili da riconoscere nei log e nella configurazione. Ogni chiave porta un ambito — lettura o scrittura — così un servizio che deve solo estrarre il registro delle decisioni può avere una chiave di sola lettura, mentre un'automazione che modifica le impostazioni riceve una chiave di scrittura. Genera una chiave per sistema, e revocare una chiave trapelata o dismessa non disturba mai le altre.

L'utilizzo è regolato da una quota giornaliera di richieste legata al tuo piano, così il throughput è prevedibile e uno script impazzito non può esaurire tutto. Il controllo più leggero — la scansione dei testi per lo spam — è disponibile su ogni piano entro quella quota; la superficie più completa, dal registro delle decisioni alla gestione delle impostazioni fino ai webhook, fa parte dei piani Pro e Business. I numeri esatti sono riportati alla fine.

3Analizzare testi e utenti su richiesta

Due endpoint ti permettono di applicare il giudizio di Telm su richiesta, dal tuo codice, senza che un messaggio passi mai attraverso un gruppo Telegram.

`POST /spam/check` invia un frammento di testo attraverso l'esatto motore di produzione che protegge le tue community — i segnali condivisi sugli spammer, le regole a pattern, i classificatori — e restituisce un verdetto. È l'unica chiamata disponibile su ogni piano, il che ne fa un filtro anti-spam naturale per il tuo prodotto: analizza commenti, bio di iscrizione, ticket di supporto o annunci di marketplace con lo stesso rilevamento che protegge i tuoi spazi Telegram. Aggiungi `include_ai` per includere un verdetto IA nei casi più difficili e ambigui (disponibile su Pro e Business), e su quei piani puoi raggruppare fino a venti testi in una singola richiesta invece di chiamare una volta per elemento.

`POST /users/check` analizza una persona anziché un messaggio. Combina la blocklist globale CAS, il dataset proprietario di Telm costruito dalla moderazione in molte community, e restituisce un livello di rischio (su Pro e Business) così puoi decidere quanto attrito applicare — lascia passare direttamente un account pulito, trattieni per revisione uno rischioso. Collegarlo al tuo onboarding ti permette di intercettare un malintenzionato noto alla porta del tuo sito o della tua app, non solo dopo che si è unito a un gruppo Telegram.

Entrambe le chiamate rispondono in linea: invii il testo o l'utente, e ricevi la valutazione nella risposta. Non c'è alcuna coda da interrogare né alcun callback da attendere — la decisione arriva con la risposta.

4Ricevere una spinta nel momento in cui accade

Interrogare il registro va bene per l'archiviazione, ma quando vuoi *reagire* a qualcosa nell'istante in cui accade, vuoi ricevere una spinta, non chiedere. I webhook (su Pro e Business) fanno esattamente questo: registri un endpoint e Telm gli invia una richiesta HTTP nel momento in cui scatta un evento rilevante. Gli eventi coprono i momenti che contano — `spam.detected` e `message.suspicious` per i contenuti, e `user.banned`, `user.kicked`, `user.muted`, `user.joined` e `user.left` per l'appartenenza.

L'uso ovvio è trasformare un'ondata di spam in un alert. Punta `spam.detected` verso il tuo sistema di monitoraggio o reperibilità e un'improvvisa impennata diventa una segnalazione a chi è di turno, nello stesso posto in cui atterrano gli altri tuoi incidenti — nessuno deve stare a guardare Telegram per accorgersi che un attacco sta iniziando. Lo stesso flusso alimenta dashboard in tempo reale, mantiene un sistema esterno sincronizzato con i ban o attiva qualsiasi workflow tu voglia.

Poiché queste richieste arrivano dal mondo esterno alla tua infrastruttura, ogni consegna è firmata. Ogni richiesta porta un'intestazione `X-Telm-Signature` della forma `v1=hex(hmac_sha256(secret, "timestamp.body"))` — un HMAC-SHA256 sul timestamp e sul corpo grezzo, con chiave un segreto che solo tu e Telm condividete. Ricalcolare quella firma dal tuo lato dimostra che la richiesta proviene davvero da Telm e non è stata falsificata o manomessa in transito; il timestamp ti permette di rifiutare i replay obsoleti. Verifica la firma prima di fidarti del payload — sono poche righe di codice e il singolo passo più importante in un ricevente di webhook sicuro.

5Una consegna su cui puoi contare

Un modello push è affidabile solo se regge i momenti in cui il tuo endpoint è lento, in fase di riavvio o brevemente offline — e quello di Telm lo fa. La consegna è almeno una volta: ogni evento porta un `id` stabile, e Telm continua a provare finché il tuo endpoint non lo conferma. Poiché almeno una volta significa che lo stesso evento può legittimamente arrivare due volte, deduplica su quell'`id` — registra quelli che hai già elaborato e ignora le ripetizioni — e la tua gestione resta corretta a prescindere da quante volte una consegna viene ritentata.

I nuovi tentativi seguono una scala che si allarga anziché martellare un endpoint in difficoltà: subito, poi dopo un minuto, cinque minuti, trenta minuti, due ore e sei ore — sei tentativi in tutto, distribuiti per dare a un servizio in ripresa il tempo di tornare in vita. Se un endpoint resta rotto — venti fallimenti consecutivi e settantadue ore senza una consegna riuscita — Telm smette di inviargli richieste automaticamente e ti avvisa su Telegram, così un URL morto diventa un chiaro avviso a sistemare il tuo ricevente invece di un silenzioso fiume di fallimenti che si accumulano.

Per mettere a punto una nuova integrazione, non devi provocare eventi reali per testarla. Un ping di prova ti permette di lanciare una consegna di esempio verso il tuo endpoint su richiesta e di confermare che il tuo controllo della firma e il tuo handler funzionino, e uno storico delle consegne mostra cosa è stato inviato e come è andato ogni tentativo — così puoi eseguire il debug di un ricevente che si comporta male dal registro invece che a indovinare.

6Un registro interrogabile di ogni decisione

Tutto ciò che il motore decide viene registrato, e `GET journal` consegna quel registro al tuo codice. Ogni voce è una decisione: il verdetto, il punteggio che vi sta dietro, quali regole si sono attivate e l'azione che ne è seguita. Poiché è paginato a cursore, puoi percorrere l'intero storico in modo affidabile — pagina dopo pagina, senza vuoti né duplicati — ed estrarlo ovunque tu conservi i tuoi archivi.

Questo fa del registro la spina dorsale di un archivio di conformità. I team che devono dimostrare perché un membro è stato rimosso — per una policy di piattaforma, un contratto con un cliente o un regolatore — esportano il registro nel proprio archivio a lungo termine secondo una pianificazione, ottenendo un resoconto indipendente e interrogabile di ogni azione di enforcement che non dipende dallo scorrere all'indietro Telegram. Sono le stesse prove che il registro di audit della dashboard presenta agli esseri umani, rese disponibili ai tuoi sistemi.

Accanto ad esso, un endpoint di analisi restituisce serie giorno per giorno — volumi e tendenze nel tempo — così puoi rappresentare il carico di moderazione nei tuoi strumenti di business intelligence accanto a tutto il resto che monitori, invece di leggerlo da uno schermo. Sia il registro sia le analisi fanno parte dei piani Pro e Business.

7Gestire molti gruppi da codice

L'API non solo legge e ascolta — scrive. Su Pro e Business puoi effettuare un `PATCH` sulle impostazioni di un gruppo ed eseguire l'intero create/read/update/delete sulle sue regole e sulla sua whitelist, tutto in modo programmatico. Qualsiasi cosa configureresti a mano nella dashboard, puoi configurarla da uno script.

È questo che rende pratico gestire la moderazione su larga scala. Un'agenzia o un grande operatore che gestisce decine di community non vuole aprire ognuna e cliccare attraverso le stesse modifiche; vuole definire la policy una volta e applicarla ovunque. Con l'API puoi distribuire una nuova regola, regolare una soglia o aggiungere un indirizzo a ogni whitelist su tutta la flotta in un unico passaggio automatizzato, e mantenere i gruppi allineati man mano che i tuoi standard evolvono.

Ti permette anche di far vivere la policy di moderazione nel tuo controllo di versione. Mantieni la configurazione desiderata come codice, applicala tramite l'API, e ogni modifica al modo in cui i tuoi gruppi sono governati viene revisionata e versionata come il resto della tua infrastruttura — ben lontano dal ricordare quali impostazioni hai attivato in quale chat.

8Cosa include ogni piano

La linea di demarcazione è semplice. Il controllo dei testi per lo spam è disponibile su ogni piano, così anche il livello gratuito può usare il rilevamento di Telm come filtro nel proprio prodotto. La superficie completa — screening degli utenti con livelli di rischio, il registro delle decisioni e le analisi, la gestione di impostazioni e regole, e i webhook — fa parte dei piani Pro e Business.

Ogni piano riceve una quota giornaliera di richieste, dimensionata in modo che le integrazioni più pesanti stiano sui piani più pesanti:

• **Free** — 100 richieste API al giorno, solo controllo spam.
• **Basic** — 1.000 richieste API al giorno, solo controllo spam.
• **Pro** — 10.000 richieste API al giorno, più la superficie API completa e i webhook.
• **Business** — 50.000 richieste API al giorno, più la superficie API completa e i webhook.
• Crea le tue chiavi in Impostazioni → API e Webhook, tienile nel tuo gestore di segreti, verifica la firma di ogni webhook, e lo stesso motore che protegge i tuoi gruppi diventa parte del tuo stack.