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

1Co vám API umožňuje

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

Z Telm se tak místo bota, který žije ve vašich skupinách, stává infrastruktura, kterou zapojíte kamkoli — do registračního formuláře na webu, do CRM bota, do vlastních telegramových botů nebo do skriptu, který nakonfiguruje sto skupin najednou.

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

2Jak požadavek prochází systémem Telm

Veřejné API má vlastní předponu cesty, /api/public/, oddělenou od dashboardu. Každé volání se autentizuje API klíčem místo relace prohlížeče, ověří se vůči vašemu tarifu a kvótě, zpracuje se stejným živým enginem, který moderuje vaše skupiny, a vrátí se jako JSON.

Protože API pracuje se stejným enginem a daty jako bot, cokoli vidíte nebo měníte v dashboardu, můžete udělat i v kódu — a každá změna provedená v kódu se v dashboardu okamžitě projeví.

• Požadavky jsou bezstavové: každý nese 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.
• Koncový bod pro kontrolu spamu prochází přesně stejnou produkční pipeline 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 — nikoli vaším přihlášením do dashboardu. Klíče vytváříte ve svém účtu a klíč odesíláte v hlavičce Authorization jako Bearer token, nebo v hlavičce X-API-Key.

Úplné tajemství se zobrazí jednou, v okamžiku vytvoření. Poté dashboard vypisuje klíč jen podle jeho krátké předpony, takže ho rozpoznáte, aniž byste kdy ukládali úplnou hodnotu. Pokud klíč unikne, odvolejte ho a vydejte nový — odvolání platí okamžitě.

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

4Dostupné koncové body

API je uspořádané kolem kontrol spamu a uživatelů, správy skupin a samoobsluhy účtu. Koncový bod pro jednotlivou kontrolu spamu je otevřený pro každý tarif; zbytek API je součástí tarifů Pro a Business.

• POST /spam/check — prožene jeden text stejným enginem pravidel, který moderuje živý provoz (každý tarif). Na Pro a vyšších lze zapnout volitelnou AI kontrolu.
• POST /spam/check-batch — zkontroluje až 20 textů v jednom volání, pouze pravidly (Pro+).
• POST /users/check — prověří telegramového uživatele: stav v CAS, signály ze spamových rozhodnutí Telm a reputaci ve vašich skupinách (Pro+).
• GET /groups a GET /groups/{id} — výpis a čtení vašich skupin (Pro+).
• GET a PATCH /groups/{id}/settings — čtení a změna nastavení ochrany skupiny (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — správa vlastních moderačních pravidel (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — správa seznamu povolených skupiny (Pro+).
• GET /groups/{id}/journal a GET /groups/{id}/analytics — čtení žurnálu moderace a analytiky (Pro+).
• GET/POST/PATCH/DELETE /webhooks — správa webhooků pro události v reálném čase (Pro+).
• GET /usage a GET /me — kontrola kvóty a informací o klíči; tato volání nikdy nespotřebovávají kvótu (každý tarif).

5Koncový bod pro kontrolu spamu podrobně

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

Jeden text může mít až 10 000 znaků. Na Pro a vyšších můžete pro obtížnější případy zapnout AI kontrolu, která čerpá ze samostatného denního přídělu AI kontrol. Pro velké objemy zkontroluje dávkový koncový bod až 20 textů v jednom volání a kvótu počítá za každou položku.

• Podle verdiktu a skóre rozhodněte, co udělá váš produkt — zablokuje odeslání formuláře, označí lead nebo automaticky odstraní zprávu ve vašem vlastním botovi.
• Dávkový koncový bod používá pouze pravidla; stupňovitá AI kontrola je dostupná jen na koncovém bodu pro jeden text.
• Velikost těla požadavku je omezená (zhruba 64 KB pro jednu kontrolu, 256 KB pro dávku); příliš velká těla vracejí 413.

6Tarify, rychlostní limity a denní kvóty

Přístup se měří dvěma způsoby: rychlostním limitem za minutu (strop pro nárazy) a denní kvótou volání, která se resetuje o půlnoci UTC. Obojí se počítá na účet a sdílí se napříč všemi vašimi API klíči. Koncový bod pro jednotlivou kontrolu spamu můžete vyzkoušet na jakémkoli tarifu, ale skutečná integrace, která pracuje s pravidly, nastavením, dávkovými kontrolami a webhooky, potřebuje Pro nebo vyšší.

• Free — 100 volání za den, pouze kontrola spamu.
• Pro — 10 000 volání za den, úplné API a webhooky a k tomu 1 000 AI kontrol denně.
• Business — 50 000 volání za den, úplné API a webhooky a k tomu 10 000 AI kontrol denně.
• S tarifem rostou i rychlostní limity za minutu — 60 požadavků za minutu na Free, 600 na Pro a 1 800 na Business.
• GET /usage a GET /me se nikdy nezapočítávají do kvóty, takže zbývající rozpočet můžete zkontrolovat kdykoli.

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

API používá standardní stavové kódy HTTP se strojově čitelným kódem chyby v těle. Navrhněte klienta tak, aby tyto kódy četl a podle nich ustoupil nebo nabídl přechod na vyšší tarif, místo aby naslepo opakoval požadavky.

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áš tarif, limit, spotřebovaný počet, čas resetu a nápovědu k upgradu. Koncové body, které vyžadují vyšší tarif, vracejí 403 plan_required s požadovaným tarifem.

• 401 — chybějící nebo neplatný API klíč.
• 403 plan_required — koncový bod vyžaduje Pro nebo vyšší.
• 403 insufficient_scope — klíči chybí rozsah write pro volání, které mění data.
• 429 daily_quota_exceeded nebo rate_limit_exceeded — počkejte na čas resetu nebo upgradujte; respektujte hlavičku Retry-After.
• Sledujte hlavičky odpovědi X-Quota-*, abyste měli před limitem náskok.

8Osvědčené postupy pro spolehlivou integraci

Několik návyků udrží integraci spolehlivou a bezpečnou i ve chvíli, kdy roste.

• Klíče ukládejte do správce tajemství, nikdy do kódu na straně klienta ani do git repozitáře; pro každou službu použijte samostatný klíč, abyste mohli jeden odvolat, aniž byste rozbili ostatní.
• Sledujte hlavičky X-Quota-Used a X-Quota-Limit (nebo se pravidelně dotazujte na GET /usage) a zpomalte dřív, než narazíte do zdi, ne až potom.
• Při 429 respektujte Retry-After a ustupte; při 403 plan_required zobrazte výzvu k upgradu místo opakování.
• Pro reakce v reálném čase dejte přednost webhookům před pravidelným dotazováním — nechte Telm, ať vám události posílá sám.
• Klíče pravidelně rotujte, a okamžitě, pokud některý mohl uniknout.

9Běžné scénáře integrace

API slouží k mnohem více věcem než jen k moderování telegramových zpráv.

• Registrace na webu a v aplikaci: proženete odeslaný text nebo uživatelská jména přes POST /spam/check dřív, než přijmete registraci nebo komentář.
• Vlastní telegramoví boti: využijte inteligenci Telm v botovi, kterého Telm nespravuje, tím, že z vašeho handleru zavoláte koncový bod pro kontrolu.
• Hromadná konfigurace: pomocí koncových bodů pro nastavení a pravidla skriptem nastavíte stejná pravidla, seznamy povolených a nastavení napříč desítkami skupin.
• Data a upozornění: zaregistrujte webhooky a streamujte události moderace v reálném čase do datového skladu, dashboardu nebo upozorňovacího kanálu.