REST API — automatiseer Telm vanuit je eigen code

1Wat de API je laat doen

De Telm REST API geeft je eigen code hetzelfde bereik als het dashboard: haal willekeurige tekst door de antispampijplijn, 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 analyses op, en registreer webhooks voor realtimegebeurtenissen.

Dat verandert Telm van een bot die in je groepen draait in infrastructuur die je overal kunt inpluggen — 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, versiebeheerd pad (de v1 is de contractversie).
• Elk verzoek en elke respons is JSON over HTTPS.
• Interactieve documentatie en de machineleesbare OpenAPI 3.1-specificatie staan op de developers-pagina — laad de specificatie in Postman, een codegenerator of een AI-agent om binnen enkele minuten een integratie op te zetten.
• Gemeten aanroepen retourneren bij elke respons de headers X-Quota-Limit, X-Quota-Used en X-Quota-Reset.

2Hoe een verzoek door Telm stroomt

De publieke API bevindt zich op zijn eigen padvoorvoegsel, /api/public/, gescheiden van het dashboard. Elke aanroep wordt geauthenticeerd door een API-sleutel in plaats van een browsersessie, gecontroleerd tegen je plan en quotum, uitgevoerd tegen dezelfde live engine die je groepen modereert, en teruggegeven als JSON.

Omdat de API dezelfde engine en gegevens bereikt 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 onmiddellijk 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 aanraken waar je account beheerder is.
• Het spamcontrole-endpoint bereikt de exacte productieregelpijplijn, zodat een API-oordeel overeenkomt met wat de bot in de groep zou doen.

3Authenticatie met API-sleutels

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

Het volledige geheim wordt eenmaal getoond, op het moment van aanmaken. Daarna toont het dashboard een sleutel alleen via zijn korte voorvoegsel, zodat je hem kunt herkennen zonder ooit de volledige waarde op te slaan. Als een sleutel lekt, trek deze in en geef een nieuwe uit — intrekking wordt binnen ongeveer een minuut van kracht.

• Stuur de sleutel als Authorization: Bearer tk_live_je_sleutel_hier (een X-API-Key-header werkt ook).
• Sleutels dragen lees- of schrijfbereik — lezen voor GET-verzoeken, schrijven voor alles wat gegevens wijzigt. Een alleen-lezen-sleutel kan niet aanmaken of bewerken.
• Je kunt tot tien actieve sleutels tegelijk aanhouden, zodat je een aparte sleutel per script of dienst kunt gebruiken.
• Een ontbrekende of ongeldige sleutel retourneert 401; een sleutel zonder het vereiste bereik retourneert 403 insufficient_scope.

4Beschikbare endpoints

De API is georganiseerd rond spam- en gebruikerscontroles, groepsbeheer en accountzelfbediening. Het enkele spamcontrole-endpoint staat open voor elk plan; de rest van het oppervlak maakt deel uit van Pro en Business.

• POST /spam/check — haal één tekst door dezelfde regel-engine die live verkeer modereert (elk plan). Een optionele AI-controle kan worden ingeschakeld op Pro en hoger.
• POST /spam/check-batch — controleer tot 20 teksten in één aanroep, alleen regels (Pro+).
• POST /users/check — zoek een Telegram-gebruiker op: CAS-status, Telm-spambeslissingssignalen en reputatie in je groepen (Pro+).
• GET /groups en GET /groups/{id} — som je groepen op en lees ze (Pro+).
• GET en PATCH /groups/{id}/settings — lees en wijzig de beschermingsinstellingen van een groep (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — beheer aangepaste moderatieregels (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — beheer de groep-whitelist (Pro+).
• GET /groups/{id}/journal en GET /groups/{id}/analytics — lees het moderatiejournaal en de analyses (Pro+).
• GET/POST/PATCH/DELETE /webhooks — beheer realtime-gebeurtenis-webhooks (Pro+).
• GET /usage en GET /me — controleer je quotum- en sleutelinformatie; deze verbruiken nooit quotum (elk plan).

5Het spamcontrole-endpoint in detail

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

Eén tekst kan tot 10.000 tekens zijn. Op Pro en hoger kun je kiezen voor een AI-controle voor moeilijkere gevallen, getrokken uit een aparte dagelijkse AI-controle-toewijzing. Voor grote volumes controleert het batch-endpoint tot 20 teksten in één aanroep en telt quotum per item.

• Gebruik het oordeel en de score om te beslissen wat je eigen product doet — een formulierinzending blokkeren, een lead markeren, of een bericht automatisch verwijderen in je eigen bot.
• Het batch-endpoint is alleen regels; de AI-ladder is alleen beschikbaar op het enkele-tekst-endpoint.
• Verzoek-bodies zijn begrensd (ruwweg 64 KB voor een enkele controle, 256 KB voor een batch); te grote bodies retourneren 413.

6Plannen, snelheidslimieten en dagelijkse quota

Toegang wordt op twee manieren gemeten: een snelheidslimiet per minuut (een burst-plafond) en een dagelijks aanroepquotum dat om middernacht UTC wordt gereset. Beide schalen met je plan en worden per account geteld, gedeeld over al je sleutels. Je kunt het enkele spamcontrole-endpoint op elk plan uitproberen, maar een echte integratie die regels, instellingen, batchcontroles en webhooks aanraakt vereist Pro of hoger.

• Free — 100 aanroepen/dag, alleen spamcontrole.
• Basic — 1.000 aanroepen/dag, alleen spamcontrole.
• Pro — 10.000 aanroepen/dag, volledige API en webhooks, plus een dagelijkse AI-controle-toewijzing.
• Business — 50.000 aanroepen/dag, volledige API en webhooks, grotere AI-toewijzing.
• Snelheidslimieten per minuut schalen ook — hogere plannen krijgen een veel groter burst-plafond.

7Foutafhandeling en statuscodes

De API gebruikt standaard HTTP-statuscodes met een machineleesbare foutcode in de body. Bouw je client om deze codes te lezen en terug te schalen of een upgrade voor te stellen in plaats van blindelings opnieuw te proberen.

Wanneer je je dagelijkse quotum overschrijdt, retourneert een gemeten aanroep 429 met een daily_quota_exceeded-code, een Retry-After-header, en een body die je plan, limiet, gebruikt aantal, resettijd en een upgrade-hint opsomt. Endpoints die een hoger plan nodig hebben retourneren 403 plan_required met het vereiste plan.

• 401 — ontbrekende of ongeldige API-sleutel.
• 403 plan_required — het endpoint heeft Pro of hoger nodig.
• 403 insufficient_scope — de sleutel mist schrijfbereik voor een wijzigende aanroep.
• 429 daily_quota_exceeded of rate_limit_exceeded — wacht op de resettijd of upgrade; respecteer de Retry-After-header.
• Lees de X-Quota-*-responsheaders om de limiet voor te blijven.

8Best practices voor een solide integratie

Een paar gewoonten houden een integratie betrouwbaar en veilig terwijl deze groeit.

• Bewaar sleutels in een secrets manager, nooit in client-side code of een git-repository; gebruik een aparte sleutel per dienst zodat je er één kunt intrekken zonder de andere te breken.
• Houd de X-Quota-Used- en X-Quota-Limit-headers in de gaten (of poll GET /usage) en rem af voordat je tegen de muur loopt, niet erna.
• Bij 429, respecteer Retry-After en schaal terug; bij 403 plan_required, toon een upgrade-prompt in plaats van opnieuw te proberen.
• Voor realtimereacties, geef de voorkeur aan webhooks boven polling — laat Telm gebeurtenissen naar je pushen.
• Roteer sleutels periodiek, en onmiddellijk als er één kan zijn gelekt.

9Veelvoorkomende integratiescenario's

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

• Aanmelding op website en app: haal ingezonden tekst of gebruikersnamen door POST /spam/check voordat je een registratie of een reactie accepteert.
• Je eigen Telegram-bots: hergebruik Telm-intelligentie in een bot die Telm niet beheert door het controle-endpoint aan te roepen vanuit je handler.
• Bulkconfiguratie: scripteer dezelfde regels, whitelists en instellingen over tientallen groepen met de instellingen- en regel-endpoints.
• Data en waarschuwingen: registreer webhooks om moderatiegebeurtenissen realtime naar een datawarehouse, een dashboard of een waarschuwingskanaal te streamen.