1Co obsahuje každý plán
Dělicí čára je jednoduchá. Kontrola spamu v textu je dostupná v každém plánu, takže i free úroveň může použít detekci Telm jako filtr ve vlastním produktu. Plný rozsah — prověrka uživatelů s úrovněmi rizika, deník rozhodnutí a analytika, správa nastavení a pravidel a webhooky — je součástí plánů Pro a Business.
Každý plán dostává denní kvótu požadavků, dimenzovanou tak, aby náročnější integrace seděly na náročnějších plánech:
- **Free** — 100 API požadavků za den, pouze kontrola spamu.
- **Basic** — 1 000 API požadavků za den, pouze kontrola spamu.
- **Pro** — 10 000 API požadavků za den, plus plný rozsah API a webhooky.
- **Business** — 50 000 API požadavků za den, plus plný rozsah API a webhooky.
- Vytvořte klíče v Nastavení → API a Webhooky, uchovávejte je ve svém bezpečném úložišti, ověřujte podpis každého webhooku a tentýž engine, který střeží vaše skupiny, se stane součástí vašeho vlastního stacku.
2Dotazovatelný záznam každého rozhodnutí
Vše, co engine rozhodne, se zaznamenává, a `GET journal` ten záznam předá vašemu kódu. Každá položka je jedno rozhodnutí: verdikt, skóre za ním, která pravidla se spustila a jaká akce následovala. Protože je stránkování kurzorové, můžete spolehlivě projít celou historii — stránku po stránce, bez mezer a duplicit — a stáhnout ji tam, kde vedete záznamy.
To dělá z deníku páteř archivu pro compliance. Týmy, které musí doložit, proč byl člen odstraněn — kvůli platformové politice, klientské smlouvě nebo regulátorovi — pravidelně exportují deník do vlastního dlouhodobého úložiště, čímž získají nezávislý, dotazovatelný přehled každého vynucovacího zásahu, jenž nezávisí na scrollování zpět Telegramem. Je to tentýž důkaz, který auditní deník v dashboardu předkládá lidem, zpřístupněný vašim systémům.
Vedle toho analytický endpoint vrací řady den po dni — objemy a trendy v čase — takže si zátěž moderace vykreslíte ve vlastních business-intelligence nástrojích vedle všeho ostatního, co sledujete, místo abyste ji odečítali z obrazovky. Deník i analytika jsou součástí plánů Pro a Business.
3Doručování, na které se můžete spolehnout
Push model je důvěryhodný jen tehdy, když si poradí s chvílemi, kdy je váš endpoint pomalý, restartuje se nebo je krátce nedostupný — a Telm si poradí. Doručování je alespoň jednou: každá událost nese stabilní `id` a Telm zkouší dál, dokud váš endpoint přijetí nepotvrdí. Protože doručení alespoň jednou znamená, že tatáž událost může legitimně dorazit dvakrát, deduplikujte podle toho `id` — zaznamenejte ty, které jste zpracovali, a opakování ignorujte — a vaše zpracování zůstane správné bez ohledu na to, kolikrát se doručení zopakuje.
Opakování následují rozšiřující se rozvrh, místo aby bušila do zápasícího endpointu: okamžitě, pak po jedné minutě, pěti minutách, třiceti minutách, dvou hodinách a šesti hodinách — celkem šest pokusů, rozprostřených tak, aby zotavující se službě daly prostor se vrátit. Pokud endpoint zůstane rozbitý — dvacet selhání po sobě a sedmdesát dva hodin bez úspěšného doručení — Telm mu automaticky přestane posílat a upozorní vás na Telegramu, takže se z mrtvé URL stane jasné varování, ať opravíte svého příjemce, místo tiché smršti hromadících se selhání.
Abyste novou integraci zprovoznili správně, nemusíte kvůli testu vyvolávat skutečné události. Testovací ping vám umožní na vyžádání vypálit ukázkové doručení na váš endpoint a ověřit, že vaše kontrola podpisu i obsluha fungují, a historie doručení ukáže, co bylo odesláno a jak dopadl každý pokus — takže rozladěného příjemce odladíte ze záznamu, ne z dohadů.
4Moderace, která mluví se zbytkem vašeho stacku
Moderační bot, který žije výhradně uvnitř Telegramu, je užitečný, ale zároveň je to ostrov. Rozhodnutí, která dělá — každá odstraněná zpráva, každý prověřený uživatel, každý odražený nálet — zůstávají uzamčená v okně chatu, dokud někdo neotevře Telegram, aby se podíval. Pro jednu komunitu to stačí. Pro tým, který provozuje moderaci jako součást větší operace, to znamená, že jediný systém, který ví nejvíc o tom, kdo zneužívá vaše prostory, je zároveň jediným systémem, který nedokáže komunikovat s ničím dalším, co provozujete.
Veřejné REST API a webhooky tuto propast uzavírají. Mění Telm ze samostatného bota na komponentu, kterou zapojíte do nástrojů, jež už máte: do monitoringu a pohotovosti, do archivu pro compliance, do vlastního produktu, do interních dashboardů. Tentýž engine, který chrání vaše skupiny, se stává něčím, na co se vaše ostatní systémy mohou dotazovat, poslouchat jej a řídit.
Tento návod projde tím, co API a webhooky skutečně zpřístupňují — endpointy, události, bezpečnostní model — i konkrétní věci, které s nimi týmy staví. Vše níže je reálná schopnost dostupná dnes; není třeba čekat na žádné SDK a nic z popsaného není jen v plánu produktu.
5Prověřování textu a uživatelů na vyžádání
Dva endpointy umožňují spustit úsudek Telm na vyžádání, z vlastního kódu, aniž by zpráva kdy prošla telegramovou skupinou.
`POST /spam/check` pošle kus textu přesně tím produkčním enginem, který střeží vaše komunity — sdílené signály o spammerech, vzorová pravidla, klasifikátory — a vrátí verdikt. Je to jediné volání dostupné v každém plánu, což z něj dělá přirozený spamový filtr pro váš vlastní produkt: prověřujte komentáře, registrační bia, podpůrné tikety nebo inzeráty na marketplace stejnou detekcí, která chrání vaše telegramové prostory. Přidejte `include_ai`, ať se do výsledku zahrne i AI verdikt pro těžší, nejednoznačnější případy (dostupné v Pro a Business), a v těchto plánech můžete v jednom požadavku dávkovat až dvacet textů místo volání pro každou položku zvlášť.
`POST /users/check` prověřuje osobu, ne zprávu. Kombinuje globální blocklist CAS, vlastní dataset Telm postavený z moderace napříč mnoha komunitami, a vrací úroveň rizika (v Pro a Business), takže se rozhodnete, kolik překážek uplatnit — čistý účet propusťte rovnou, rizikový pozdržte k prověření. Zapojením do vlastního onboardingu odchytíte známého škůdce už u dveří svého webu nebo aplikace, ne až poté, co vstoupil do telegramové skupiny.
Obě volání odpovídají v přímé lince: pošlete text nebo uživatele a hodnocení dostanete zpět v odpovědi. Není žádná fronta k dotazování ani callback, na který se čeká — rozhodnutí přichází spolu s odpovědí.
6Doručení pushem v okamžiku, kdy to nastane
Dotazování deníku je v pořádku pro archivaci, ale když chcete na něco *zareagovat* v okamžiku, kdy to nastane, chcete být obslouženi pushem, ne se ptát. Webhooky (v Pro a Business) přesně to dělají: zaregistrujete endpoint a Telm mu pošle HTTP požadavek v okamžiku, kdy se spustí relevantní událost. Události pokrývají důležité momenty — `spam.detected` a `message.suspicious` pro obsah a `user.banned`, `user.kicked`, `user.muted`, `user.joined` a `user.left` pro členství.
Nasnadě je proměnit vlnu spamu v alert. Nasměrujte `spam.detected` do svého monitoringu nebo pohotovostního systému a náhlý nárůst se stane výzvou tomu, kdo má službu, na stejném místě, kam přistávají vaše ostatní incidenty — nikdo nemusí sledovat Telegram, aby si všiml začínajícího útoku. Tentýž proud napájí dashboardy v reálném čase, drží externí systém synchronizovaný s bany nebo spouští jakýkoli workflow, který si přejete.
Protože tyto požadavky přicházejí z vnějšího světa do vaší infrastruktury, je každé doručení podepsané. Každý požadavek nese hlavičku `X-Telm-Signature` ve tvaru `v1=hex(hmac_sha256(secret, "timestamp.body"))` — HMAC-SHA256 přes časovou značku a tělo požadavku, s tajným klíčem, který sdílíte jen vy a Telm. Přepočtení tohoto podpisu na vaší straně dokáže, že požadavek skutečně přišel od Telm a nebyl při přenosu zfalšován ani pozměněn; časová značka umožňuje odmítnout zastaralé replay útoky. Ověřte podpis dřív, než payloadu důvěřujete — je to pár řádků kódu a ten jediný nejdůležitější krok v bezpečném příjemci webhooku.
7REST API a vaše klíče
API najdete na `https://api.telm.com/api/public/v1`. Je to prosté REST rozhraní — voláte jej běžnými HTTPS požadavky a JSONem, z libovolného jazyka, bez zvláštní klientské knihovny. Pokud váš kód umí odeslat HTTP požadavek, umí mluvit s Telm.
Autentizace probíhá pomocí API klíče. Klíče vytváříte v dashboardu v Nastavení → API a Webhooky a každý se vám při vytvoření zobrazí přesně jednou — okamžitě si jej zkopírujte do svého bezpečného úložiště, protože už jej nelze získat znovu. Klíče mají prefix `tk_live_`, aby se snadno poznaly v lozích a konfiguraci. Každý klíč nese rozsah — čtení nebo zápis — takže služba, která potřebuje jen stahovat deník rozhodnutí, může držet klíč jen pro čtení, zatímco automatizace měnící nastavení dostane klíč pro zápis. Vytvořte jeden klíč na systém a odvolání uniklého či vyřazeného klíče nikdy neruší ostatní.
Spotřebu řídí denní kvóta požadavků navázaná na váš plán, takže propustnost je předvídatelná a jeden ujetý skript nevyčerpá vše. Nejlehčí kontrola — skenování spamu v textu — je dostupná v každém plánu v rámci té kvóty; širší rozsah, od deníku rozhodnutí přes správu nastavení po webhooky, je součástí plánů Pro a Business. Přesná čísla najdete na konci.
8Správa mnoha skupin z kódu
API nejen čte a poslouchá — také zapisuje. V Pro a Business můžete provést `PATCH` nastavení skupiny a plné vytvoření/čtení/úprava/mazání jejích pravidel i whitelistu, to vše programově. Cokoli byste nastavovali ručně v dashboardu, nastavíte ze skriptu.
Právě to dělá provoz moderace ve velkém praktickým. Agentura nebo velký operátor spravující desítky komunit nechce otevírat každou zvlášť a proklikávat se stejnými změnami; chce definovat politiku jednou a uplatnit ji všude. S API zavedete nové pravidlo, upravíte práh nebo přidáte adresu do každého whitelistu napříč celou flotilou v jediném automatizovaném průchodu a udržíte všechny skupiny sladěné, jak se vaše standardy vyvíjejí.
Umožňuje to také, aby moderační politika žila ve vašem vlastním systému správy verzí. Uchovávejte požadovanou konfiguraci jako kód, aplikujte ji přes API a každá změna v tom, jak se vaše skupiny řídí, prochází revizí a je verzována jako zbytek vaší infrastruktury — na hony vzdálené tomu, abyste si museli pamatovat, které nastavení jste v kterém chatu přepnuli.