REST-API — Telm aus Ihrem eigenen Code automatisieren

1Was Sie mit der API tun können

Die Telm-REST-API gibt Ihrem eigenen Code dieselbe Reichweite wie das Dashboard: Lassen Sie beliebige Texte durch die Anti-Spam-Pipeline laufen, prüfen Sie einen Telegram-Nutzer, bevor Sie ihn hereinlassen, lesen und ändern Sie die Schutzeinstellungen einer Gruppe, verwalten Sie eigene Regeln und Whitelists, rufen Sie das Moderationsjournal und Analytics ab und registrieren Sie Webhooks für Ereignisse in Echtzeit.

Damit wird Telm von einem Bot, der in Ihren Gruppen lebt, zu einer Infrastruktur, die Sie überall anbinden können — an ein Registrierungsformular auf Ihrer Website, einen CRM-Bot, Ihre eigenen Telegram-Bots oder ein Skript, das hundert Gruppen auf einmal konfiguriert.

• Basis-URL: api.telm.com/api/public/v1 — ein stabiler, versionierter Pfad (v1 bezeichnet die Version der Schnittstelle).
• Jede Anfrage und jede Antwort ist JSON über HTTPS.
• Die interaktive Dokumentation und die maschinenlesbare OpenAPI-3.1-Spezifikation finden Sie auf der Entwicklerseite — laden Sie die Spezifikation in Postman, einen Codegenerator oder einen KI-Agenten, um eine Integration in wenigen Minuten aufzusetzen.
• Kontingentierte Aufrufe liefern bei jeder Antwort die Header X-Quota-Limit, X-Quota-Used und X-Quota-Reset.

2Wie eine Anfrage durch Telm läuft

Die öffentliche API liegt unter einem eigenen Pfadpräfix, /api/public/, getrennt vom Dashboard. Jeder Aufruf wird mit einem API-Schlüssel statt mit einer Browser-Sitzung authentifiziert, gegen Ihren Plan und Ihr Kontingent geprüft, von derselben Live-Engine verarbeitet, die Ihre Gruppen moderiert, und als JSON zurückgegeben.

Da die API dieselbe Engine und dieselben Daten erreicht wie der Bot, können Sie alles, was Sie im Dashboard sehen oder ändern können, auch per Code erledigen — und jede Änderung, die Sie per Code vornehmen, erscheint sofort im Dashboard.

• Anfragen sind zustandslos: Jede trägt ihren eigenen Schlüssel und steht für sich.
• Ein Schlüssel handelt im Namen Ihres Kontos und kann nur Gruppen berühren, in denen Ihr Konto Administrator ist.
• Der Spam-Prüf-Endpunkt nutzt exakt dieselbe Regel-Pipeline wie die Produktion, sodass ein API-Urteil dem entspricht, was der Bot in der Gruppe tun würde.

3Authentifizierung mit API-Schlüsseln

Jede Anfrage wird mit einem API-Schlüssel der Form tk_live_ gefolgt von zufälligen Zeichen authentifiziert — nicht mit Ihrem Dashboard-Login. Sie erstellen Schlüssel in Ihrem Konto und senden den Schlüssel im Authorization-Header als Bearer-Token oder in einem X-API-Key-Header.

Das vollständige Geheimnis wird nur einmal angezeigt, bei der Erstellung. Danach listet das Dashboard einen Schlüssel nur anhand seines kurzen Präfixes auf, sodass Sie ihn erkennen, ohne den vollständigen Wert je speichern zu müssen. Wenn ein Schlüssel durchsickert, widerrufen Sie ihn und geben Sie einen neuen aus — der Widerruf wirkt sofort.

• Senden Sie den Schlüssel als Authorization: Bearer tk_live_your_key_here (ein X-API-Key-Header funktioniert ebenfalls).
• Schlüssel haben eine Lese- oder Schreibberechtigung — Lesen für GET-Anfragen, Schreiben für alles, was Daten ändert. Ein Schlüssel mit „Nur Lesen“ kann nichts erstellen oder bearbeiten.
• Sie können bis zu zehn aktive Schlüssel gleichzeitig haben und so für jedes Skript oder jeden Dienst einen eigenen Schlüssel verwenden.
• Ein fehlender oder ungültiger Schlüssel ergibt 401; ein Schlüssel ohne die erforderliche Berechtigung ergibt 403 insufficient_scope.

4Verfügbare Endpunkte

Die API gliedert sich in Spam- und Nutzerprüfungen, Gruppenverwaltung und die Selbstverwaltung Ihres Kontos. Der einzelne Spam-Prüf-Endpunkt steht jedem Plan offen; der Rest der API gehört zu Pro und Business.

• POST /spam/check — einen Text durch dieselbe Regel-Engine laufen lassen, die den Live-Verkehr moderiert (jeder Plan). Ab Pro lässt sich optional eine KI-Prüfung aktivieren.
• POST /spam/check-batch — bis zu 20 Texte in einem Aufruf prüfen, nur regelbasiert (Pro+).
• POST /users/check — einen Telegram-Nutzer nachschlagen: CAS-Status, Signale aus Telm-Spam-Entscheidungen und Reputation in Ihren Gruppen (Pro+).
• GET /groups und GET /groups/{id} — Ihre Gruppen auflisten und abrufen (Pro+).
• GET und PATCH /groups/{id}/settings — die Schutzeinstellungen einer Gruppe lesen und ändern (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — eigene Moderationsregeln verwalten (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — die Whitelist der Gruppe verwalten (Pro+).
• GET /groups/{id}/journal und GET /groups/{id}/analytics — Moderationsprotokoll und Analytics lesen (Pro+).
• GET/POST/PATCH/DELETE /webhooks — Webhooks für Ereignisse in Echtzeit verwalten (Pro+).
• GET /usage und GET /me — Ihr Kontingent und die Schlüsselinformationen prüfen; diese Aufrufe verbrauchen nie Kontingent (jeder Plan).

5Der Spam-Prüf-Endpunkt im Detail

POST /spam/check ist das Herzstück der API und der eine Endpunkt, den Sie in jedem Plan ausprobieren können. Senden Sie einen JSON-Body mit dem zu prüfenden Text; die Antwort liefert ein Urteil, einen numerischen Score, einen Konfidenzwert und eine empfohlene Aktion, die Sie in Ihrem eigenen Produkt anwenden können.

Ein einzelner Text kann bis zu 10.000 Zeichen lang sein. Ab Pro können Sie für schwierigere Fälle eine KI-Prüfung zuschalten, die aus einem separaten Tageskontingent für KI-Prüfungen schöpft. Für hohe Volumen prüft der Batch-Endpunkt bis zu 20 Texte in einem Aufruf und zählt das Kontingent pro Element.

• Entscheiden Sie anhand von Urteil und Score, was Ihr eigenes Produkt tut — eine Formularübermittlung blockieren, einen Lead markieren oder eine Nachricht in Ihrem eigenen Bot automatisch entfernen.
• Der Batch-Endpunkt ist nur regelbasiert; die KI-Stufe gibt es nur am Endpunkt für einzelne Texte.
• Anfrage-Bodys sind in der Größe begrenzt (etwa 64 KB für eine Einzelprüfung, 256 KB für einen Batch); zu große Bodys ergeben 413.

6Pläne, Ratenlimits und Tageskontingente

Der Zugriff wird auf zwei Arten bemessen: durch ein Ratenlimit pro Minute (eine Burst-Obergrenze) und ein tägliches Aufrufkontingent, das um Mitternacht UTC zurückgesetzt wird. Beide werden pro Konto gezählt und über alle Ihre API-Schlüssel geteilt. Den einzelnen Spam-Prüf-Endpunkt können Sie in jedem Plan ausprobieren, aber eine echte Integration, die Regeln, Einstellungen, Stapelprüfungen und Webhooks nutzt, braucht Pro oder höher.

• Free — 100 Aufrufe/Tag, nur Spam-Prüfung.
• Pro — 10.000 Aufrufe/Tag, vollständige API und Webhooks, dazu 1.000 KI-Prüfungen pro Tag.
• Business — 50.000 Aufrufe/Tag, vollständige API und Webhooks, dazu 10.000 KI-Prüfungen pro Tag.
• Auch die Ratenlimits pro Minute skalieren — 60 Anfragen pro Minute bei Free, 600 bei Pro und 1.800 bei Business.
• GET /usage und GET /me zählen nie gegen Ihr Kontingent, sodass Sie Ihr verbleibendes Budget jederzeit prüfen können.

7Fehlerbehandlung und Statuscodes

Die API verwendet Standard-HTTP-Statuscodes mit einem maschinenlesbaren Fehlercode im Body. Bauen Sie Ihren Client so, dass er diese Codes liest und dann zurücksteckt oder zu einem Upgrade auffordert, statt blind zu wiederholen.

Wenn Sie Ihr Tageskontingent überschreiten, liefert ein kontingentierter Aufruf 429 mit dem Code daily_quota_exceeded, einem Retry-After-Header und einem Body mit Ihrem Plan, dem Limit, der Zahl verbrauchter Aufrufe, dem Rücksetzzeitpunkt und einem Upgrade-Hinweis. Endpunkte, die einen höheren Plan erfordern, liefern 403 plan_required mit dem erforderlichen Plan.

• 401 — fehlender oder ungültiger API-Schlüssel.
• 403 plan_required — der Endpunkt erfordert Pro oder höher.
• 403 insufficient_scope — dem Schlüssel fehlt die Schreibberechtigung für einen ändernden Aufruf.
• 429 daily_quota_exceeded oder rate_limit_exceeded — warten Sie bis zum Rücksetzzeitpunkt oder führen Sie ein Upgrade durch; beachten Sie den Retry-After-Header.
• Lesen Sie die X-Quota-*-Antwort-Header, um dem Limit zuvorzukommen.

8Best Practices für eine solide Integration

Einige Gewohnheiten halten eine Integration zuverlässig und sicher, während sie wächst.

• Bewahren Sie Schlüssel in einem Secrets-Manager auf, niemals in clientseitigem Code oder einem Git-Repository; verwenden Sie pro Dienst einen eigenen Schlüssel, damit Sie einen widerrufen können, ohne die anderen zu beeinträchtigen.
• Beobachten Sie die Header X-Quota-Used und X-Quota-Limit (oder fragen Sie GET /usage ab) und drosseln Sie, bevor Sie an die Grenze stoßen, nicht erst danach.
• Beachten Sie bei 429 den Retry-After-Header und stecken Sie zurück; zeigen Sie bei 403 plan_required einen Upgrade-Hinweis an, statt es erneut zu versuchen.
• Für Reaktionen in Echtzeit sind Webhooks besser als Polling — lassen Sie Telm Ihnen die Ereignisse senden.
• Rotieren Sie Schlüssel regelmäßig — und sofort, wenn einer durchgesickert sein könnte.

9Typische Integrationsszenarien

Die API wird für weit mehr genutzt als für die Moderation von Telegram-Nachrichten.

• Registrierung auf Websites und in Apps: Lassen Sie übermittelte Texte oder Benutzernamen durch POST /spam/check laufen, bevor Sie eine Registrierung oder einen Kommentar annehmen.
• Ihre eigenen Telegram-Bots: Nutzen Sie die Intelligenz von Telm in einem Bot, den Telm nicht verwaltet, indem Sie den Prüf-Endpunkt aus Ihrem Handler aufrufen.
• Massenkonfiguration: Übertragen Sie per Skript dieselben Regeln, Whitelists und Einstellungen auf Dutzende Gruppen — mit den Einstellungs- und Regel-Endpunkten.
• Daten und Alarmierung: Registrieren Sie Webhooks, um Moderationsereignisse in Echtzeit in ein Data Warehouse, ein Dashboard oder einen Alarmkanal zu streamen.