Telegram-moderatie koppelen aan je eigen stack: API en webhooks

1Wat elk plan bevat

De scheidslijn is simpel. Tekst op spam controleren is beschikbaar in elk plan, zodat zelfs het gratis niveau Telms detectie als filter in het eigen product kan gebruiken. Het volledige oppervlak — gebruikerscontrole met risiconiveaus, het beslissingsjournaal en de analytics, instellingen- en regelbeheer, en webhooks — hoort bij de plannen Pro en Business.

Elk plan krijgt een dagelijkse verzoekquota, zo bemeten dat zwaardere integraties op zwaardere plannen zitten:

• **Free** — 100 API-verzoeken per dag, alleen spamcontrole.
• **Basic** — 1.000 API-verzoeken per dag, alleen spamcontrole.
• **Pro** — 10.000 API-verzoeken per dag, plus het volledige API-oppervlak en webhooks.
• **Business** — 50.000 API-verzoeken per dag, plus het volledige API-oppervlak en webhooks.
• Maak je sleutels aan onder Instellingen → API & Webhooks, bewaar ze in je secrets-opslag, verifieer de handtekening van elke webhook, en dezelfde engine die je groepen bewaakt wordt een deel van je eigen stack.

2Een bevraagbaar register van elke beslissing

Alles wat de engine beslist wordt vastgelegd, en `GET journal` overhandigt dat register aan je code. Elke vermelding is één beslissing: het oordeel, de score erachter, welke regels afgingen en de actie die volgde. Omdat het cursor-gepagineerd is, kun je de hele historie betrouwbaar doorlopen — pagina na pagina, zonder gaten of duplicaten — en die trekken naar waar je je administratie bijhoudt.

Dat maakt het journaal de ruggengraat van een compliance-archief. Teams die moeten aantonen waarom een lid is verwijderd — voor een platformbeleid, een klantcontract of een toezichthouder — exporteren het log volgens een schema naar hun eigen langetermijnopslag, en krijgen zo een onafhankelijk, bevraagbaar overzicht van elke handhavingsactie dat niet afhangt van terugscrollen door Telegram. Het is hetzelfde bewijs dat de auditlog van het dashboard aan mensen toont, nu beschikbaar voor je systemen.

Daarnaast geeft een analytics-endpoint dag-voor-dag-reeksen terug — volumes en trends door de tijd — zodat je de moderatiebelasting in je eigen business-intelligencetools kunt uitzetten naast alles wat je verder bijhoudt, in plaats van het van een scherm af te lezen. Zowel het journaal als de analytics horen bij de plannen Pro en Business.

3Bezorging waarop je kunt rekenen

Een pushmodel is alleen betrouwbaar als het overweg kan met de momenten dat je endpoint traag is, herstart of even down is — en dat van Telm doet dat. Bezorging is minstens één keer: elk event draagt een stabiele `id`, en Telm blijft proberen tot je endpoint het bevestigt. Omdat minstens één keer betekent dat hetzelfde event terecht twee keer kan aankomen, dedupliceer op die `id` — leg vast welke je verwerkt hebt en negeer herhalingen — en je verwerking blijft correct, hoe vaak een bezorging ook opnieuw wordt geprobeerd.

Nieuwe pogingen volgen een verbreedend schema in plaats van een worstelend endpoint te bestoken: meteen, dan na één minuut, vijf minuten, dertig minuten, twee uur en zes uur — zes pogingen in totaal, uitgesmeerd om een herstellende service ruimte te geven om terug te komen. Blijft een endpoint kapot — twintig opeenvolgende mislukkingen en tweeënzeventig uur zonder geslaagde bezorging — dan stopt Telm er automatisch mee en waarschuwt het je in Telegram, zodat een dode URL een duidelijk seintje wordt om je ontvanger te repareren in plaats van een stille stortvloed van mislukkingen die zich opstapelt.

Om een nieuwe integratie goed te krijgen hoef je geen echte events uit te lokken om te testen. Met een test-ping vuur je op aanvraag een voorbeeldbezorging af op je endpoint en bevestig je dat je handtekeningcontrole en handler werken, en een afleverhistorie toont wat er is verstuurd en hoe elke poging verliep — zodat je een zich misdragende ontvanger vanuit het register kunt debuggen in plaats van te gissen.

4Moderatie die praat met de rest van je stack

Een moderatiebot die volledig binnen Telegram leeft is nuttig, maar ook een eiland. De beslissingen die hij neemt — elk bericht dat hij verwijdert, elke gebruiker die hij screent, elke raid die hij afslaat — blijven opgesloten in een chatvenster, tenzij iemand Telegram opent om te kijken. Voor één community is dat prima. Voor een team dat moderatie draait als onderdeel van een grotere operatie betekent het dat het ene systeem dat het meeste weet over wie je ruimtes misbruikt, precies het systeem is dat met niets anders kan praten dat je draait.

De publieke REST API en webhooks dichten dat gat. Ze maken van Telm in plaats van een op zichzelf staande bot een component die je kunt koppelen aan de tools die je al hebt: je monitoring en on-call-opstelling, je compliance-archief, je eigen product, je interne dashboards. Dezelfde engine die je groepen beschermt wordt iets dat je andere systemen kunnen bevragen, beluisteren en aansturen.

Deze gids loopt door wat de API en webhooks werkelijk blootleggen — de endpoints, de events, het beveiligingsmodel — en de concrete dingen die teams ermee bouwen. Alles hieronder is een echte mogelijkheid die vandaag beschikbaar is; er is geen SDK om op te wachten en niets hier beschreven dat het product alleen nog van plan is.

5Tekst en gebruikers op aanvraag screenen

Met twee endpoints laat je Telms oordeel op aanvraag draaien, vanuit je eigen code, zonder dat er ooit een bericht door een Telegram-groep gaat.

`POST /spam/check` stuurt een stuk tekst door exact dezelfde productie-engine die je community's bewaakt — de gedeelde spammersignalen, de patroonregels, de classifiers — en geeft een oordeel terug. Dit is de ene aanroep die in elk plan beschikbaar is, wat hem een natuurlijke spamfilter maakt voor je eigen product: screen reacties, aanmeldbio's, supporttickets of marktplaatsadvertenties met dezelfde detectie die je Telegram-ruimtes beschermt. Voeg `include_ai` toe om voor de lastigere, dubbelzinnigere gevallen een AI-oordeel mee te nemen (beschikbaar in Pro en Business); in die plannen kun je tot twintig teksten in één verzoek bundelen in plaats van per item aan te roepen.

`POST /users/check` screent een persoon in plaats van een bericht. De aanroep combineert de wereldwijde CAS-blokkeerlijst en Telms eigen dataset opgebouwd uit moderatie over veel community's, en geeft een risiconiveau terug (in Pro en Business), zodat je kunt beslissen hoeveel wrijving je toepast — een schoon account meteen doorwuiven, een riskant account vasthouden voor beoordeling. Koppel je hem aan je eigen onboarding, dan vang je een bekende kwaadwillende al bij de deur van je website of app, niet pas nadat hij zich bij een Telegram-groep heeft gevoegd.

Beide aanroepen antwoorden inline: je stuurt de tekst of de gebruiker, je krijgt de beoordeling terug in de respons. Er is geen wachtrij om te pollen en geen callback om op te wachten — de beslissing komt met het antwoord.

6Gepusht worden op het moment dat het gebeurt

Het journaal pollen is prima voor archivering, maar wanneer je op iets wilt *reageren* zodra het gebeurt, wil je gepusht worden, niet vragen. Webhooks (in Pro en Business) doen precies dat: je registreert een endpoint, en Telm stuurt er een HTTP-verzoek naartoe op het moment dat een relevant event afgaat. De events dekken de momenten die ertoe doen — `spam.detected` en `message.suspicious` voor content, en `user.banned`, `user.kicked`, `user.muted`, `user.joined` en `user.left` voor lidmaatschap.

Het voor de hand liggende gebruik is een spamgolf omzetten in een alert. Richt `spam.detected` op je monitoring- of on-call-systeem en een plotselinge piek wordt een melding naar wie er dienst heeft, op dezelfde plek waar je andere incidenten binnenkomen — niemand hoeft Telegram in de gaten te houden om te merken dat er een aanval begint. Dezelfde stroom voedt real-time dashboards, houdt een extern systeem synchroon met bans, of triggert elke workflow die je maar wilt.

Omdat deze verzoeken van de buitenwereld je infrastructuur binnenkomen, is elke bezorging ondertekend. Elk verzoek draagt een `X-Telm-Signature`-header van de vorm `v1=hex(hmac_sha256(secret, "timestamp.body"))` — een HMAC-SHA256 over de timestamp en de ruwe body, met een secret dat alleen jij en Telm delen. Die handtekening aan jouw kant herberekenen bewijst dat het verzoek echt van Telm kwam en onderweg niet is vervalst of gemanipuleerd; de timestamp laat je verouderde replays weigeren. Verifieer de handtekening voordat je de payload vertrouwt — het zijn een paar regels code en de allerbelangrijkste stap in een veilige webhook-ontvanger.

7De REST API en je sleutels

De API bevindt zich op `https://api.telm.com/api/public/v1`. Het is een gewone REST-interface — je roept die aan met doodgewone HTTPS-verzoeken en JSON, vanuit elke taal, zonder speciale clientbibliotheek. Als je code een HTTP-verzoek kan doen, kan hij met Telm praten.

Authenticatie gaat met een API-sleutel. Je maakt sleutels aan in het dashboard onder Instellingen → API & Webhooks, en elke sleutel wordt je bij het aanmaken precies één keer getoond — kopieer hem daar meteen naar je secrets-opslag, want daarna kun je hem niet meer opvragen. Sleutels hebben de prefix `tk_live_`, zodat ze makkelijk te herkennen zijn in logs en config. Elke sleutel draagt een scope — lezen of schrijven — zodat een service die alleen het beslissingslog hoeft op te halen een alleen-lezen sleutel kan aanhouden, terwijl automatisering die instellingen wijzigt een schrijfsleutel krijgt. Maak één sleutel per systeem, en het intrekken van een gelekte of afgedankte sleutel verstoort de andere nooit.

Gebruik wordt geregeld door een dagelijkse verzoekquota die aan je plan is gekoppeld, zodat de doorvoer voorspelbaar is en één op hol geslagen script niet alles kan opgebruiken. De lichtste controle — tekst scannen op spam — is beschikbaar in elk plan binnen die quota; het volledigere oppervlak, van het beslissingsjournaal tot instellingenbeheer tot webhooks, hoort bij de plannen Pro en Business. De exacte getallen staan aan het eind.

8Veel groepen vanuit code beheren

De API leest en luistert niet alleen — hij schrijft. In Pro en Business kun je de instellingen van een groep `PATCH`en en volledige create/read/update/delete draaien op de regels en de whitelist, allemaal programmatisch. Alles wat je met de hand in het dashboard zou instellen, kun je vanuit een script instellen.

Dat is wat moderatie op schaal praktisch maakt. Een bureau of een grote beheerder met tientallen community's wil niet elke community openen en dezelfde wijzigingen doorklikken; ze willen het beleid één keer definiëren en overal toepassen. Met de API rol je een nieuwe regel uit, pas je een drempel aan of voeg je in één geautomatiseerde ronde aan elke whitelist over de hele vloot een adres toe, en houd je de groepen in de pas terwijl je normen evolueren.

Het laat je moderatiebeleid ook in je eigen versiebeheer leven. Bewaar de gewenste configuratie als code, pas die toe via de API, en elke wijziging in hoe je groepen worden bestuurd wordt beoordeeld en geversioneerd zoals de rest van je infrastructuur — mijlenver van onthouden welke instellingen je in welke chat hebt omgezet.