REST API — automatiseer Telm vanuit je eigen code

1Wat je met de API kunt doen

De Telm REST API geeft je eigen code hetzelfde bereik als het dashboard: haal elke tekst door de antispam-pipeline, zoek een Telegram-gebruiker op voordat je hem binnenlaat, lees en wijzig de beschermingsinstellingen van een groep, beheer aangepaste regels en whitelists, haal het moderatiejournaal en de analytics op en registreer webhooks voor realtime gebeurtenissen.

Zo verandert Telm van een bot die in je groepen woont in infrastructuur die je overal kunt aansluiten — een aanmeldformulier op een website, een CRM-bot, je eigen Telegram-bots of een script dat honderd groepen tegelijk configureert.

• Basis-URL: api.telm.com/api/public/v1 — een stabiel pad met versienummer (de v1 is de contractversie).
• Elk verzoek en elk antwoord is JSON via HTTPS.
• Interactieve documentatie en de machineleesbare OpenAPI 3.1-specificatie staan op de ontwikkelaarspagina — laad de specificatie in Postman, een codegenerator of een AI-agent om in een paar minuten de basis van een integratie op te zetten.
• Bemeterde aanroepen geven bij elk antwoord de headers X-Quota-Limit, X-Quota-Used en X-Quota-Reset terug.

2Hoe een verzoek door Telm loopt

De openbare API heeft een eigen padprefix, /api/public/, los van het dashboard. Elke aanroep wordt geauthenticeerd met een API-sleutel in plaats van een browsersessie, getoetst aan je plan en quotum, uitgevoerd op dezelfde live engine die je groepen modereert en als JSON teruggegeven.

Omdat de API dezelfde engine en gegevens gebruikt als de bot, kun je alles wat je in het dashboard kunt zien of wijzigen ook in code doen — en elke wijziging die je in code maakt, verschijnt meteen in het dashboard.

• Verzoeken zijn stateless: elk verzoek draagt zijn eigen sleutel en staat op zichzelf.
• Een sleutel handelt namens je account en kan alleen groepen raken waar je account beheerder is.
• Het spam-check-endpoint gebruikt precies dezelfde regelpipeline als in productie, dus een API-oordeel komt overeen met wat de bot in de groep zou doen.

3Authenticatie met API-sleutels

Elk verzoek wordt geauthenticeerd met een API-sleutel in de vorm tk_live_ gevolgd door willekeurige tekens — niet met je dashboardlogin. Je maakt sleutels aan in je account en stuurt de sleutel mee in de Authorization-header als Bearer-token, of in een header X-API-Key.

Het volledige geheim wordt één keer getoond, bij het aanmaken. Daarna toont het dashboard een sleutel alleen nog met zijn korte prefix, zodat je hem herkent zonder ooit de volledige waarde op te slaan. Lekt een sleutel, trek hem dan in en maak een nieuwe aan — intrekken werkt direct.

• Stuur de sleutel mee als Authorization: Bearer tk_live_your_key_here (een header X-API-Key werkt ook).
• Sleutels hebben lees- of schrijfrechten — lezen voor GET-verzoeken, schrijven voor alles wat gegevens wijzigt. Een sleutel met alleen leesrechten kan niets aanmaken of bewerken.
• Je kunt tot tien actieve sleutels tegelijk hebben, zodat je per script of service een aparte sleutel kunt gebruiken.
• Een ontbrekende of ongeldige sleutel geeft 401; een sleutel zonder de vereiste rechten geeft 403 insufficient_scope.

4Beschikbare endpoints

De API is opgebouwd rond spam- en gebruikerscontroles, groepsbeheer en selfservice voor je account. Het losse spam-check-endpoint staat open voor elk plan; de rest van de API hoort bij Pro en Business.

• POST /spam/check — haal één tekst door dezelfde regelengine die het live verkeer modereert (elk plan). Op Pro en hoger kun je een optionele AI-controle inschakelen.
• POST /spam/check-batch — controleer tot 20 teksten in één aanroep, alleen met regels (Pro+).
• POST /users/check — zoek een Telegram-gebruiker op: CAS-status, signalen uit spambeslissingen van Telm en reputatie in je groepen (Pro+).
• GET /groups en GET /groups/{id} — je groepen opvragen en bekijken (Pro+).
• GET en PATCH /groups/{id}/settings — de beschermingsinstellingen van een groep lezen en wijzigen (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — aangepaste moderatieregels beheren (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — de whitelist van de groep beheren (Pro+).
• GET /groups/{id}/journal en GET /groups/{id}/analytics — het moderatiejournaal en de analytics lezen (Pro+).
• GET/POST/PATCH/DELETE /webhooks — webhooks voor realtime gebeurtenissen beheren (Pro+).
• GET /usage en GET /me — je quotum en sleutelgegevens bekijken; deze verbruiken nooit quotum (elk plan).

5Het spam-check-endpoint in detail

POST /spam/check is het hart van de API en het enige endpoint dat je op elk plan kunt uitproberen. Stuur een JSON-body met de tekst die je wilt controleren; het antwoord bevat een oordeel, een numerieke score, een zekerheidswaarde en een aanbevolen actie die je in je eigen product kunt toepassen.

Eén tekst mag tot 10.000 tekens lang zijn. Op Pro en hoger kun je voor lastigere gevallen een AI-controle aanzetten, die uit een apart dagelijks tegoed aan AI-controles komt. Voor grote volumes controleert het batch-endpoint tot 20 teksten in één aanroep en telt het quotum per item.

• Gebruik het oordeel en de score om te bepalen wat je eigen product doet — een formulierinzending blokkeren, een lead markeren of een bericht automatisch verwijderen in je eigen bot.
• Het batch-endpoint werkt alleen met regels; de AI-ladder is alleen beschikbaar op het endpoint voor losse teksten.
• Verzoekbodies zijn begrensd (ongeveer 64 KB voor een losse controle, 256 KB voor een batch); te grote bodies geven 413.

6Plannen, ratelimieten en dagelijkse quota

Toegang wordt op twee manieren bemeterd: een ratelimiet per minuut (een plafond voor pieken) en een dagelijks quotum aan aanroepen dat om middernacht UTC wordt gereset. Beide worden per account geteld en gedeeld over al je API-sleutels. Je kunt het losse spam-check-endpoint op elk plan uitproberen, maar een echte integratie die regels, instellingen, batchcontroles en webhooks gebruikt, heeft Pro of hoger nodig.

• Free — 100 aanroepen/dag, alleen spamcontrole.
• Pro — 10.000 aanroepen/dag, volledige API en webhooks, plus 1.000 AI-controles per dag.
• Business — 50.000 aanroepen/dag, volledige API en webhooks, plus 10.000 AI-controles per dag.
• Ook de ratelimieten per minuut groeien mee — 60 verzoeken per minuut op Free, 600 op Pro en 1.800 op Business.
• GET /usage en GET /me tellen nooit mee voor je quotum, dus je kunt op elk moment je resterende budget bekijken.

7Foutafhandeling en statuscodes

De API gebruikt standaard HTTP-statuscodes met een machineleesbare foutcode in de body. Bouw je client zo dat hij deze codes leest en terugschakelt of om een upgrade vraagt, in plaats van blind opnieuw te proberen.

Als je je dagelijkse quotum overschrijdt, geeft een bemeterde aanroep 429 terug met de code daily_quota_exceeded, een Retry-After-header en een body met je plan, limiet, verbruikte aantal, resettijd en een upgrade-hint. Endpoints die een hoger plan vereisen, geven 403 plan_required terug met het vereiste plan.

• 401 — ontbrekende of ongeldige API-sleutel.
• 403 plan_required — het endpoint vereist Pro of hoger.
• 403 insufficient_scope — de sleutel heeft geen schrijfrechten voor een wijzigende aanroep.
• 429 daily_quota_exceeded of rate_limit_exceeded — wacht tot de resettijd of upgrade; respecteer de Retry-After-header.
• Lees de X-Quota-*-headers in het antwoord om de limiet voor te blijven.

8Best practices voor een solide integratie

Een paar gewoontes houden een integratie betrouwbaar en veilig naarmate die groeit.

• Bewaar sleutels in een secrets-manager, nooit in frontendcode of een git-repository; gebruik per service een aparte sleutel, zodat je er één kunt intrekken zonder de andere te breken.
• Houd de headers X-Quota-Used en X-Quota-Limit in de gaten (of vraag periodiek GET /usage op) en rem af voordat je tegen de limiet aanloopt, niet erna.
• Respecteer bij 429 de Retry-After-header en schakel terug; toon bij 403 plan_required een upgradeprompt in plaats van opnieuw te proberen.
• Kies voor realtime reacties webhooks in plaats van polling — laat Telm de gebeurtenissen naar jou pushen.
• Roteer sleutels regelmatig, en meteen als er een gelekt kan zijn.

9Veelvoorkomende integratiescenario's

De API wordt voor veel meer gebruikt dan het modereren van Telegram-berichten.

• Aanmelden op websites en in apps: haal ingevoerde tekst of gebruikersnamen door POST /spam/check voordat je een registratie of reactie accepteert.
• Je eigen Telegram-bots: hergebruik de intelligentie van Telm in een bot die Telm niet beheert, door het controle-endpoint vanuit je handler aan te roepen.
• Bulkconfiguratie: zet met de endpoints voor instellingen en regels via een script dezelfde regels, whitelists en instellingen klaar voor tientallen groepen.
• Data en alerts: registreer webhooks om moderatiegebeurtenissen in realtime naar een datawarehouse, een dashboard of een alertkanaal te streamen.