REST API – automatisera Telm från din egen kod

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

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

Det gör Telm till mer än en bot som bor i dina grupper — det blir infrastruktur som 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, versionerad sökväg (v1 är kontraktets version).
• Alla anrop och svar är JSON över HTTPS.
• Interaktiv dokumentation och den maskinläsbara OpenAPI 3.1-specifikationen finns på utvecklarsidan — läs in specifikationen i Postman, en kodgenerator eller en AI-agent för att få en integration på plats på några minuter.
• Mätta anrop returnerar huvudena X-Quota-Limit, X-Quota-Used och X-Quota-Reset i varje svar.

2Så går ett anrop genom Telm

Det publika API:et har ett eget sökvägsprefix, /api/public/, skilt från dashboarden. Varje anrop autentiseras med en API-nyckel i stället för en webbläsarsession, kontrolleras mot din plan och kvot, körs mot samma livemotor som modererar dina grupper och returneras som JSON.

Eftersom API:et når samma motor och data som boten kan du göra allt i kod som du kan se eller ändra i dashboarden — och varje ändring du gör i kod syns direkt i dashboarden.

• Anropen är tillståndslösa: vart och ett bär sin egen nyckel och står på egna ben.
• En nyckel agerar för ditt kontos räkning och kan bara röra grupper där ditt konto är administratör.
• Spamkontroll-endpointen når exakt samma regelflöde som i produktion, så ett utslag från API:et stämmer med vad boten skulle göra i gruppen.

3Autentisering med API-nycklar

Varje anrop autentiseras med en API-nyckel på formen tk_live_ följt av slumpmässiga tecken — inte med din inloggning till dashboarden. Du skapar nycklar i ditt konto och skickar nyckeln i Authorization-huvudet som en Bearer-token, eller i huvudet X-API-Key.

Den fullständiga hemligheten visas en gång, när nyckeln skapas. Därefter listar dashboarden nyckeln bara med dess korta prefix, så att du kan känna igen den utan att någonsin lagra hela värdet. Om en nyckel läcker återkallar du den och utfärdar en ny — återkallelsen träder i kraft direkt.

• Skicka nyckeln som Authorization: Bearer tk_live_your_key_here (huvudet X-API-Key fungerar också).
• Nycklar har läs- eller skrivbehörighet — läsbehörighet för GET-anrop, skrivbehörighet för allt som ändrar data. En nyckel med enbart läsbehörighet kan inte skapa eller redigera.
• Du kan ha upp till tio aktiva nycklar samtidigt, så du kan använda en separat nyckel per skript eller tjänst.
• En saknad eller ogiltig nyckel returnerar 401; en nyckel utan den behörighet som krävs returnerar 403 insufficient_scope.

4Tillgängliga endpoints

API:et är uppbyggt kring spam- och användarkontroller, grupphantering och självbetjäning för kontot. Den enskilda spamkontroll-endpointen är öppen för alla planer; resten av API:et ingår i Pro och Business.

• POST /spam/check — kör en text genom samma regelmotor som modererar livetrafiken (alla planer). En valfri AI-kontroll kan aktiveras på Pro och uppåt.
• POST /spam/check-batch — kontrollera upp till 20 texter i ett anrop, bara med regler (Pro+).
• POST /users/check — slå upp en Telegram-användare: CAS-status, Telms signaler från spambeslut 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 modereringsjournalen och analysen (Pro+).
• GET/POST/PATCH/DELETE /webhooks — hantera webhooks för händelser i realtid (Pro+).
• GET /usage och GET /me — kontrollera din kvot och information om nyckeln; dessa förbrukar aldrig kvot (alla planer).

5Spamkontroll-endpointen i detalj

POST /spam/check är API:ets hjärta och den enda endpoint du kan prova på alla planer. Skicka en JSON-kropp med texten som ska kontrolleras; svaret innehåller ett utslag, en numerisk poäng, ett säkerhetsvärde och en rekommenderad åtgärd som 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 en AI-kontroll för svårare fall, som dras från en separat daglig tilldelning av AI-kontroller. För stora volymer 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 ett inskickat formulär, flagga en lead eller ta bort ett meddelande automatiskt i din egen bot.
• Batch-endpointen använder bara regler; AI-stegen finns bara på endpointen för enskilda texter.
• Anropskroppar har ett tak (ungefär 64 KB för en enskild kontroll, 256 KB för en batch); för stora kroppar returnerar 413.

6Planer, hastighetsgränser och dagliga kvoter

Åtkomsten mäts på två sätt: en hastighetsgräns per minut (ett tak för toppar) och en daglig anropskvot som nollställs vid midnatt UTC. Båda räknas per konto och delas mellan alla dina API-nycklar. Du kan prova den enskilda spamkontroll-endpointen på alla planer, men en riktig integration som rör regler, inställningar, batchkontroller och webhooks kräver Pro eller högre.

• Free — 100 anrop/dag, bara spamkontroll.
• Pro — 10 000 anrop/dag, fullständigt API och webhooks, plus 1 000 AI-kontroller per dag.
• Business — 50 000 anrop/dag, fullständigt API och webhooks, plus 10 000 AI-kontroller per dag.
• Hastighetsgränserna per minut skalar också — 60 anrop per minut på Free, 600 på Pro och 1 800 på Business.
• GET /usage och GET /me räknas aldrig mot din kvot, så du kan när som helst kontrollera hur mycket som är kvar.

7Felhantering och statuskoder

API:et använder vanliga HTTP-statuskoder med en maskinläsbar felkod i svarskroppen. Bygg din klient så att den läser dessa koder och backar eller föreslår en uppgradering i stället för att försöka igen i blindo.

När du överskrider din dagliga kvot returnerar ett mätt anrop 429 med koden daily_quota_exceeded, ett Retry-After-huvud och en kropp med din plan, gräns, antal använda anrop, nollställningstid och ett uppgraderingstips. Endpoints som kräver en högre plan returnerar 403 plan_required tillsammans med den plan som krävs.

• 401 — API-nyckeln saknas eller är ogiltig.
• 403 plan_required — endpointen kräver Pro eller högre.
• 403 insufficient_scope — nyckeln saknar skrivbehörighet för ett anrop som ändrar data.
• 429 daily_quota_exceeded eller rate_limit_exceeded — vänta till nollställningen eller uppgradera; respektera Retry-After-huvudet.
• Läs svarshuvudena X-Quota-* för att ligga steget före gränsen.

8Bästa praxis för en stabil integration

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

• Förvara nycklar i en hemlighetshanterare, aldrig i kod på klientsidan eller i ett git-repository; använd en separat nyckel per tjänst så att du kan återkalla en utan att de andra slutar fungera.
• Håll koll på huvudena X-Quota-Used och X-Quota-Limit (eller fråga GET /usage regelbundet) och sakta ner innan du slår i taket, inte efteråt.
• Vid 429, respektera Retry-After och backa; vid 403 plan_required, visa en uppmaning att uppgradera i stället för att försöka igen.
• För reaktioner i realtid, välj webhooks framför polling — låt Telm skicka händelserna till dig.
• Rotera nycklar med jämna mellanrum, och omedelbart om en nyckel kan ha läckt.

9Vanliga integrationsscenarier

API:et används till mycket mer än att moderera Telegram-meddelanden.

• Registrering på webbplatser och i appar: kör inskickad text eller användarnamn genom POST /spam/check innan du godkänner en registrering eller en kommentar.
• Dina egna Telegram-botar: återanvänd Telms intelligens i en bot som Telm inte hanterar genom att anropa kontroll-endpointen från din hanterare.
• Massinställningar: skripta samma regler, vitlistor och inställningar för dussintals grupper med endpointerna för inställningar och regler.
• Data och larm: registrera webhooks för att strömma modereringshändelser till ett datalager, en dashboard eller en larmkanal i realtid.