1Moderation That Talks to the Rest of Your Stack
A moderation bot that lives entirely inside Telegram is useful, but it’s also an island. The decisions it makes — every message it removes, every user it screens, every raid it turns back — stay locked in a chat window unless someone opens Telegram to look. For a single community that’s fine. For a team running moderation as part of a larger operation, it means the one system that knows the most about who’s abusing your spaces is the one system that can’t talk to anything else you run.
The public REST API and webhooks close that gap. They turn Telm from a self-contained bot into a component you can wire into the tools you already have: your monitoring and on-call setup, your compliance archive, your own product, your internal dashboards. The same engine that protects your groups becomes something your other systems can query, listen to, and drive.
This guide walks through what the API and webhooks actually expose — the endpoints, the events, the security model — and the concrete things teams build with them. Everything below is a real capability available today; there’s no SDK to wait for and nothing described here that the product only plans to do.
2The REST API and Your Keys
The API lives at `https://api.telm.com/api/public/v1`. It’s a plain REST interface — you call it with ordinary HTTPS requests and JSON, from any language, no special client library required. If your code can make an HTTP request, it can talk to Telm.
Authentication is by API key. You create keys in the dashboard under Settings → API & Webhooks, and each one is shown to you exactly once at creation — copy it into your secrets store there and then, because it can’t be retrieved again afterward. Keys are prefixed `tk_live_` so they’re easy to recognise in logs and config. Every key carries a scope — read or write — so a service that only needs to pull the decision log can hold a read-only key, while automation that changes settings gets a write key. Mint one key per system, and revoking a leaked or retired key never disturbs the others.
Usage is governed by a daily request quota tied to your plan, so throughput is predictable and one runaway script can’t exhaust everything. The lightest check — text spam scanning — is available on every plan within that quota; the fuller surface, from the decision journal to settings management to webhooks, is part of the Pro and Business plans. The exact numbers are laid out at the end.
3Screening Text and Users on Demand
Two endpoints let you run Telm’s judgment on demand, from your own code, without a message ever passing through a Telegram group.
`POST /spam/check` sends a piece of text through the exact production engine that guards your communities — the shared spammer signals, the pattern rules, the classifiers — and returns a verdict. This is the one call available on every plan, which makes it a natural spam filter for your own product: screen comments, sign-up bios, support tickets, or marketplace listings with the same detection that protects your Telegram spaces. Add `include_ai` to fold in an AI verdict for the harder, more ambiguous cases (available on Pro and Business), and on those plans you can batch up to twenty texts in a single request instead of calling once per item.
`POST /users/check` screens a person rather than a message. It combines the global CAS blocklist, Telm’s own dataset built from moderation across many communities, and returns a risk level (on Pro and Business) so you can decide how much friction to apply — wave a clean account straight through, hold a risky one for review. Wiring it into your own onboarding lets you catch a known bad actor at the door of your website or app, not just after they’ve joined a Telegram group.
Both calls answer in-line: you send the text or the user, you get the assessment back in the response. There’s no queue to poll and no callback to wait for — the decision comes with the reply.
4Getting Pushed the Moment It Happens
Polling the journal is fine for archiving, but when you want to *react* to something the instant it occurs, you want to be pushed, not to ask. Webhooks (on Pro and Business) do exactly that: you register an endpoint, and Telm sends it an HTTP request the moment a relevant event fires. The events cover the moments that matter — `spam.detected` and `message.suspicious` for content, and `user.banned`, `user.kicked`, `user.muted`, `user.joined`, and `user.left` for membership.
The obvious use is turning a spam wave into an alert. Point `spam.detected` at your monitoring or on-call system and a sudden surge becomes a page to whoever’s on duty, in the same place your other incidents land — no one has to be watching Telegram to notice an attack starting. The same stream feeds real-time dashboards, keeps an external system in sync with bans, or triggers any workflow you like.
Because these requests come from the outside world into your infrastructure, every delivery is signed. Each request carries an `X-Telm-Signature` header of the form `v1=hex(hmac_sha256(secret, "timestamp.body"))` — an HMAC-SHA256 over the timestamp and the raw body, keyed with a secret only you and Telm share. Recomputing that signature on your end proves the request genuinely came from Telm and wasn’t forged or tampered with in transit; the timestamp lets you reject stale replays. Verify the signature before you trust the payload — it’s a few lines of code and the single most important step in a safe webhook receiver.
5Delivery You Can Rely On
A push model is only trustworthy if it copes with the times your endpoint is slow, restarting, or briefly down — and Telm’s does. Delivery is at-least-once: every event carries a stable `id`, and Telm keeps trying until your endpoint acknowledges it. Because at-least-once means the same event can legitimately arrive twice, dedupe on that `id` — record the ones you’ve processed and ignore repeats — and your handling stays correct no matter how many times a delivery is retried.
Retries follow a widening schedule rather than hammering a struggling endpoint: immediately, then after one minute, five minutes, thirty minutes, two hours, and six hours — six attempts in all, spread out to give a recovering service room to come back. If an endpoint stays broken — twenty consecutive failures and seventy-two hours with no successful delivery — Telm stops sending to it automatically and notifies you in Telegram, so a dead URL becomes a clear heads-up to fix your receiver instead of a silent firehose of failures piling up.
For getting a new integration right, you don’t have to provoke real events to test it. A test ping lets you fire a sample delivery at your endpoint on demand and confirm your signature check and handler work, and a delivery history shows what was sent and how each attempt fared — so you can debug a misbehaving receiver from the record instead of guessing.
6A Queryable Record of Every Decision
Everything the engine decides is recorded, and `GET journal` hands that record to your code. Each entry is one decision: the verdict, the score behind it, which rules fired, and the action that followed. Because it’s cursor-paginated, you can walk the entire history reliably — page after page, without gaps or duplicates — and pull it into wherever you keep records.
That makes the journal the backbone of a compliance archive. Teams that have to show why a member was removed — for a platform policy, a client contract, or a regulator — export the log into their own long-term store on a schedule, giving them an independent, queryable account of every enforcement action that doesn’t depend on scrolling back through Telegram. It’s the same evidence the dashboard’s audit log presents to humans, made available to your systems.
Alongside it, an analytics endpoint returns day-by-day series — volumes and trends over time — so you can chart moderation load in your own business-intelligence tools next to everything else you track, rather than reading it off a screen. Both the journal and analytics are part of the Pro and Business plans.
7Managing Many Groups From Code
The API doesn’t only read and listen — it writes. On Pro and Business you can `PATCH` a group’s settings and run full create/read/update/delete on its rules and its whitelist, all programmatically. Anything you’d configure by hand in the dashboard, you can configure from a script.
That’s what makes running moderation at scale practical. An agency or a large operator managing dozens of communities doesn’t want to open each one and click through the same changes; they want to define the policy once and apply it everywhere. With the API you roll out a new rule, adjust a threshold, or add an address to every whitelist across the whole fleet in a single automated pass, and keep the groups in lockstep as your standards evolve.
It also lets moderation policy live in your own source control. Keep the desired configuration as code, apply it through the API, and every change to how your groups are governed is reviewed and versioned like the rest of your infrastructure — a far cry from remembering which settings you toggled in which chat.
8What Each Plan Includes
The dividing line is simple. Text spam-checking is available on every plan, so even the free tier can use Telm’s detection as a filter in its own product. The full surface — user screening with risk levels, the decision journal and analytics, settings and rule management, and webhooks — is part of the Pro and Business plans.
Every plan gets a daily request quota, sized so heavier integrations sit on heavier plans:
- **Free** — 100 API requests per day, spam-check only.
- **Basic** — 1,000 API requests per day, spam-check only.
- **Pro** — 10,000 API requests per day, plus the full API surface and webhooks.
- **Business** — 50,000 API requests per day, plus the full API surface and webhooks.
- Create your keys under Settings → API & Webhooks, keep them in your secrets store, verify every webhook’s signature, and the same engine that guards your groups becomes a part of your own stack.