REST API — automatizujte Telm z vlastního kódu

1Co vám API umožňuje

REST API Telm dává vašemu vlastnímu kódu stejný dosah jako dashboardu: proženete jakýkoli text antispamovou linkou, vyhledáte telegramového uživatele, ještě než ho vpustíte dovnitř, čtete a měníte nastavení ochrany skupiny, spravujete vlastní pravidla a seznamy povolených, stahujete žurnál moderace i analytiku a registrujete webhooky pro události v reálném čase.

To promění Telm z bota žijícího uvnitř vašich skupin v infrastrukturu, kterou můžete zapojit kamkoli — registrační formulář na webu, CRM bota, vaše vlastní telegramové boty nebo skript, který nakonfiguruje sto skupin naráz.

• Základní URL: api.telm.com/api/public/v1 — stabilní verzovaná cesta (v1 je verze kontraktu).
• Každý požadavek i odpověď je JSON přes HTTPS.
• Interaktivní dokumentace a strojově čitelná specifikace OpenAPI 3.1 žijí na stránce pro vývojáře — načtěte specifikaci do Postmanu, generátoru kódu nebo AI agenta a připravte si základ integrace během pár minut.
• Měřená volání vracejí v každé odpovědi hlavičky X-Quota-Limit, X-Quota-Used a X-Quota-Reset.

2Jak požadavek prochází Telm

Veřejné API žije na vlastní předponě cesty /api/public/, oddělené od dashboardu. Každé volání je autentizováno API klíčem místo relace prohlížeče, prověřeno vůči vašemu plánu a kvótě, spuštěno proti stejnému živému enginu, který moderuje vaše skupiny, a vráceno jako JSON.

Protože API dosahuje na stejný engine a data jako bot, cokoli vidíte nebo měníte na dashboardu můžete udělat i v kódu — a jakákoli změna, kterou provedete v kódu, se na dashboardu objeví okamžitě.

• Požadavky jsou bezstavové: každý nese svůj vlastní klíč a stojí sám o sobě.
• Klíč jedná jménem vašeho účtu a může se dotknout pouze skupin, kde je váš účet správcem.
• Endpoint kontroly spamu dosahuje na přesnou produkční linku pravidel, takže verdikt API odpovídá tomu, co by bot udělal ve skupině.

3Autentizace pomocí API klíčů

Každý požadavek je autentizován API klíčem ve tvaru tk_live_ následovaným náhodnými znaky — ne vaším přihlášením na dashboard. Klíče vytváříte ve svém účtu a posíláte je v hlavičce Authorization jako Bearer token, nebo v hlavičce X-API-Key.

Celé tajemství se zobrazí jen jednou, v okamžiku vytvoření. Poté dashboard klíč uvádí pouze jeho krátkou předponou, takže jej poznáte, aniž byste kdy museli ukládat celou hodnotu. Pokud klíč unikne, zrušte jej a vydejte nový — zrušení se projeví přibližně do minuty.

• Pošlete klíč jako Authorization: Bearer tk_live_your_key_here (funguje i hlavička X-API-Key).
• Klíče nesou rozsah read nebo write — read pro GET požadavky, write pro cokoli, co mění data. Klíč jen pro čtení nemůže vytvářet ani upravovat.
• Můžete držet až deset aktivních klíčů najednou, takže lze použít samostatný klíč pro každý skript nebo službu.
• Chybějící nebo neplatný klíč vrací 401; klíč bez potřebného rozsahu vrací 403 insufficient_scope.

4Dostupné endpointy

API je uspořádáno okolo kontrol spamu a uživatelů, správy skupin a samoobsluhy účtu. Samotný endpoint kontroly spamu je otevřený každému plánu; zbytek plochy je součástí Pro a Business.

• POST /spam/check — proženete jeden text stejným enginem pravidel, který moderuje živý provoz (každý plán). Volitelnou kontrolu AI lze zapnout v Pro a výše.
• POST /spam/check-batch — zkontrolujte až 20 textů v jednom volání, jen pravidla (Pro+).
• POST /users/check — vyhledejte telegramového uživatele: stav CAS, signály z rozhodnutí Telm o spamu a reputace ve vašich skupinách (Pro+).
• GET /groups a GET /groups/{id} — vypište a čtěte své skupiny (Pro+).
• GET a PATCH /groups/{id}/settings — čtěte a měňte nastavení ochrany skupiny (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — spravujte vlastní pravidla moderace (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — spravujte seznam povolených skupiny (Pro+).
• GET /groups/{id}/journal a GET /groups/{id}/analytics — čtěte žurnál moderace a analytiku (Pro+).
• GET/POST/PATCH/DELETE /webhooks — spravujte webhooky událostí v reálném čase (Pro+).
• GET /usage a GET /me — zkontrolujte svou kvótu a informace o klíči; tato volání nikdy nespotřebovávají kvótu (každý plán).

5Endpoint kontroly spamu podrobně

POST /spam/check je srdcem API a jediným endpointem, který můžete vyzkoušet v jakémkoli plánu. Pošlete JSON tělo s textem ke kontrole; odpověď vrátí verdikt, číselné skóre, hodnotu jistoty a doporučenou akci, kterou můžete uplatnit ve vlastním produktu.

Jeden text může mít až 10 000 znaků. V Pro a výše se můžete pro těžší případy přihlásit ke kontrole AI, čerpané ze samostatného denního přídělu kontrol AI. Pro velké objemy dávkový endpoint zkontroluje až 20 textů v jednom volání a počítá kvótu za položku.

• Použijte verdikt a skóre k rozhodnutí, co udělá váš vlastní produkt — zablokovat odeslání formuláře, označit lead nebo automaticky odstranit zprávu ve vašem vlastním botovi.
• Dávkový endpoint používá jen pravidla; kontrola AI je dostupná pouze u endpointu pro jeden text.
• Těla požadavků jsou zastropována (zhruba 64 KB pro jednu kontrolu, 256 KB pro dávku); nadměrná těla vracejí 413.

6Plány, limity rychlosti a denní kvóty

Přístup je měřen dvěma způsoby: limitem rychlosti za minutu (strop nárazu) a denní kvótou volání, která se obnovuje o půlnoci UTC. Oba se škálují s vaším plánem a počítají se za účet, sdílené napříč všemi vašimi klíči. Samotný endpoint kontroly spamu můžete vyzkoušet v jakémkoli plánu, ale skutečná integrace, která se dotýká pravidel, nastavení, dávkových kontrol a webhooků, potřebuje Pro nebo výše.

• Free — 100 volání/den, jen kontrola spamu.
• Basic — 1 000 volání/den, jen kontrola spamu.
• Pro — 10 000 volání/den, kompletní API a webhooky, plus denní příděl kontrol AI.
• Business — 50 000 volání/den, kompletní API a webhooky, větší příděl AI.
• Limity rychlosti za minutu se škálují také — vyšší plány mají mnohem větší strop nárazu.

7Zpracování chyb a stavové kódy

API používá standardní stavové kódy HTTP se strojově čitelným chybovým kódem v těle. Sestavte svého klienta tak, aby tyto kódy četl a couvl nebo vyzval k upgradu, místo aby slepě opakoval.

Když překročíte denní kvótu, měřené volání vrátí 429 s kódem daily_quota_exceeded, hlavičkou Retry-After a tělem, které uvádí váš plán, limit, počet použití, čas obnovení a nápovědu k upgradu. Endpointy, které vyžadují vyšší plán, vracejí 403 plan_required s požadovaným plánem.

• 401 — chybějící nebo neplatný API klíč.
• 403 plan_required — endpoint vyžaduje Pro nebo výše.
• 403 insufficient_scope — klíči chybí rozsah write pro měnící volání.
• 429 daily_quota_exceeded nebo rate_limit_exceeded — počkejte na čas obnovení nebo upgradujte; respektujte hlavičku Retry-After.
• Čtěte hlavičky odpovědí X-Quota-*, abyste byli o krok napřed před limitem.

8Osvědčené postupy pro solidní integraci

Několik návyků udrží integraci spolehlivou a bezpečnou, jak roste.

• Ukládejte klíče do správce tajemství, nikdy do kódu na straně klienta ani do git repozitáře; použijte samostatný klíč pro každou službu, abyste mohli jeden zrušit, aniž byste rozbili ostatní.
• Sledujte hlavičky X-Quota-Used a X-Quota-Limit (nebo se dotazujte GET /usage) a přiškrťte, než narazíte na strop, ne potom.
• Při 429 respektujte Retry-After a couvněte; při 403 plan_required zobrazte výzvu k upgradu, místo abyste opakovali.
• Pro reakce v reálném čase upřednostněte webhooky před dotazováním — nechte Telm posílat události k vám.
• Klíče pravidelně obměňujte a okamžitě, pokud jeden mohl uniknout.

9Časté scénáře integrace

API se používá k mnohem víc než jen moderaci telegramových zpráv.

• Registrace na webu a v aplikaci: proženete odeslaný text nebo uživatelská jména přes POST /spam/check, ještě než přijmete registraci nebo komentář.
• Vaše vlastní telegramové boty: znovu využijte inteligenci Telm v botovi, kterého Telm nespravuje, voláním kontrolního endpointu z vašeho handleru.
• Hromadná konfigurace: naskriptujte stejná pravidla, seznamy povolených a nastavení napříč desítkami skupin pomocí endpointů pro nastavení a pravidla.
• Data a upozorňování: zaregistrujte webhooky, abyste v reálném čase streamovali události moderace do datového skladu, na dashboard nebo do upozorňovacího kanálu.