Telegram bot webhook instellen: complete gids voor ontwikkelaars

De instelling van een Telegram bot webhook verbindt je server met de update-stroom van Telegram, zodat berichten in realtime aankomen in plaats van via een polling-lus. Als je een aangepaste bot bouwt met de Bot API, zijn webhooks het standaard productietraject: Telegram POST elke update naar je HTTPS-eindpunt, en je code reageert.

Deze gids behandelt de vereisten, registratie, een werkend voorbeeld van een handler, verificatie, probleemoplossing en wanneer een beheerd platform zoals TeleClaw meer zin heeft dan zelf-hosting.

Belangrijkste punten

• Webhooks en long polling sluiten elkaar uit. Het instellen van een webhook schakelt getUpdates uit totdat je deze verwijdert.
• HTTPS is verplicht. Je eindpunt heeft TLS 1.2+, een overeenkomstig certificaat en poort 443, 80, 88 of 8443 nodig.
• Registreer met setWebhook, verifieer met getWebhookInfo. Controleer last_error_message wanneer updates niet meer binnenkomen.
• Gebruik secret_token om te bevestigen dat verzoeken van Telegram komen, en niet van willekeurige scanners die je URL raken.
• No-code alternatief: TeleClaw regelt hosting en levering, zodat je de serverlaag volledig overslaat.

Webhooks vs long polling: welke te kiezen

Telegram biedt twee manieren om updates te ontvangen. Volgens de Bots FAQ kies je één methode per bot. Je kunt niet beide tegelijk uitvoeren.

Long polling is de snelste manier om te prototypen. Je bot roept getUpdates in een lus aan, verwerkt elke batch en schuift de offset op. Geen domein, geen certificaat, geen open poort.

Webhooks draaien het model om. Telegram stuurt een HTTPS POST naar je URL wanneer iemand de bot een bericht stuurt. Dat verwijdert inactieve polling-verzoeken en verkort de reactietijd, wat belangrijk is voor supportbots, betalingsstromen en groepsmoderatie op schaal.

Als je de bot zelf nog registreert, begin dan met onze gids voor het maken van een Telegram bot om een token van BotFather te krijgen voordat je hier verdergaat.

Vereisten voor het instellen van een Telegram bot webhook

Voordat je setWebhook aanroept, controleer je of je infrastructuur voldoet aan de vereisten van Telegram uit de officiële webhook-gids:

• Bot-token van @BotFather (zie de hierboven gelinkte gids voor het maken van een bot).
• Openbaar domein met een geldig TLS-certificaat. Zelfondertekende certificaten werken alleen als je de openbare sleutel uploadt via de certificate-parameter.
• Ondersteunde poort op je server: 443 (standaard), 80, 88 of 8443. Andere poorten worden geweigerd.
• Certificaat CN of SAN moet overeenkomen met het domein in je webhook-URL. Wildcard-certificaten werken mogelijk niet. Omleidingen worden niet ondersteund.
• Inkomende POST-toegang van Telegram-subnetten 149.154.160.0/20 en 91.108.4.0/22.

Voor lokale ontwikkeling, exposeer localhost via een tunnel (ngrok, Cloudflare Tunnel of iets dergelijks) die je een openbare HTTPS-URL geeft. Test of de tunnel HTTP 200 retourneert voor POST-verzoeken voordat je de webhook registreert.

Stap 1: Bouw je webhook-eindpunt

Je server heeft een route nodig die POST-verzoeken accepteert, het JSON Update-object parseert en snel HTTP 200 retourneert. Langzame handlers zorgen ervoor dat Telegram opnieuw probeert en uiteindelijk fouten rapporteert in getWebhookInfo.

Minimaal Node.js-voorbeeld met 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 met Flask volgt hetzelfde patroon: lees JSON van request, valideer de geheime header indien geconfigureerd, verwerk de update, retourneer 200.

Reageer snel. Zwaar werk (database-schrijvingen, AI API-aanroepen) moet naar een achtergrondwachtrij gaan. Telegram verwacht een snelle bevestiging. Je kunt ook inline antwoorden door een JSON-body met een method-veld te retourneren in plaats van een aparte API-aanroep te doen, zoals beschreven in de Bot API webhook-notities.

Stap 2: Telegram bot configureer webhook met setWebhook

Zodra je eindpunt live is, registreer je het bij de Bot API. Vervang <TOKEN> en de URL door je waarden.

Met 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
 }'

Parameterreferentie:

• url (verplicht): Je HTTPS-eindpunt. Gebruik een lege string om de webhook te verwijderen.
• secret_token (optioneel): 1-256 tekens (A-Z, a-z, 0-9, _, -). Telegram stuurt het in de X-Telegram-Bot-Api-Secret-Token-header.
• max_connections (optioneel): 1-100 gelijktijdige verbindingen. Standaard is 40.
• allowed_updates (optioneel): Beperk welke updatetypen je ontvangt. Vermindert de payloadgrootte als je alleen berichten verwerkt.
• drop_pending_updates (optioneel): Stel true in om in de wachtrij staande updates te verwijderen bij het wisselen van webhooks.
• certificate (optioneel): Upload je openbare sleutelbestand voor zelfondertekende certificaten.

Een succesvol antwoord ziet eruit als {"ok":true,"result":true,"description":"Webhook was set"}.

Stap 3: Verifieer met getWebhookInfo

Bevestig de registratie altijd onmiddellijk. Dit is je eerste hulpmiddel voor probleemoplossing wanneer updates niet meer binnenkomen.

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

Voorbeeldantwoord:

{
 "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"]
 }
}

Let op deze velden:

• url: Leeg betekent dat er geen webhook actief is (bot gebruikt long polling).
• pending_update_count: In de wachtrij staande updates die wachten op levering. Een stijgend aantal duidt op leveringsfouten.
• last_error_date en last_error_message: De meest recente reden van de storing. Los de hoofdoorzaak op, dan probeert Telegram het automatisch opnieuw.
• ip_address: Welk Telegram IP momenteel je eindpunt raakt.

Stuur een testbericht naar je bot vanuit een echt Telegram-account. Als pending_update_count op nul blijft en je serverlogs de POST tonen, werkt de instelling van de Telegram bot webhook.

Telegram bot webhook voorbeeld: join request handler

Bots voor toetredingsverzoeken (Guardian-achtige toelatingsstromen) hebben het updatetype chat_join_request nodig. Onze Guardian bot gids behandelt de productkant. Hier is de webhook-bedrading.

Registreer met toetredingsverzoeken ingeschakeld:

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

Handler-logica (pseudocode):

if (update.chat_join_request) {
 const { chat, from, invite_link } = update.chat_join_request;
 // Voer screeninglogica uit en keur vervolgens goed of weiger via Bot API
 await approveChatJoinRequest(chat.id, from.id);
}

Telegram levert toetredingsverzoeken als push-updates, dus webhooks zijn een natuurlijke pasvorm voor toelatingsbots die moeten reageren voordat het verzoek verloopt.

Telegram bot webhook verwijderen en terugschakelen naar polling

Moet je lokaal debuggen met getUpdates? Verwijder eerst de webhook.

Optie A met deleteWebhook:

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

Optie B met setWebhook en lege URL:

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

Beide methoden schakelen long polling opnieuw in. Als je deze stap overslaat, retourneert getUpdates niets omdat de webhook nog steeds is geregistreerd bij je productie-URL.

Probleemoplossing voor veelvoorkomende webhook-fouten

Wanneer getWebhookInfo fouten toont, koppel de boodschap dan aan een oplossing:

Voer getWebhookInfo regelmatig uit in productie. Het vroegtijdig opvangen van last_error_message voorkomt uren van stil berichtverlies.

Sla de server over: beheerde bots met TeleClaw

Niet elke bot heeft een aangepaste webhook-infrastructuur nodig. Als je doel een AI-assistent is voor een groep of bedrijfskanaal, zijn hosting en updatelevering opgeloste problemen.

TeleClaw verbindt je BotFather-token met een beheerde runtime, aangedreven door OpenClaw. Je configureert persoonlijkheid, kennisbank en moderatieregels in het dashboard. Het platform regelt HTTPS-eindpunten, schaling en AI-modelroutering. Voeg @claw toe als groepsbeheerder en ga live zonder een webhook-handler te schrijven.

Ontdek wat een beheerde bot kan doen op de TeleClaw functiespagina. Voor een volledige no-code walkthrough, zie onze Telegram chatbot zonder code gids.

Aangepaste webhooks zijn nog steeds zinvol wanneer je volledige controle nodig hebt: eigen backends, gereguleerde gegevensresidentie of niet-standaard updateverwerking. Voor al het andere lopen de operationele kosten van certificaatbeheer, monitoring en herhaalde afhandeling snel op.

Conclusie

De instelling van een Telegram bot webhook komt neer op vier stappen: implementeer een HTTPS-eindpunt, roep setWebhook aan, verifieer met getWebhookInfo en controleer op fouten. Gebruik secret_token voor verzoekvalidatie, beperk allowed_updates tot wat je verwerkt en houd handlers snel.

Ontwikkelaars die productie-pushlevering willen zonder servers te draaien, kunnen in plaats daarvan TeleClaw gebruiken. Plak je token, configureer AI-gedrag en focus op wat de bot zegt in plaats van hoe updates aankomen.

Klaar om een AI-bot te lanceren zonder webhooks te beheren? Voeg @claw toe aan je Telegram-groep →