Configuration de webhook de bot Telegram : guide complet pour les développeurs

La configuration de webhook de bot Telegram connecte votre serveur au flux de mises à jour de Telegram afin que les messages arrivent en temps réel au lieu d’une boucle de polling. Si vous construisez un bot personnalisé avec l’API Bot, les webhooks sont le chemin de production standard : Telegram POSTe chaque mise à jour vers votre point de terminaison HTTPS, et votre code répond.

Ce guide passe en revue les prérequis, l’enregistrement, un exemple de gestionnaire fonctionnel, la vérification, le dépannage et quand une plateforme gérée comme TeleClaw est plus judicieuse que l’auto-hébergement.

Points clés à retenir

• Les webhooks et le long polling sont mutuellement exclusifs. La configuration d’un webhook désactive getUpdates jusqu’à ce que vous le supprimiez.
• HTTPS est obligatoire. Votre point de terminaison nécessite TLS 1.2+, un certificat correspondant et le port 443, 80, 88 ou 8443.
• Enregistrez avec setWebhook, vérifiez avec getWebhookInfo. Vérifiez last_error_message lorsque les mises à jour cessent de circuler.
• Utilisez secret_token pour confirmer que les requêtes proviennent de Telegram, et non de scanners aléatoires qui frappent votre URL.
• Alternative sans code : TeleClaw gère l’hébergement et la livraison, vous permettant ainsi de sauter entièrement la couche serveur.

Webhooks vs long polling : lequel choisir

Telegram propose deux façons de recevoir les mises à jour. Selon la FAQ des bots, vous choisissez une méthode par bot. Vous ne pouvez pas exécuter les deux en même temps.

Le long polling est le moyen le plus rapide de prototyper. Votre bot appelle getUpdates en boucle, traite chaque lot et avance le décalage. Pas de domaine, pas de certificat, pas de port ouvert.

Les webhooks inversent le modèle. Telegram envoie un POST HTTPS à votre URL chaque fois que quelqu’un envoie un message au bot. Cela supprime les requêtes de polling inactives et réduit le temps de réaction, ce qui est important pour les bots de support, les flux de paiement et la modération de groupe à grande échelle.

Si vous enregistrez toujours le bot lui-même, commencez par notre guide de création d’un bot Telegram pour obtenir un jeton de BotFather avant de continuer ici.

Prérequis pour la configuration de webhook de bot Telegram

Avant d’appeler setWebhook, confirmez que votre infrastructure répond aux exigences de Telegram de la guide officiel des webhooks :

• Jeton de bot de @BotFather (voir le guide de création de bot lié ci-dessus).
• Domaine public avec un certificat TLS valide. Les certificats auto-signés ne fonctionnent que si vous téléchargez la clé publique via le paramètre certificate.
• Port pris en charge sur votre serveur : 443 (par défaut), 80, 88 ou 8443. Les autres ports sont rejetés.
• CN ou SAN du certificat doit correspondre au domaine de votre URL de webhook. Les certificats wildcard peuvent ne pas fonctionner. Les redirections ne sont pas prises en charge.
• Accès POST entrant depuis les sous-réseaux Telegram 149.154.160.0/20 et 91.108.4.0/22.

Pour le développement local, exposez localhost via un tunnel (ngrok, Cloudflare Tunnel ou similaire) qui vous donne une URL HTTPS publique. Testez que le tunnel renvoie HTTP 200 pour les requêtes POST avant d’enregistrer le webhook.

Étape 1 : Construisez votre point de terminaison de webhook

Votre serveur a besoin d’une route qui accepte les requêtes POST, analyse l’objet JSON Update et renvoie rapidement HTTP 200. Les gestionnaires lents entraînent des tentatives de Telegram et finissent par signaler des erreurs dans getWebhookInfo.

Exemple minimal Node.js avec 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 avec Flask suit le même modèle : lire le JSON de request, valider l’en-tête secret si configuré, traiter la mise à jour, renvoyer 200.

Répondez rapidement. Les tâches lourdes (écritures de base de données, appels d’API IA) doivent être placées dans une file d’attente en arrière-plan. Telegram s’attend à un accusé de réception rapide. Vous pouvez également répondre en ligne en renvoyant un corps JSON avec un champ method au lieu de faire un appel d’API séparé, comme décrit dans les notes de webhook de l’API Bot.

Étape 2 : Configurer le webhook du bot Telegram avec setWebhook

Une fois votre point de terminaison en ligne, enregistrez-le auprès de l’API Bot. Remplacez <TOKEN> et l’URL par vos valeurs.

Utilisation de 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
 }'

Référence des paramètres :

• url (obligatoire) : Votre point de terminaison HTTPS. Utilisez une chaîne vide pour supprimer le webhook.
• secret_token (facultatif) : 1-256 caractères (A-Z, a-z, 0-9, _, -). Telegram l’envoie dans l’en-tête X-Telegram-Bot-Api-Secret-Token.
• max_connections (facultatif) : 1-100 connexions simultanées. La valeur par défaut est 40.
• allowed_updates (facultatif) : Limitez les types de mises à jour que vous recevez. Réduit la taille de la charge utile si vous ne traitez que les messages.
• drop_pending_updates (facultatif) : Définissez true pour ignorer les mises à jour en attente lors du changement de webhooks.
• certificate (facultatif) : Téléchargez votre fichier de clé publique pour les certificats auto-signés.

Une réponse réussie ressemble à {"ok":true,"result":true,"description":"Webhook was set"}.

Étape 3 : Vérifier avec getWebhookInfo

Confirmez toujours l’enregistrement immédiatement. C’est votre premier outil de dépannage lorsque les mises à jour cessent d’arriver.

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

Exemple de réponse :

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

Surveillez ces champs :

• url : Vide signifie qu’aucun webhook n’est actif (le bot est en long polling).
• pending_update_count : Mises à jour en attente de livraison. Un nombre croissant signale des échecs de livraison.
• last_error_date et last_error_message : La raison de l’échec le plus récent. Corrigez la cause première, puis Telegram réessaie automatiquement.
• ip_address : Quelle IP Telegram frappe actuellement votre point de terminaison.

Envoyez un message test à votre bot depuis un compte Telegram réel. Si pending_update_count reste à zéro et que les journaux de votre serveur affichent le POST, la configuration du webhook du bot Telegram fonctionne.

Exemple de webhook de bot Telegram : gestionnaire de demande de jointure

Les bots de demande de jointure (flux d’admission de type Guardian) ont besoin du type de mise à jour chat_join_request. Notre guide du bot Guardian couvre l’aspect produit. Voici le câblage du webhook.

Enregistrez-vous avec les demandes de jointure activées :

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

Logique du gestionnaire (pseudocode) :

if (update.chat_join_request) {
 const { chat, from, invite_link } = update.chat_join_request;
 // Exécutez la logique de filtrage, puis approuvez ou refusez via l'API Bot
 await approveChatJoinRequest(chat.id, from.id);
}

Telegram livre les demandes de jointure sous forme de mises à jour push, de sorte que les webhooks sont un ajustement naturel pour les bots d’admission qui doivent répondre avant l’expiration de la demande.

Supprimer le webhook du bot Telegram et revenir au polling

Besoin de déboguer localement avec getUpdates ? Supprimez d’abord le webhook.

Option A avec deleteWebhook :

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

Option B avec setWebhook et URL vide :

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

Les deux méthodes réactivent le long polling. Si vous ignorez cette étape, getUpdates ne renvoie rien car le webhook est toujours enregistré sur votre URL de production.

Dépannage des erreurs courantes de webhook

Lorsque getWebhookInfo affiche des erreurs, faites correspondre le message à une solution :

Exécutez getWebhookInfo selon un calendrier en production. Détecter last_error_message tôt évite des heures de perte de messages silencieuse.

Oubliez le serveur : bots gérés avec TeleClaw

Tous les bots n’ont pas besoin d’une infrastructure de webhook personnalisée. Si votre objectif est un assistant IA pour un groupe ou un canal d’entreprise, l’hébergement et la livraison des mises à jour sont des problèmes résolus.

TeleClaw connecte votre jeton BotFather à un runtime géré alimenté par OpenClaw. Vous configurez la personnalité, la base de connaissances et les règles de modération dans le tableau de bord. La plateforme gère les points de terminaison HTTPS, la mise à l’échelle et le routage des modèles d’IA. Ajoutez @claw en tant qu’administrateur de groupe et mettez en ligne sans écrire de gestionnaire de webhook.

Découvrez ce qu’un bot géré peut faire sur la page des fonctionnalités de TeleClaw. Pour une présentation complète sans code, consultez notre guide de chatbot Telegram sans code.

Les webhooks personnalisés ont toujours un sens lorsque vous avez besoin d’un contrôle total : backends propriétaires, résidence de données réglementée ou traitement de mises à jour non standard. Pour tout le reste, le coût opérationnel de la gestion des certificats, de la surveillance et de la gestion des tentatives s’accumule rapidement.

Conclusion

La configuration de webhook de bot Telegram se résume à quatre étapes : déployer un point de terminaison HTTPS, appeler setWebhook, vérifier avec getWebhookInfo et surveiller les erreurs. Utilisez secret_token pour la validation des requêtes, limitez allowed_updates à ce que vous traitez et gardez les gestionnaires rapides.

Les développeurs qui souhaitent une livraison push en production sans exécuter de serveurs peuvent utiliser TeleClaw à la place. Collez votre jeton, configurez le comportement de l’IA et concentrez-vous sur ce que le bot dit plutôt que sur la façon dont les mises à jour arrivent.

Prêt à lancer un bot IA sans gérer les webhooks ? Ajoutez @claw à votre groupe Telegram →