REST API – automatisera Telm från din egen kod

1Vad API:t låter dig göra

Telms REST API ger din egen kod samma räckvidd som dashboarden: kör valfri text genom antispam-pipelinen, slå upp en Telegram-användare innan du släpper in dem, läs och ändra en grupps skyddsinställningar, hantera anpassade regler och vitlistor, hämta modereringsjournalen och analysen, och registrera webhooks för realtidshändelser.

Det förvandlar Telm från en bot som lever inuti dina grupper till infrastruktur du kan koppla in var som helst – ett registreringsformulär på en webbplats, en CRM-bot, dina egna Telegram-botar, eller ett skript som konfigurerar hundra grupper på en gång.

• Bas-URL: api.telm.com/api/public/v1 – en stabil, versionshanterad sökväg (v1 är kontraktsversionen).
• Varje förfrågan och svar är JSON över HTTPS.
• Interaktiv dokumentation och den maskinläsbara OpenAPI 3.1-specifikationen finns på developers-sidan – ladda in specifikationen i Postman, en kodgenerator eller en AI-agent för att skapa en integration på minuter.
• Mätta anrop returnerar rubrikerna X-Quota-Limit, X-Quota-Used och X-Quota-Reset på varje svar.

2Hur en förfrågan flödar genom Telm

Det publika API:t ligger på sitt eget sökvägsprefix, /api/public/, skilt från dashboarden. Varje anrop autentiseras med en API-nyckel snarare än en webbläsarsession, kontrolleras mot din plan och kvot, körs mot samma live-motor som modererar dina grupper, och returneras som JSON.

Eftersom API:t når samma motor och data som boten kan allt du kan se eller ändra i dashboarden också göras i kod – och varje ändring du gör i kod dyker upp i dashboarden omedelbart.

• Förfrågningar är tillståndslösa: varje bär sin egen nyckel och står på egna ben.
• En nyckel agerar på uppdrag av ditt konto och kan bara röra grupper där ditt konto är administratör.
• Spam-kontroll-endpointen når den exakta produktionsregelpipelinen, så att ett API-utslag matchar vad boten skulle göra i gruppen.

3Autentisering med API-nycklar

Varje förfrågan autentiseras med en API-nyckel av formen tk_live_ följd av slumpmässiga tecken – inte din dashboard-inloggning. Du skapar nycklar i ditt konto och skickar nyckeln i Authorization-rubriken som en Bearer-token, eller i en X-API-Key-rubrik.

Den fullständiga hemligheten visas en gång, vid skapandet. Efter det listar dashboarden en nyckel endast med dess korta prefix, så att du kan känna igen den utan att någonsin lagra det fullständiga värdet. Om en nyckel läcker, återkalla den och utfärda en ny – återkallelse träder i kraft inom ungefär en minut.

• Skicka nyckeln som Authorization: Bearer tk_live_din_nyckel_här (en X-API-Key-rubrik fungerar också).
• Nycklar bär läs- eller skrivbehörighet – läs för GET-förfrågningar, skriv för allt som ändrar data. En skrivskyddad nyckel kan inte skapa eller redigera.
• Du kan ha upp till tio aktiva nycklar samtidigt, så att du kan använda en separat nyckel per skript eller tjänst.
• En saknad eller ogiltig nyckel returnerar 401; en nyckel utan den nödvändiga behörigheten returnerar 403 insufficient_scope.

4Tillgängliga endpoints

API:t är organiserat kring spam- och användarkontroller, grupphantering och kontosjälvbetjäning. Den enskilda spam-kontroll-endpointen är öppen för varje plan; resten av ytan är en del av Pro och Business.

• POST /spam/check – kör en text genom samma regelmotor som modererar live-trafik (varje plan). En valfri AI-kontroll kan aktiveras på Pro och uppåt.
• POST /spam/check-batch – kontrollera upp till 20 texter i ett anrop, enbart regler (Pro+).
• POST /users/check – slå upp en Telegram-användare: CAS-status, Telm-spambeslutssignaler och rykte i dina grupper (Pro+).
• GET /groups och GET /groups/{id} – lista och läs dina grupper (Pro+).
• GET och PATCH /groups/{id}/settings – läs och ändra en grupps skyddsinställningar (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules – hantera anpassade modereringsregler (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist – hantera gruppens vitlista (Pro+).
• GET /groups/{id}/journal och GET /groups/{id}/analytics – läs modereringsloggen och analysen (Pro+).
• GET/POST/PATCH/DELETE /webhooks – hantera webhooks för realtidshändelser (Pro+).
• GET /usage och GET /me – kontrollera din kvot och nyckelinformation; dessa förbrukar aldrig kvot (varje plan).

5Spam-kontroll-endpointen i detalj

POST /spam/check är hjärtat i API:t och den enda endpointen du kan prova på vilken plan som helst. Skicka en JSON-body med texten att kontrollera; svaret returnerar ett utslag, en numerisk poäng, ett konfidensvärde och en rekommenderad åtgärd du kan tillämpa i din egen produkt.

En enskild text kan vara upp till 10 000 tecken. På Pro och uppåt kan du välja till en AI-kontroll för svårare fall, hämtad från ett separat dagligt AI-kontroll-utrymme. För hög volym kontrollerar batch-endpointen upp till 20 texter i ett anrop och räknar kvot per objekt.

• Använd utslaget och poängen för att avgöra vad din egen produkt gör – blockera en formulärinlämning, flagga en lead, eller automatiskt ta bort ett meddelande i din egen bot.
• Batch-endpointen är enbart regler; AI-stegen är tillgänglig endast på den enskilda text-endpointen.
• Förfrågningskroppar är begränsade (ungefär 64 KB för en enskild kontroll, 256 KB för en batch); överstora kroppar returnerar 413.

6Planer, hastighetsgränser och dagliga kvoter

Åtkomst mäts på två sätt: en hastighetsgräns per minut (ett burst-tak) och en daglig anropskvot som nollställs vid midnatt UTC. Båda skalar med din plan och räknas per konto, delade över alla dina nycklar. Du kan prova den enskilda spam-kontroll-endpointen på vilken plan som helst, men en riktig integration som rör regler, inställningar, batch-kontroller och webhooks behöver Pro eller högre.

• Free – 100 anrop/dag, endast spam-kontroll.
• Basic – 1 000 anrop/dag, endast spam-kontroll.
• Pro – 10 000 anrop/dag, fullständigt API och webhooks, plus ett dagligt AI-kontroll-utrymme.
• Business – 50 000 anrop/dag, fullständigt API och webhooks, större AI-utrymme.
• Hastighetsgränser per minut skalar också – högre planer får ett mycket större burst-tak.

7Felhantering och statuskoder

API:t använder standard HTTP-statuskoder med en maskinläsbar felkod i kroppen. Bygg din klient för att läsa dessa koder och sänka takten eller uppmana till en uppgradering snarare än att blint försöka igen.

När du överskrider din dagliga kvot returnerar ett mätt anrop 429 med en daily_quota_exceeded-kod, en Retry-After-rubrik, och en kropp som listar din plan, gräns, använt antal, nollställningstid och ett uppgraderingstips. Endpoints som behöver en högre plan returnerar 403 plan_required med den nödvändiga planen.

• 401 – saknad eller ogiltig API-nyckel.
• 403 plan_required – endpointen behöver Pro eller högre.
• 403 insufficient_scope – nyckeln saknar skrivbehörighet för ett ändrande anrop.
• 429 daily_quota_exceeded eller rate_limit_exceeded – vänta på nollställningstiden eller uppgradera; respektera Retry-After-rubriken.
• Läs X-Quota-*-svarsrubrikerna för att ligga steget före gränsen.

8Bästa praxis för en solid integration

Några få vanor håller en integration pålitlig och säker medan den växer.

• Lagra nycklar i en hemlighetshanterare, aldrig i klientkod eller ett git-repository; använd en separat nyckel per tjänst så att du kan återkalla en utan att förstöra de andra.
• Bevaka rubrikerna X-Quota-Used och X-Quota-Limit (eller polla GET /usage) och strypa innan du slår i väggen, inte efter.
• Vid 429, respektera Retry-After och sänk takten; vid 403 plan_required, visa en uppgraderingsuppmaning snarare än att försöka igen.
• För realtidsreaktioner, föredra webhooks framför polling – låt Telm pusha händelser till dig.
• Rotera nycklar regelbundet, och omedelbart om en kan ha läckt.

9Vanliga integrationsscenarier

API:t används för mycket mer än att moderera Telegram-meddelanden.

• Webbplats- och app-registrering: kör inskickad text eller användarnamn genom POST /spam/check innan du accepterar en registrering eller en kommentar.
• Dina egna Telegram-bottar: återanvänd Telm-intelligens i en bot som Telm inte hanterar genom att anropa kontroll-endpointen från din hanterare.
• Bulk-konfiguration: skripta samma regler, vitlistor och inställningar över dussintals grupper med inställnings- och regel-endpoints.
• Data och varning: registrera webhooks för att strömma modereringshändelser in i ett datalager, en dashboard eller en varningskanal i realtid.