Telegram-Moderation in Ihren eigenen Stack einbinden: API und Webhooks

1Moderation, die mit dem Rest Ihres Stacks spricht

Ein Moderationsbot, der vollständig in Telegram lebt, ist nützlich, aber auch eine Insel. Die Entscheidungen, die er trifft — jede Nachricht, die er entfernt, jeder Nutzer, den er prüft, jeder Raid, den er abwehrt — bleiben in einem Chatfenster eingeschlossen, solange niemand Telegram öffnet, um nachzusehen. Für eine einzelne Community ist das in Ordnung. Für ein Team, das Moderation als Teil eines größeren Betriebs betreibt, bedeutet es: Das eine System, das am meisten darüber weiß, wer Ihre Räume missbraucht, ist genau das System, das mit nichts anderem sprechen kann, das Sie betreiben.

Die öffentliche REST-API und Webhooks schließen diese Lücke. Sie machen aus Telm statt eines in sich geschlossenen Bots eine Komponente, die Sie in Ihre bestehenden Tools einbinden können: Ihr Monitoring und Ihre Bereitschaft, Ihr Compliance-Archiv, Ihr eigenes Produkt, Ihre internen Dashboards. Dieselbe Engine, die Ihre Gruppen schützt, wird zu etwas, das Ihre anderen Systeme abfragen, abhören und steuern können.

Dieser Leitfaden führt durch das, was die API und die Webhooks tatsächlich bereitstellen — die Endpunkte, die Ereignisse, das Sicherheitsmodell — und die konkreten Dinge, die Teams damit bauen. Alles unten ist eine echte Funktion, die heute verfügbar ist; es gibt kein SDK, auf das man warten müsste, und nichts hier Beschriebenes, das das Produkt erst plant.

2Die REST-API und Ihre Schlüssel

Die API liegt unter `https://api.telm.com/api/public/v1`. Es ist eine schlichte REST-Schnittstelle — Sie rufen sie mit gewöhnlichen HTTPS-Anfragen und JSON auf, aus jeder Sprache, ohne spezielle Client-Bibliothek. Wenn Ihr Code eine HTTP-Anfrage stellen kann, kann er mit Telm sprechen.

Die Authentifizierung erfolgt per API-Schlüssel. Sie erstellen Schlüssel im Dashboard unter Einstellungen → API & Webhooks, und jeder wird Ihnen bei der Erstellung genau einmal angezeigt — kopieren Sie ihn dann sofort in Ihren Secrets-Speicher, denn danach lässt er sich nicht erneut abrufen. Schlüssel tragen das Präfix `tk_live_`, sodass sie in Logs und Config leicht zu erkennen sind. Jeder Schlüssel trägt einen Geltungsbereich — Lesen oder Schreiben —, sodass ein Dienst, der nur das Entscheidungs-Log abrufen muss, einen Nur-Lese-Schlüssel halten kann, während eine Automatisierung, die Einstellungen ändert, einen Schreibschlüssel bekommt. Erstellen Sie einen Schlüssel pro System, und der Widerruf eines geleakten oder ausgemusterten Schlüssels stört die anderen nie.

Die Nutzung wird durch ein an Ihren Tarif gebundenes Tageskontingent an Anfragen geregelt, sodass der Durchsatz planbar ist und ein einzelnes außer Kontrolle geratenes Skript nicht alles aufbrauchen kann. Die leichteste Prüfung — das Scannen von Text auf Spam — ist in jedem Tarif innerhalb dieses Kontingents verfügbar; der umfassendere Funktionsumfang, vom Entscheidungsjournal über die Einstellungsverwaltung bis zu Webhooks, ist Teil der Tarife Pro und Business. Die genauen Zahlen stehen am Ende.

3Text und Nutzer auf Abruf prüfen

Zwei Endpunkte lassen Sie Telms Urteil auf Abruf ausführen, aus Ihrem eigenen Code, ohne dass eine Nachricht je durch eine Telegram-Gruppe läuft.

`POST /spam/check` schickt einen Text durch genau die produktive Engine, die Ihre Communities schützt — die geteilten Spammer-Signale, die Musterregeln, die Klassifikatoren — und liefert ein Urteil zurück. Dies ist der eine Aufruf, der in jedem Tarif verfügbar ist, was ihn zu einem natürlichen Spam-Filter für Ihr eigenes Produkt macht: Prüfen Sie Kommentare, Anmelde-Bios, Support-Tickets oder Marktplatz-Anzeigen mit derselben Erkennung, die Ihre Telegram-Räume schützt. Fügen Sie `include_ai` hinzu, um für die schwierigeren, mehrdeutigen Fälle ein KI-Urteil einzubeziehen (verfügbar in Pro und Business); in diesen Tarifen können Sie bis zu zwanzig Texte in einer einzigen Anfrage bündeln, statt einmal pro Element aufzurufen.

`POST /users/check` prüft eine Person statt einer Nachricht. Der Aufruf kombiniert die globale CAS-Sperrliste und Telms eigenen Datensatz aus der Moderation über viele Communities hinweg und liefert eine Risikostufe zurück (in Pro und Business), sodass Sie entscheiden können, wie viel Reibung Sie anwenden — ein sauberes Konto direkt durchwinken, ein riskantes zur Prüfung zurückhalten. Binden Sie ihn in Ihr eigenes Onboarding ein, und Sie erwischen einen bekannten Übeltäter schon an der Tür Ihrer Website oder App, nicht erst, nachdem er einer Telegram-Gruppe beigetreten ist.

Beide Aufrufe antworten inline: Sie senden den Text oder den Nutzer, Sie erhalten die Bewertung in der Antwort zurück. Es gibt keine Warteschlange zum Pollen und keinen Callback, auf den man warten müsste — die Entscheidung kommt mit der Antwort.

4Gepusht werden in dem Moment, in dem es passiert

Das Pollen des Journals ist fürs Archivieren gut, aber wenn Sie auf etwas *reagieren* wollen, sobald es geschieht, wollen Sie gepusht werden, nicht fragen. Webhooks (in Pro und Business) tun genau das: Sie registrieren einen Endpunkt, und Telm sendet ihm eine HTTP-Anfrage in dem Moment, in dem ein relevantes Ereignis auslöst. Die Ereignisse decken die Momente ab, auf die es ankommt — `spam.detected` und `message.suspicious` für Inhalte sowie `user.banned`, `user.kicked`, `user.muted`, `user.joined` und `user.left` für die Mitgliedschaft.

Der naheliegende Einsatz ist, eine Spam-Welle in einen Alarm zu verwandeln. Richten Sie `spam.detected` auf Ihr Monitoring- oder Bereitschaftssystem, und ein plötzlicher Anstieg wird zum Alarm für die diensthabende Person, am selben Ort, an dem auch Ihre anderen Incidents landen — niemand muss Telegram beobachten, um zu bemerken, dass ein Angriff beginnt. Derselbe Strom speist Echtzeit-Dashboards, hält ein externes System mit Sperren synchron oder stößt einen beliebigen Workflow an.

Weil diese Anfragen aus der Außenwelt in Ihre Infrastruktur kommen, ist jede Zustellung signiert. Jede Anfrage trägt einen `X-Telm-Signature`-Header der Form `v1=hex(hmac_sha256(secret, "timestamp.body"))` — einen HMAC-SHA256 über den Zeitstempel und den rohen Body, mit einem Secret geschlüsselt, das nur Sie und Telm teilen. Diese Signatur auf Ihrer Seite neu zu berechnen beweist, dass die Anfrage wirklich von Telm kam und unterwegs nicht gefälscht oder manipuliert wurde; der Zeitstempel lässt Sie veraltete Replays abweisen. Verifizieren Sie die Signatur, bevor Sie dem Payload vertrauen — es sind ein paar Zeilen Code und der wichtigste einzelne Schritt in einem sicheren Webhook-Empfänger.

5Zustellung, auf die Sie sich verlassen können

Ein Push-Modell ist nur dann vertrauenswürdig, wenn es mit den Zeiten zurechtkommt, in denen Ihr Endpunkt langsam ist, neu startet oder kurz ausfällt — und Telms tut das. Die Zustellung erfolgt mindestens einmal: Jedes Ereignis trägt eine stabile `id`, und Telm versucht es weiter, bis Ihr Endpunkt es bestätigt. Weil „mindestens einmal" bedeutet, dass dasselbe Ereignis legitim zweimal ankommen kann, deduplizieren Sie anhand dieser `id` — halten Sie fest, welche Sie verarbeitet haben, und ignorieren Sie Wiederholungen —, und Ihre Verarbeitung bleibt korrekt, egal wie oft eine Zustellung wiederholt wird.

Wiederholungen folgen einem sich weitenden Zeitplan, statt einen kämpfenden Endpunkt zu bombardieren: sofort, dann nach einer Minute, fünf Minuten, dreißig Minuten, zwei Stunden und sechs Stunden — insgesamt sechs Versuche, gestreckt, um einem sich erholenden Dienst Raum zur Rückkehr zu geben. Bleibt ein Endpunkt kaputt — zwanzig Fehlschläge in Folge und zweiundsiebzig Stunden ohne erfolgreiche Zustellung —, stellt Telm die Zustellung automatisch ein und benachrichtigt Sie in Telegram, sodass eine tote URL zu einem klaren Hinweis wird, Ihren Empfänger zu reparieren, statt zu einem stillen Schwall von Fehlschlägen, der sich auftürmt.

Um eine neue Integration richtig hinzubekommen, müssen Sie keine echten Ereignisse provozieren, um sie zu testen. Ein Test-Ping lässt Sie auf Abruf eine Beispielzustellung an Ihren Endpunkt abfeuern und Ihre Signaturprüfung und Ihren Handler bestätigen, und ein Zustellverlauf zeigt, was gesendet wurde und wie jeder Versuch abschnitt — sodass Sie einen fehlerhaften Empfänger anhand des Protokolls debuggen können, statt zu raten.

6Ein abfragbares Protokoll jeder Entscheidung

Alles, was die Engine entscheidet, wird aufgezeichnet, und `GET journal` reicht dieses Protokoll an Ihren Code weiter. Jeder Eintrag ist eine Entscheidung: das Urteil, der Score dahinter, welche Regeln ausgelöst haben und die darauffolgende Aktion. Weil es cursor-paginiert ist, können Sie die gesamte Historie zuverlässig durchlaufen — Seite für Seite, ohne Lücken oder Duplikate — und sie dorthin ziehen, wo Sie Ihre Aufzeichnungen führen.

Das macht das Journal zum Rückgrat eines Compliance-Archivs. Teams, die belegen müssen, warum ein Mitglied entfernt wurde — für eine Plattformrichtlinie, einen Kundenvertrag oder eine Aufsichtsbehörde —, exportieren das Log planmäßig in ihren eigenen Langzeitspeicher und erhalten so ein unabhängiges, abfragbares Protokoll jeder Durchsetzungsmaßnahme, das nicht davon abhängt, in Telegram zurückzuscrollen. Es ist dasselbe Beweismaterial, das das Audit-Log des Dashboards Menschen zeigt, nun für Ihre Systeme verfügbar.

Daneben liefert ein Analytics-Endpunkt Tag-für-Tag-Reihen — Volumina und Trends über die Zeit —, sodass Sie die Moderationslast in Ihren eigenen Business-Intelligence-Tools neben allem anderen darstellen können, das Sie verfolgen, statt sie von einem Bildschirm abzulesen. Sowohl das Journal als auch die Analytics sind Teil der Tarife Pro und Business.

7Viele Gruppen per Code verwalten

Die API liest und lauscht nicht nur — sie schreibt. In Pro und Business können Sie die Einstellungen einer Gruppe per `PATCH` ändern und vollständiges Create/Read/Update/Delete auf ihren Regeln und ihrer Whitelist ausführen, alles programmatisch. Alles, was Sie von Hand im Dashboard konfigurieren würden, können Sie aus einem Skript heraus konfigurieren.

Genau das macht Moderation im großen Maßstab praktikabel. Eine Agentur oder ein großer Betreiber mit Dutzenden Communities will nicht jede einzeln öffnen und dieselben Änderungen durchklicken; sie wollen die Richtlinie einmal definieren und überall anwenden. Mit der API rollen Sie eine neue Regel aus, passen einen Schwellenwert an oder fügen in einem einzigen automatisierten Durchlauf jeder Whitelist der gesamten Flotte eine Adresse hinzu — und halten die Gruppen im Gleichschritt, während sich Ihre Standards weiterentwickeln.

Außerdem lässt sie Ihre Moderationsrichtlinie in Ihrer eigenen Versionsverwaltung leben. Halten Sie die gewünschte Konfiguration als Code, wenden Sie sie über die API an, und jede Änderung daran, wie Ihre Gruppen geführt werden, wird wie der Rest Ihrer Infrastruktur geprüft und versioniert — weit entfernt davon, sich zu merken, welche Einstellungen Sie in welchem Chat umgelegt haben.

8Was jeder Tarif enthält

Die Trennlinie ist einfach. Die Text-Spam-Prüfung ist in jedem Tarif verfügbar, sodass selbst die kostenlose Stufe Telms Erkennung als Filter im eigenen Produkt nutzen kann. Der volle Funktionsumfang — Nutzerprüfung mit Risikostufen, das Entscheidungsjournal und die Analytics, Einstellungs- und Regelverwaltung sowie Webhooks — ist Teil der Tarife Pro und Business.

Jeder Tarif erhält ein tägliches Anfragekontingent, so bemessen, dass schwerere Integrationen auf schwereren Tarifen liegen:

• **Free** — 100 API-Anfragen pro Tag, nur Spam-Prüfung.
• **Basic** — 1.000 API-Anfragen pro Tag, nur Spam-Prüfung.
• **Pro** — 10.000 API-Anfragen pro Tag, plus den vollen API-Umfang und Webhooks.
• **Business** — 50.000 API-Anfragen pro Tag, plus den vollen API-Umfang und Webhooks.
• Erstellen Sie Ihre Schlüssel unter Einstellungen → API & Webhooks, bewahren Sie sie in Ihrem Secrets-Speicher auf, verifizieren Sie die Signatur jedes Webhooks, und dieselbe Engine, die Ihre Gruppen schützt, wird zu einem Teil Ihres eigenen Stacks.