Telegram Bot Webhook-Einrichtung: Vollständige Anleitung für Entwickler

Die Einrichtung eines Telegram Bot Webhooks verbindet Ihren Server mit dem Update-Stream von Telegram, sodass Nachrichten in Echtzeit ankommen, anstatt in einer Polling-Schleife. Wenn Sie einen benutzerdefinierten Bot mit der Bot API erstellen, sind Webhooks der Standard-Produktionspfad: Telegram POSTet jedes Update an Ihren HTTPS-Endpunkt, und Ihr Code antwortet.

Dieser Leitfaden führt Sie durch die Voraussetzungen, die Registrierung, ein funktionierendes Handler-Beispiel, die Überprüfung, die Fehlerbehebung und wann eine verwaltete Plattform wie TeleClaw mehr Sinn macht als das Selbst-Hosting.

Wichtige Erkenntnisse

• Webhooks und Long Polling schließen sich gegenseitig aus. Das Setzen eines Webhooks deaktiviert getUpdates, bis Sie ihn entfernen.
• HTTPS ist obligatorisch. Ihr Endpunkt benötigt TLS 1.2+, ein passendes Zertifikat und Port 443, 80, 88 oder 8443.
• Registrieren Sie sich mit setWebhook, überprüfen Sie mit getWebhookInfo. Überprüfen Sie last_error_message, wenn keine Updates mehr fließen.
• Verwenden Sie secret_token, um zu bestätigen, dass Anfragen von Telegram stammen und nicht von zufälligen Scannern, die Ihre URL treffen.
• No-Code-Alternative: TeleClaw übernimmt das Hosting und die Zustellung, sodass Sie die Server-Ebene komplett überspringen können.

Webhooks vs. Long Polling: Was soll man wählen?

Telegram bietet zwei Möglichkeiten, Updates zu empfangen. Laut den Bots FAQ wählen Sie eine Methode pro Bot. Sie können nicht beide gleichzeitig ausführen.

Long Polling ist der schnellste Weg zum Prototyping. Ihr Bot ruft getUpdates in einer Schleife auf, verarbeitet jede Charge und erhöht den Offset. Keine Domain, kein Zertifikat, kein offener Port.

Webhooks drehen das Modell um. Telegram sendet einen HTTPS POST an Ihre URL, wann immer jemand dem Bot eine Nachricht sendet. Das eliminiert unnötige Polling-Anfragen und verkürzt die Reaktionszeit, was für Support-Bots, Zahlungsabläufe und Gruppenmoderation im großen Maßstab wichtig ist.

Wenn Sie den Bot selbst noch registrieren, beginnen Sie mit unserem Leitfaden zum Erstellen eines Telegram Bots, um ein Token von BotFather zu erhalten, bevor Sie hier fortfahren.

Voraussetzungen für die Einrichtung eines Telegram Bot Webhooks

Bevor Sie setWebhook aufrufen, stellen Sie sicher, dass Ihre Infrastruktur die Anforderungen von Telegram aus dem offiziellen Webhook-Leitfaden erfüllt:

• Bot-Token von @BotFather (siehe den oben verlinkten Leitfaden zum Erstellen eines Bots).
• Öffentliche Domain mit einem gültigen TLS-Zertifikat. Selbstsignierte Zertifikate funktionieren nur, wenn Sie den öffentlichen Schlüssel über den Parameter certificate hochladen.
• Unterstützter Port auf Ihrem Server: 443 (Standard), 80, 88 oder 8443. Andere Ports werden abgelehnt.
• Zertifikat CN oder SAN muss mit der Domain in Ihrer Webhook-URL übereinstimmen. Wildcard-Zertifikate funktionieren möglicherweise nicht. Weiterleitungen werden nicht unterstützt.
• Eingehender POST-Zugriff von Telegram-Subnetzen 149.154.160.0/20 und 91.108.4.0/22.

Für die lokale Entwicklung machen Sie localhost über einen Tunnel (ngrok, Cloudflare Tunnel oder ähnliches) zugänglich, der Ihnen eine öffentliche HTTPS-URL gibt. Testen Sie, ob der Tunnel HTTP 200 für POST-Anfragen zurückgibt, bevor Sie den Webhook registrieren.

Schritt 1: Erstellen Sie Ihren Webhook-Endpunkt

Ihr Server benötigt eine Route, die POST-Anfragen akzeptiert, das JSON Update-Objekt parst und schnell HTTP 200 zurückgibt. Langsame Handler führen dazu, dass Telegram erneut versucht und schließlich Fehler in getWebhookInfo meldet.

Minimales Node.js-Beispiel mit Express:

import express from 'express';

const app = express();
app.use(express.json());

const SECRET = process.env. WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
 if (SECRET && req.get('X-Telegram-Bot-Api-Secret-Token')!== SECRET) {
 return res.sendStatus(403);
 }

 const update = req.body;
 // Process update.message, update.callback_query, etc.
 console.log('Update ID:', update.update_id);

 res.sendStatus(200);
});

app.listen(443);

Python mit Flask folgt dem gleichen Muster: JSON aus request lesen, den geheimen Header validieren, falls konfiguriert, das Update verarbeiten, 200 zurückgeben.

Schnell antworten. Aufwendige Arbeiten (Datenbank-Schreibvorgänge, AI-API-Aufrufe) sollten in eine Hintergrundwarteschlange verschoben werden. Telegram erwartet eine schnelle Bestätigung. Sie können auch inline antworten, indem Sie einen JSON-Body mit einem method-Feld zurückgeben, anstatt einen separaten API-Aufruf zu tätigen, wie in den Bot API Webhook-Hinweisen beschrieben.

Schritt 2: Telegram Bot Webhook mit setWebhook konfigurieren

Sobald Ihr Endpunkt live ist, registrieren Sie ihn bei der Bot API. Ersetzen Sie <TOKEN> und die URL durch Ihre Werte.

Mit curl:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -H "Content-Type: application/json" \
 -d '{
 "url": "https://yourdomain.com/webhook",
 "secret_token": "my_random_secret_abc123",
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"],
 "drop_pending_updates": false
 }'

Parameterreferenz:

• url (erforderlich): Ihr HTTPS-Endpunkt. Verwenden Sie einen leeren String, um den Webhook zu entfernen.
• secret_token (optional): 1-256 Zeichen (A-Z, a-z, 0-9, _, -). Telegram sendet es im Header X-Telegram-Bot-Api-Secret-Token.
• max_connections (optional): 1-100 gleichzeitige Verbindungen. Standard ist 40.
• allowed_updates (optional): Begrenzen Sie, welche Update-Typen Sie empfangen. Reduziert die Payload-Größe, wenn Sie nur Nachrichten verarbeiten.
• drop_pending_updates (optional): Setzen Sie true, um in der Warteschlange befindliche Updates beim Wechseln von Webhooks zu verwerfen.
• certificate (optional): Laden Sie Ihre öffentliche Schlüsseldatei für selbstsignierte Zertifikate hoch.

Eine erfolgreiche Antwort sieht so aus: {"ok":true,"result":true,"description":"Webhook was set"}.

Schritt 3: Überprüfen mit getWebhookInfo

Bestätigen Sie die Registrierung immer sofort. Dies ist Ihr erstes Fehlerbehebungstool, wenn keine Updates mehr eintreffen.

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

Beispielantwort:

{
 "ok": true,
 "result": {
 "url": "https://yourdomain.com/webhook",
 "has_custom_certificate": false,
 "pending_update_count": 0,
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"]
 }
}

Beachten Sie diese Felder:

• url: Leer bedeutet, dass kein Webhook aktiv ist (Bot befindet sich im Long Polling).
• pending_update_count: In der Warteschlange befindliche Updates, die auf die Zustellung warten. Eine steigende Zahl signalisiert Zustellungsfehler.
• last_error_date und last_error_message: Der jüngste Fehlergrund. Beheben Sie die Ursache, dann versucht Telegram automatisch erneut.
• ip_address: Welche Telegram-IP derzeit Ihren Endpunkt trifft.

Senden Sie eine Testnachricht an Ihren Bot von einem echten Telegram-Konto. Wenn pending_update_count bei Null bleibt und Ihre Serverprotokolle den POST anzeigen, funktioniert die Telegram Bot Webhook-Einrichtung.

Telegram Bot Webhook Beispiel: Beitrittsanfrage-Handler

Bots für Beitrittsanfragen (Guardian-ähnliche Zulassungsabläufe) benötigen den Update-Typ chat_join_request. Unser Guardian Bot-Leitfaden behandelt die Produktseite. Hier ist die Webhook-Verkabelung.

Registrieren Sie sich mit aktivierten Beitrittsanfragen:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -d "url=https://yourdomain.com/webhook" \
 -d "allowed_updates=[\"chat_join_request\",\"message\"]"

Handler-Logik (Pseudocode):

if (update.chat_join_request) {
 const { chat, from, invite_link } = update.chat_join_request;
 // Führen Sie die Screening-Logik aus und genehmigen oder lehnen Sie dann über die Bot API ab
 await approveChatJoinRequest(chat.id, from.id);
}

Telegram liefert Beitrittsanfragen als Push-Updates, daher sind Webhooks eine natürliche Wahl für Zulassungs-Bots, die reagieren müssen, bevor die Anfrage abläuft.

Telegram Bot Webhook entfernen und zurück zum Polling wechseln

Müssen Sie lokal mit getUpdates debuggen? Entfernen Sie zuerst den Webhook.

Option A mit deleteWebhook:

curl -X POST "https://api.telegram.org/bot<TOKEN>/deleteWebhook" \
 -d "drop_pending_updates=true"

Option B mit setWebhook und leerer URL:

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url="

Beide Methoden aktivieren das Long Polling wieder. Wenn Sie diesen Schritt überspringen, gibt getUpdates nichts zurück, da der Webhook immer noch bei Ihrer Produktions-URL registriert ist.

Fehlerbehebung bei häufigen Webhook-Fehlern

Wenn getWebhookInfo Fehler anzeigt, ordnen Sie die Meldung einer Lösung zu:

Führen Sie getWebhookInfo in der Produktion regelmäßig aus. Das frühzeitige Erkennen von last_error_message verhindert stundenlangen stillen Nachrichtenverlust.

Den Server überspringen: Verwaltete Bots mit TeleClaw

Nicht jeder Bot benötigt eine benutzerdefinierte Webhook-Infrastruktur. Wenn Ihr Ziel ein KI-Assistent für eine Gruppe oder einen Geschäftskanal ist, sind Hosting und Update-Zustellung gelöste Probleme.

TeleClaw verbindet Ihr BotFather-Token mit einer verwalteten Laufzeit, die von OpenClaw betrieben wird. Sie konfigurieren Persönlichkeit, Wissensbasis und Moderationsregeln im Dashboard. Die Plattform übernimmt HTTPS-Endpunkte, Skalierung und KI-Modell-Routing. Fügen Sie @claw als Gruppenadministrator hinzu und gehen Sie live, ohne einen Webhook-Handler schreiben zu müssen.

Entdecken Sie, was ein verwalteter Bot auf der TeleClaw-Funktionsseite leisten kann. Für eine vollständige No-Code-Anleitung siehe unseren Telegram Chatbot ohne Code-Leitfaden.

Benutzerdefinierte Webhooks sind immer noch sinnvoll, wenn Sie die volle Kontrolle benötigen: proprietäre Backends, regulierte Datenresidenz oder nicht-standardmäßige Update-Verarbeitung. Für alles andere summieren sich die Betriebskosten für Zertifikatsverwaltung, Überwachung und Wiederholungsversuche schnell.

Fazit

Die Einrichtung eines Telegram Bot Webhooks besteht aus vier Schritten: Bereitstellen eines HTTPS-Endpunkts, Aufrufen von setWebhook, Überprüfen mit getWebhookInfo und Überwachen auf Fehler. Verwenden Sie secret_token zur Anforderungsvalidierung, begrenzen Sie allowed_updates auf das, was Sie verarbeiten, und halten Sie Handler schnell.

Entwickler, die eine Produktions-Push-Zustellung ohne den Betrieb von Servern wünschen, können stattdessen TeleClaw verwenden. Fügen Sie Ihr Token ein, konfigurieren Sie das KI-Verhalten und konzentrieren Sie sich darauf, was der Bot sagt, anstatt wie Updates ankommen.

Bereit, einen KI-Bot zu starten, ohne Webhooks zu verwalten? Fügen Sie @claw zu Ihrer Telegram-Gruppe hinzu →