Telegram Bot API via proxy : configurer le long polling, les webhooks et gérer l'erreur 429

Introduction : ce que vous allez apprendre dans ce guide

Si vous avez déjà lancé un bot Telegram, vous connaissez ce problème. Le bot se code en une soirée, mais le faire tourner de manière fiable devient un projet à part entière. Les messages arrivent en retard, les mises à jour se perdent, le serveur reçoit soudain une erreur 429, et le webhook cesse de répondre sans explication. Ajoutez à cela un proxy par lequel tous les appels doivent passer, et le nombre de points de défaillance double.

Ce guide pas à pas répond exactement à ces problèmes. Vous allez apprendre à utiliser l'API Telegram Bot à travers un serveur proxy pour que votre bot ne plante pas, ne perde pas de messages et réagisse correctement aux limites. Nous ne parlerons pas du protocole MTProto et nous ne construirons pas de système de monitoring de proxy. Notre sujet est plus concret et plus pratique : les requêtes HTTP vers api.telegram.org via un proxy, les deux méthodes de réception des mises à jour, et la bonne réaction aux limites.

Ce que vous obtiendrez au final

• Un bot fonctionnel qui envoie des requêtes à l'API Telegram Bot à travers votre proxy (HTTP ou SOCKS5).
• Un long polling configuré, qui ne casse pas sur les timeouts et ne duplique pas les messages.
• Un webhook avec HTTPS et token secret, qui reçoit les mises à jour sur votre serveur.
• Une fonction d'enveloppe prête à l'emploi qui attend le temps nécessaire lors d'une erreur 429 et réessaie l'envoi.
• Une bonne compréhension du mode à choisir pour votre projet : polling ou webhook.

À qui s'adresse ce guide

Aux marketeurs et affiliés qui créent des bots pour des campagnes de mailing, des notifications de leads et des statistiques de campagne. Aux développeurs qui ont besoin d'une IP sortante fixe et prévisible pour leurs requêtes serveur. Aux propriétaires d'entreprise dont les bots servent des clients et n'ont pas le droit de rester silencieux pendant une heure. Si vous travaillez avec des proxys mobiles et souhaitez faire passer le trafic de votre bot par eux, vous êtes au bon endroit.

Ce qu'il faut savoir au préalable

Nous expliquons chaque étape depuis zéro, mais quelques compétences de base vous faciliteront grandement la vie. Il est utile de savoir ouvrir un terminal ou une invite de commandes, copier des commandes et exécuter des scripts Python. Savoir ce qu'est une requête HTTP et du JSON est un plus, mais nous vous le rappellerons en termes simples. Les sujets avancés sont regroupés dans une section dédiée, que les débutants peuvent ignorer sans perdre le fil.

Combien de temps cela prendra

La préparation et la création du bot prendront environ 20 minutes. La configuration du proxy et la première requête réussie, encore 20 à 30 minutes. Le long polling se met en place en une demi-heure. Le webhook demandera 40 à 60 minutes, car il faut un certificat HTTPS. La gestion de l'erreur 429 ajoutera encore 20 minutes. Au total, comptez entre deux et trois heures de travail tranquille, avec des vérifications à chaque étape.

Préparation : outils et accès nécessaires

Avant d'écrire la première ligne de code, rassemblons tout ce dont nous avons besoin. Ainsi, vous ne serez pas interrompu en pleine étape à chercher où trouver le mot de passe du proxy ou comment installer une bibliothèque.

Outils et accès nécessaires

1. Un compte Telegram avec un numéro lié. C'est depuis ce compte que vous créerez le bot via le bot officiel BotFather.
2. Un accès proxy : adresse du serveur, port, identifiant et mot de passe. Dans votre espace client mobileproxy.space, ces informations apparaissent dans la fiche du proxy acheté. En général, deux ports sont disponibles : un pour la connexion HTTP, l'autre pour SOCKS5. Notez les deux.
3. Un ordinateur ou un serveur avec Python 3.10 ou plus récent. Pour le webhook, il faudra un serveur avec une IP publique et un domaine ; un ordinateur à la maison ne conviendra pas.
4. L'utilitaire curl. Sous Windows 10 et 11, macOS et Linux, il est déjà intégré. Vérifiez avec la commande curl --version.
5. Un éditeur de texte : VS Code, Notepad++ ou tout autre outil confortable pour écrire du code.

Configuration requise

Pour le polling, presque aucune exigence : n'importe quelle machine connectée à Internet, y compris un ordinateur portable. Le bot consomme quelques dizaines de mégaoctets de mémoire. Pour le webhook, il faut un VPS avec une configuration minimale : 1 cœur, 1 Go de RAM, Ubuntu 22.04 ou 24.04. Un domaine pointant vers l'IP de ce serveur et le port 443 ouvert dans le pare-feu sont obligatoires.

Ce qu'il faut installer

1. Ouvrez un terminal.
2. Vérifiez Python avec la commande python3 --version. Sous Windows, la commande peut être python --version.
3. Créez un dossier de projet : mkdir tgbot-proxy, puis placez-vous dedans cd tgbot-proxy.
4. Créez un environnement virtuel : python3 -m venv venv. Activez-le : sous Linux et macOS source venv/bin/activate, sous Windows venv\Scripts\activate.
5. Installez les bibliothèques : pip install requests[socks] flask. Le paquet requests gère les requêtes vers l'API Telegram Bot, le module socks est nécessaire pour un proxy SOCKS5, et Flask recevra le webhook.

Sauvegardes et sécurité des données

Traitez le token du bot comme le mot de passe de votre application bancaire. Celui qui l'obtient pourra écrire au nom du bot à vos clients. Créez un fichier .env avec le token et les données du proxy, et ne l'envoyez jamais dans un dépôt public. Si le bot tourne déjà et que vous le migrez vers un proxy, sauvegardez la configuration actuelle, faites un export de la base de données si elle existe, et notez le résultat de la méthode getWebhookInfo. Ainsi, un retour en arrière ne prendra que deux minutes.

Conseil : Créez un bot de test dédié aux expérimentations. Reproduisez d'abord toutes les étapes de ce guide dessus, puis transférez uniquement la configuration validée vers le bot de production. Vous ne risquerez pas de casser la communication avec de vrais clients.

Notions de base : comment fonctionne l'API Telegram Bot

Décortiquons les termes clés en langage simple. Sans eux, les étapes suivantes sembleront magiques ; avec eux, elles deviendront logiques et prévisibles.

API Telegram Bot

C'est une interface HTTP classique. Votre code envoie une requête à l'adresse https://api.telegram.org/bot<TOKEN>/<méthode>, et le serveur Telegram répond par un objet JSON. Par exemple, la méthode getMe renvoie des informations sur le bot, et sendMessage envoie un texte dans un chat. Aucune bibliothèque spéciale n'est nécessaire, curl ou requests suffisent. C'est précisément pourquoi l'API Telegram Bot est si facile à faire passer par un proxy : c'est le même trafic que n'importe quel site en HTTPS.

Mises à jour (updates)

Chaque événement destiné au bot, qu'il s'agisse d'un message, d'un clic sur un bouton ou d'un ajout à un groupe, arrive sous forme d'objet update avec un numéro unique update_id. Les numéros augmentent dans l'ordre. Votre code doit récupérer ces objets et les traiter. Il existe exactement deux méthodes de réception, et elles s'excluent mutuellement.

Long polling

Votre bot demande lui-même à Telegram : ai-je de nouvelles mises à jour ? Il le fait via la méthode getUpdates. Le terme « long » signifie que le serveur ne répond pas immédiatement par une liste vide, mais garde la connexion ouverte jusqu'à un timeout spécifié, généralement 30 à 60 secondes, et répond dès qu'un événement survient. Cela économise des requêtes et donne une réaction quasi instantanée. Le polling ne nécessite pas d'adresse publique, fonctionne derrière un routeur et via n'importe quel proxy. Idéal pour démarrer et pour les bots à faible charge.

Webhook

Approche inverse. Vous communiquez à Telegram l'adresse de votre serveur via la méthode setWebhook, et Telegram envoie lui-même chaque mise à jour par une requête POST à cette adresse. Vous n'avez rien à interroger. Exigences : un domaine public, un certificat HTTPS et l'un des ports 443, 80, 88 ou 8443. Le webhook monte mieux en charge et ne gaspille pas de ressources en attente.

À bien comprendre : le proxy n'affecte que les requêtes sortantes de votre bot vers Telegram. Les requêtes entrantes du webhook arrivent directement sur votre serveur, et le proxy n'intervient pas dans cette chaîne. Donc l'expression « webhook via proxy » signifie en pratique : le bot répond et appelle les méthodes de l'API via le proxy, mais reçoit les mises à jour sur sa propre adresse publique.

Erreur 429 Too Many Requests

Telegram limite la fréquence des requêtes. Repères pour 2026 : pas plus d'un message par seconde dans un même chat, pas plus de 20 messages par minute dans un groupe, et environ 30 messages par seconde au total pour un bot. En cas de dépassement, le serveur renvoie le statut HTTP 429 et, dans le corps de la réponse, le champ parameters.retry_after avec le nombre de secondes d'attente. Il ne faut pas l'ignorer : les tentatives répétées sans pause allongent la durée du blocage.

Pourquoi utiliser un proxy pour un bot

Les raisons sont purement pratiques. D'abord, une IP sortante fixe et prévisible : pratique quand on a plusieurs serveurs et qu'on veut une seule adresse externe. Ensuite, la séparation du trafic par projet : chaque client ou chaque campagne a son propre canal. Enfin, les politiques d'entreprise, quand toutes les connexions externes doivent passer par une passerelle. Les proxys mobiles sont ici précieux pour leur stabilité et la possibilité de gérer le changement d'IP selon un planning ou via un lien.

Étape 1 : créer le bot et obtenir le token

Objectif : obtenir un token d'accès à l'API Telegram Bot et vérifier que le bot existe.

1. Ouvrez Telegram sur votre téléphone ou votre ordinateur.
2. Dans la barre de recherche, tapez BotFather. Choisissez le bot avec la coche bleue de vérification ; les faux n'en ont pas.
3. Appuyez sur Start ou envoyez la commande /start. Vous verrez la liste des commandes disponibles.
4. Envoyez la commande /newbot.
5. BotFather vous demandera le nom du bot. Entrez un nom affiché, par exemple Proxy Test Bot. Il peut contenir des espaces et des accents.
6. On vous demandera ensuite un username. Il doit être unique, en latin, et se terminer par bot, par exemple proxy_test_2026_bot. Si le nom est pris, BotFather vous le signalera ; trouvez-en un autre.
7. Vous recevrez un message de félicitations avec une chaîne du type 123456789:AAExampleTokenLettersAndDigits. C'est le token. Copiez-le en entier, chiffres avant le deux-points compris.
8. Créez un fichier .env dans le dossier du projet et écrivez-y la ligne BOT_TOKEN=votre_token.

Attention : Ne publiez jamais le token dans des chats, des captures d'écran ou des dépôts ouverts. Si le token fuite, envoyez immédiatement la commande /revoke à BotFather, choisissez le bot et obtenez un nouveau token. L'ancien cessera de fonctionner aussitôt.

Première requête sans proxy

Avant de compliquer le schéma, vérifions que le token fonctionne avec une requête simple depuis votre machine. Exécutez dans le terminal, en remplaçant par votre token :

curl https://api.telegram.org/bot123456789:AAExampleToken/getMe

Réponse attendue : un JSON commençant par {"ok":true,"result":{"id":123456789,"is_bot":true,.... Vous y verrez le username du bot que vous venez de créer.

Vérification : La réponse contient "ok":true et le bon username. Si à la place vous recevez "error_code":401, le token a été mal copié ; vérifiez que des caractères ne manquent pas aux extrémités.

Problèmes possibles

• Username déjà pris. Ajoutez des chiffres ou une abréviation du projet, l'essentiel est de garder la terminaison bot.
• BotFather ne répond pas. Vérifiez que vous avez ouvert le bot avec la coche de vérification, et non un homonyme.
• Erreur 404 Not Found. Le mot bot est manquant avant le token dans l'adresse. Le format est strictement /bot<TOKEN>/méthode.

Étape 2 : connecter le proxy et vérifier l'accès à l'API

Objectif : faire passer les requêtes vers l'API Telegram Bot par votre proxy et le vérifier concrètement, pas seulement en théorie.

Comprendre le format d'adresse du proxy

Un proxy se décrit par une seule chaîne : protocole://login:motdepasse@hôte:port. Prenez les données dans votre espace client. Supposons qu'on vous ait donné l'hôte proxy-host, le port HTTP 8080, le port SOCKS5 1080, l'identifiant user et le mot de passe pass. Les chaînes seront alors :

• Proxy HTTP : http://user:pass@proxy-host:8080
• Proxy SOCKS5 : socks5h://user:pass@proxy-host:1080

Faites attention à la lettre h dans socks5h. Elle signifie que le nom de domaine api.telegram.org sera résolu du côté du proxy, et non sur votre machine. C'est la bonne option pour les proxys mobiles : les requêtes DNS et le trafic empruntent le même chemin. Sans le h, en cas de problème de DNS local, les requêtes échoueront alors que le proxy est opérationnel.

Si le mot de passe contient les caractères @, : ou /, il faut les encoder : @ devient %40, le deux-points devient %3A, le slash devient %2F. Sinon, la chaîne sera mal interprétée.

Vérification avec curl

1. D'abord, découvrez quelle IP les services externes voient à travers votre proxy. Exécutez : curl -x http://user:pass@proxy-host:8080 https://api.ipify.org. L'adresse IP renvoyée doit différer de votre adresse personnelle ou de celle du serveur.
2. Maintenant, la même requête vers l'API Telegram Bot : curl -x http://user:pass@proxy-host:8080 https://api.telegram.org/bot123456789:AAExampleToken/getMe.
3. Pour SOCKS5, remplacez le paramètre : curl -x socks5h://user:pass@proxy-host:1080 https://api.telegram.org/bot123456789:AAExampleToken/getMe.
4. Mesurez le temps de réponse : ajoutez à la fin de la commande -w " temps : %{time_total}". Une valeur jusqu'à 1-2 secondes pour un proxy mobile est normale.

Vérification : Les deux requêtes ont renvoyé "ok":true, et l'IP de la première commande diffère de la vôtre. Cela signifie que la route via le proxy fonctionne et que l'API Telegram Bot répond par ce chemin.

Configurer le proxy dans Python

Créez un fichier config.py avec le contenu suivant, en remplaçant les valeurs par les vôtres :

import os
TOKEN = os.getenv('BOT_TOKEN', '123456789:AAExampleTokenReplaceMe')
PROXY = os.getenv('BOT_PROXY', 'http://user:pass@proxy-host:8080')
PROXIES = {'http': PROXY, 'https': PROXY}
BASE = f'https://api.telegram.org/bot{TOKEN}'

La clé https dans le dictionnaire est obligatoire, car l'API Telegram Bot fonctionne uniquement en HTTPS. C'est une erreur fréquente des débutants de ne mettre que http et de s'étonner ensuite que le trafic passe en direct.

Maintenant, le script de test check.py :

import requests
from config import PROXIES, BASE
ip = requests.get('https://api.ipify.org', proxies=PROXIES, timeout=15).text
print('IP sortante :', ip)
me = requests.get(f'{BASE}/getMe', proxies=PROXIES, timeout=15).json()
print('Bot :', me['result']['username'])

Lancez : python check.py. L'IP du proxy et le username du bot s'afficheront à l'écran.

Conseil : Si vous ne voulez pas modifier le code d'une bibliothèque que vous utilisez déjà, définissez la variable d'environnement HTTPS_PROXY=http://user:pass@proxy-host:8080. La bibliothèque requests et la plupart des clients HTTP la prennent automatiquement en compte. C'est une façon pratique de migrer un bot existant vers un proxy sans rien modifier.

Configuration dans les frameworks populaires

• aiogram 3.x : créez une session AiohttpSession(proxy='http://user:pass@proxy-host:8080') et passez-la à la création de l'objet Bot(token=TOKEN, session=session). Pour SOCKS5, il faudra le paquet aiohttp-socks.
• python-telegram-bot 21.x : utilisez HTTPXRequest(proxy='http://user:pass@proxy-host:8080') et passez-le dans ApplicationBuilder().token(TOKEN).request(request).
• Node.js : le paquet https-proxy-agent ou socks-proxy-agent crée un agent qui est passé dans les options du client HTTP ou dans le constructeur de la bibliothèque de bot.

Problèmes possibles

• 407 Proxy Authentication Required. Identifiant ou mot de passe incorrect, ou caractères spéciaux non encodés. Vérifiez les données dans votre espace client.
• Connection refused. Port indiqué de manière erronée ou confusion entre les ports HTTP et SOCKS5. Essayez l'autre port.
• La requête passe en direct. Il manque la clé https dans le dictionnaire, ou la variable d'environnement a été définie dans une autre fenêtre de terminal.
• Erreur SSL. Ne désactivez pas la vérification du certificat. Mettez à jour le paquet certifi avec pip install -U certifi et vérifiez l'heure du système.

Étape 3 : lancer le long polling via un proxy

Objectif : obtenir un bot fonctionnel qui, via le proxy, récupère les mises à jour avec getUpdates et répond aux messages sans en perdre ni en dupliquer.

Comment bien construire une boucle de polling

La logique est simple, mais les détails comptent. Vous appelez getUpdates avec le paramètre offset égal au dernier update_id traité plus un. Telegram comprend alors que les mises à jour précédentes ont été reçues et les supprime de son côté. Si vous oubliez l'offset, le même message reviendra sans cesse et le bot répondra plusieurs fois.

Le paramètre timeout définit combien de secondes le serveur garde la connexion ouverte en attendant des événements. C'est là que commence la spécificité du proxy. Tout proxy a son propre timeout d'inactivité, souvent autour de 60-120 secondes pour les proxys mobiles. Si le timeout du polling est plus élevé, le proxy coupera la connexion avant que Telegram ne réponde, et vous obtiendrez une erreur au lieu des mises à jour. Une valeur sûre est timeout=50 avec un timeout du client HTTP à 60 secondes. Le timeout du client doit toujours être supérieur à celui du polling, sinon le client décrochera le premier.

Écrivons le bot

1. Créez un fichier polling.py.
2. Copiez le code ci-dessous.
3. Lancez-le avec la commande python polling.py.
4. Envoyez n'importe quel message au bot dans Telegram.

import time, requests
from config import PROXIES, BASE
offset = 0
print('Polling lancé via le proxy')
while True:
try:
r = requests.get(f'{BASE}/getUpdates', params={'offset': offset, 'timeout': 50}, proxies=PROXIES, timeout=60)
data = r.json()
except requests.RequestException as e:
print('Erreur réseau :', e)
time.sleep(3)
continue
if not data.get('ok'):
print('Erreur API :', data)
time.sleep(3)
continue
for upd in data['result']:
offset = upd['update_id'] + 1
msg = upd.get('message')
if msg and 'text' in msg:
requests.post(f'{BASE}/sendMessage', json={'chat_id': msg['chat']['id'], 'text': 'Reçu : ' + msg['text']}, proxies=PROXIES, timeout=15)

Analysons ce qui se passe. La boucle externe ne se termine jamais seule. Le bloc try intercepte les erreurs réseau : coupure du proxy, timeout, changement d'IP. En cas d'erreur, le script attend trois secondes et réessaie au lieu de planter. La vérification data.get('ok') attrape les erreurs au niveau de l'API. La boucle interne traite chaque mise à jour et décale immédiatement l'offset.

Vérification : La ligne de démarrage est apparue dans la console, et après l'envoi d'un message, le bot a répondu « Reçu : votre texte ». Envoyez trois messages d'affilée, le bot doit répondre exactement une fois à chacun. Arrêtez le script avec Ctrl+C, envoyez un message, relancez-le : le bot répondra au message manqué, car Telegram conserve les mises à jour non traitées pendant 24 heures.

Particularités des proxys mobiles en polling

Les proxys mobiles savent changer d'adresse IP : selon un minuteur ou via un lien spécial depuis l'espace client. Au moment du changement d'IP, la connexion de polling ouverte se rompt. Ce n'est pas une erreur de votre code, c'est le comportement normal du réseau. Notre boucle y est déjà préparée : elle interceptera l'exception, attendra et reprendra au même offset. Aucune mise à jour ne sera perdue.

Néanmoins, une rotation fréquente crée du bruit inutile dans les logs et des micro-retards. Recommandation : pour un bot en polling, réglez l'intervalle de rotation à 10 minutes minimum, ou désactivez le changement automatique et changez l'IP via un lien uniquement quand c'est vraiment nécessaire. Un bot n'est pas un scraper, il n'a pas besoin d'une adresse fraîche chaque minute.

Conseil : Ajoutez l'heure et l'update_id de chaque mise à jour dans le log. Quand, une semaine plus tard, quelqu'un dira que le bot n'a pas répondu, vous retrouverez en une minute si le message est arrivé à votre code ou si le problème venait du réseau.

Problèmes possibles

• Erreur 409 Conflict. La plus fréquente. Un webhook est installé pour le bot, or polling et webhook ne peuvent pas fonctionner simultanément. Exécutez curl -x votre_proxy https://api.telegram.org/botTOKEN/deleteWebhook et relancez le script. Deuxième cause : deux copies du script tournent, fermez la superflue.
• Le bot répond deux fois à chaque message. L'offset ne se décale pas, ou deux copies du bot tournent.
• Read timed out en permanence. Le timeout du polling est supérieur à celui du proxy. Réduisez timeout à 30-40 secondes.
• Délai de réponse de 5-10 secondes. Vérifiez le temps de réponse du proxy avec curl. Si le canal lui-même est lent, changez de point de sortie ou de forfait.

Étape 4 : configurer un webhook avec HTTPS et token secret

Objectif : Telegram envoie lui-même les mises à jour sur votre serveur, et le bot répond via le proxy. Cette étape nécessite un VPS avec un domaine, donc si vous n'avez pour l'instant que le polling et qu'il vous convient, vous pouvez passer à l'étape 5 et revenir ici plus tard.

Préparation du serveur et du domaine

1. Louez un VPS sous Ubuntu. Notez son IP publique.
2. Dans le panneau de gestion du domaine, créez un enregistrement A, par exemple bot.example.com, pointant vers l'IP du serveur. Attendez la mise à jour DNS, généralement 5 à 30 minutes. Vérifiez avec la commande nslookup bot.example.com.
3. Connectez-vous au serveur en SSH et mettez à jour les paquets : sudo apt update.
4. Installez nginx et certbot : sudo apt install nginx certbot python3-certbot-nginx.
5. Ouvrez les ports 80 et 443 : sudo ufw allow 80, sudo ufw allow 443.
6. Obtenez un certificat gratuit : sudo certbot --nginx -d bot.example.com. Suivez les indications, saisissez un email, acceptez les conditions. En une minute, le certificat sera émis.

Telegram n'accepte les webhooks qu'en HTTPS avec un certificat valide émis par une autorité de confiance. Le certificat de certbot répond à cette exigence. Un certificat auto-signé est aussi possible, mais il faudra alors télécharger sa partie publique via le paramètre certificate de setWebhook, ce qui ajoute des complications. Pour les débutants, certbot est plus simple.

Configurer nginx comme point d'entrée

Nginx recevra les requêtes HTTPS de Telegram et les transmettra à votre application Flask, qui écoute sur le port local 8080. Ouvrez la configuration du site créée par certbot avec sudo nano /etc/nginx/sites-available/default et ajoutez dans le bloc server avec le port 443 ce location :

location /tg/webhook {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_read_timeout 30s;
}

Enregistrez le fichier, vérifiez la syntaxe sudo nginx -t et rechargez sudo systemctl reload nginx.

Conseil : Rendez le chemin du webhook moins évident, par exemple /tg/webhook/k8s7d2f. Ce n'est pas un substitut au token secret, mais une couche supplémentaire : les scanners aléatoires ne trouveront pas votre point d'entrée.

Écrivons le gestionnaire de webhook

Créez sur le serveur un fichier webhook.py. Il reçoit le POST de Telegram, vérifie l'en-tête secret et répond à l'utilisateur via le proxy. La fonction call sera écrite à l'étape suivante ; pour l'instant, utilisez un requests.post classique avec proxies.

import requests
from flask import Flask, request, abort
from config import PROXIES, BASE
app = Flask(__name__)
SECRET = 'MySecret123'
@app.post('/tg/webhook')
def webhook():
if request.headers.get('X-Telegram-Bot-Api-Secret-Token') != SECRET:
abort(403)
update = request.get_json(silent=True) or {}
msg = update.get('message')
if msg and 'text' in msg:
requests.post(f'{BASE}/sendMessage', json={'chat_id': msg['chat']['id'], 'text': 'Reçu via webhook'}, proxies=PROXIES, timeout=15)
return 'ok', 200
if __name__ == '__main__':
app.run(host='127.0.0.1', port=8080)

Point clé : l'en-tête X-Telegram-Bot-Api-Secret-Token. Telegram l'ajoute à chaque requête si vous avez indiqué secret_token lors de l'installation du webhook. Toute requête sans la bonne valeur est rejetée avec le code 403. Ainsi, personne d'extérieur ne pourra glisser de faux messages au bot.

Lancez l'application : python webhook.py. Pour un fonctionnement permanent, vous en ferez plus tard un service systemd, mais pour les tests un lancement direct suffit.

Enregistrer le webhook via le proxy

L'appel à setWebhook passe lui aussi par le proxy, car c'est une requête sortante vers l'API Telegram Bot. Exécutez-le sur n'importe quelle machine ayant accès au proxy :

curl -x http://user:pass@proxy-host:8080 -F "url=https://bot.example.com/tg/webhook" -F "secret_token=MySecret123" -F "max_connections=40" -F "drop_pending_updates=true" https://api.telegram.org/bot123456789:AAExampleToken/setWebhook

Décortiquons les paramètres. url — l'adresse de votre gestionnaire. secret_token — une chaîne de 1 à 256 caractères composée de lettres latines, chiffres, tirets et underscores ; elle doit correspondre à SECRET dans le code. max_connections — combien de requêtes simultanées Telegram peut vous ouvrir, de 1 à 100, par défaut 40. drop_pending_updates — réinitialiser les mises à jour accumulées, pour que le bot ne déverse pas une vague de vieilles réponses au moment du basculement.

Réponse attendue : {"ok":true,"result":true,"description":"Webhook was set"}.

Diagnostic via getWebhookInfo

C'est l'outil principal de débogage des webhooks. Exécutez :

curl -x http://user:pass@proxy-host:8080 https://api.telegram.org/bot123456789:AAExampleToken/getWebhookInfo

Dans la réponse, regardez les champs : url doit correspondre au vôtre, pending_update_count indique la file de mises à jour non traitées, last_error_date et last_error_message apparaissent si Telegram n'a pas pu livrer une mise à jour. Un champ d'erreur vide après l'envoi d'un message test signifie un succès complet.

Vérification : Écrivez au bot. Il a répondu « Reçu via webhook ». Dans getWebhookInfo, il n'y a pas de last_error_message, et pending_update_count est à zéro. Dans les logs Flask, une ligne POST /tg/webhook avec le code 200 est visible.

Attention : Le gestionnaire de webhook doit répondre rapidement, en quelques secondes. Si votre code réfléchit trop longtemps, par exemple en faisant une requête lourde à une base de données ou à un service externe via un proxy lent, Telegram considérera la livraison comme échouée et la répétera. Déportez le travail lourd dans une tâche en arrière-plan et renvoyez 200 au webhook tout de suite.

Problèmes possibles

• last_error_message: SSL error. Le certificat n'est pas valide, a expiré ou a été émis pour un autre domaine. Vérifiez sudo certbot certificates.
• Connection timed out. Le port 443 est fermé dans le pare-feu ou chez l'hébergeur. Vérifiez sudo ufw status et les réglages dans le panneau du VPS.
• Wrong response from the webhook: 403. Le token secret dans le code et dans setWebhook ne correspondent pas. Vérifiez la casse des lettres.
• Wrong response from the webhook: 502. Flask n'est pas lancé ou écoute sur un autre port. Vérifiez ss -tlnp | grep 8080.
• Bad webhook: port not allowed. Utilisez uniquement 443, 80, 88 ou 8443.

Étape 5 : gérer l'erreur 429 et rendre les requêtes robustes

Objectif : écrire une fonction unique pour tous les appels à l'API Telegram Bot, qui gère elle-même la pause en cas de 429, réessaie en cas de panne réseau ou de proxy, et ne fait jamais planter le bot.

Pourquoi on ne peut pas ignorer le 429

Quand vous envoyez une campagne à mille utilisateurs, la limite de 30 messages par seconde est atteinte instantanément. Telegram répond 429 et indique retry_after. Si vous continuez à bombarder le serveur, les messages ne partiront pas, et le temps d'attente dans les réponses suivantes augmentera. Avec un proxy, il y a une nuance : les limites Telegram sont liées au bot, pas à l'IP. Changer d'IP par rotation n'aidera pas à contourner la limite et ne doit pas être utilisé pour cela. La seule voie correcte est de respecter retry_after et de contrôler la vitesse d'envoi.

Écrivons une enveloppe universelle

Ajoutez dans le fichier config.py ou dans un api.py séparé la fonction suivante :

import time, requests
from config import PROXIES, BASE
def call(method, payload, retries=6):
for attempt in range(retries):
try:
r = requests.post(f'{BASE}/{method}', json=payload, proxies=PROXIES, timeout=15)
except requests.RequestException as e:
print('Réseau ou proxy :', e)
time.sleep(min(2 ** attempt, 30))
continue
if r.status_code == 429:
wait = r.json().get('parameters', {}).get('retry_after', 1)
print('429 Too Many Requests, attente', wait, 'sec')
time.sleep(wait + 0.5)
continue
if 500 <= r.status_code < 600:
print('Erreur serveur Telegram', r.status_code)
time.sleep(min(2 ** attempt, 30))
continue
data = r.json()
if not data.get('ok'):
print('Erreur API :', data.get('description'))
return data
raise RuntimeError('Telegram Bot API : tentatives épuisées pour ' + method)

Ce que fait cette fonction. En cas d'erreur réseau, elle attend de manière exponentielle : 1, 2, 4, 8 secondes, mais pas plus de 30. Ainsi, le bot survit à un changement d'IP sur le proxy ou à une courte panne du canal. En cas de 429, elle lit retry_after, ajoute une demi-seconde de marge et réessaie. En cas d'erreurs 5xx côté Telegram, elle réessaie aussi avec une pause. En cas d'erreurs 400 ou 403, par exemple si l'utilisateur a bloqué le bot, réessayer est inutile, donc la fonction renvoie la réponse telle quelle, et vous décidez quoi faire ensuite.

Limitons la vitesse à l'avance

Mieux vaut ne pas déclencher de 429 du tout. Pour les campagnes, ajoutez une pause entre les messages. La variante la plus simple : time.sleep(0.05) après chaque envoi donne 20 messages par seconde, ce qui est sous la limite globale. Pour un même chat, gardez une pause d'au moins une seconde. Pour les groupes, pas plus de 20 messages par minute.

def broadcast(chat_ids, text):
sent, failed = 0, 0
for cid in chat_ids:
res = call('sendMessage', {'chat_id': cid, 'text': text})
if res.get('ok'):
sent += 1
else:
failed += 1
time.sleep(0.05)
print('Envoyés :', sent, 'Erreurs :', failed)

Conseil : Enregistrez les réponses d'erreur 403 Forbidden: bot was blocked by the user. Supprimez ces utilisateurs de la base de diffusion. Cela réduira la charge et évitera des limites inutiles, car les requêtes échouées comptent aussi.

Testons la gestion du 429

1. Créez un groupe de test et ajoutez-y le bot.
2. Lancez une boucle de 40 appels call('sendMessage', {...}) dans ce chat sans pauses.
3. Observez la console : après quelques envois rapides, une ligne sur le 429 et le temps d'attente apparaîtra.
4. Vérifiez qu'après la pause, l'envoi a repris et que les 40 messages sont bien arrivés.

Vérification : Tous les messages ont été livrés, le bot n'a pas planté avec une exception, et les pauses retry_after sont visibles dans le log. Remplacez requests.post dans polling.py et webhook.py par la fonction call, pour que tout le travail avec l'API Telegram Bot passe par un canal unique et protégé.

Problèmes possibles

• retry_after énorme, des centaines de secondes. Vous avez ignoré la limite trop longtemps. Arrêtez complètement l'envoi, attendez le temps indiqué et réduisez le rythme.
• Le 429 arrive dès les premiers messages. Un autre processus utilise le même token. Vérifiez qu'une ancienne version du bot ne tourne pas.
• Réponse non JSON en cas de 429. Certains proxys renvoient leur propre page HTML d'erreur. Entourez r.json() d'un try et, en cas d'échec, attendez 5 secondes fixes.

Étape 6 : réglages avancés pour les projets à forte charge

Objectif : préparer le bot à la croissance : plusieurs bots via plusieurs proxys, file d'envoi, serveur Bot API local et rotation bien pensée. Les débutants peuvent sauter cette section et y revenir quand les utilisateurs dépasseront le millier.

Plusieurs bots via plusieurs proxys

Les marketeurs gèrent souvent une dizaine de bots pour différents projets depuis un seul serveur. La bonne architecture : pour chaque bot, son propre dictionnaire proxies et sa propre session requests.Session(). Une session réutilise les connexions TCP, ce qui réduit la charge sur le proxy et accélère les requêtes de 2 à 3 fois. Stockez la configuration sous forme de liste : token, adresse du proxy, mode de réception des mises à jour. Un processus par bot est plus simple à déboguer qu'un processus pour tout.

Une file d'envoi au lieu d'appels directs

Pour les campagnes de plus de 10 000 utilisateurs, les appels directs depuis le code principal cessent de fonctionner. Mettez en place une file : Redis ou au moins une table en base avec les champs chat_id, text, status, attempts. Un worker séparé récupère les tâches et appelle la fonction call en contrôlant la vitesse. En cas de 429, le worker dort au lieu de bloquer la réception des webhooks. Ainsi, le bot continue de répondre aux commandes des utilisateurs pendant que la campagne se déroule en arrière-plan. En 2026, l'API Telegram Bot permet aux bots payants, via le paramètre allow_paid_broadcast, d'augmenter la limite jusqu'à 1000 messages par seconde, mais cela consomme des Stars, donc pour la plupart des projets, une file à 20-25 messages par seconde reste la meilleure option.

Serveur Bot API local

Telegram publie les sources du serveur Bot API, que l'on peut lancer chez soi. Votre code s'adresse alors non pas à api.telegram.org, mais à localhost, et le serveur local communique avec Telegram. Avantages : téléchargement de fichiers jusqu'à 2 Go au lieu de 50 Mo, webhooks sur n'importe quel port et sans HTTPS à l'intérieur de votre réseau, levée de certaines limites. Inconvénient : le proxy devra être configuré au niveau du serveur local lui-même, et non dans le code du bot. Variante pour les équipes avec des compétences DevOps, inutile pour démarrer.

Rotation d'IP et webhooks

Avec les webhooks, la rotation d'IP sur le proxy est presque invisible : chaque appel sendMessage est court, et une coupure de connexion au moment du changement n'affectera au maximum qu'une requête, que l'enveloppe call répétera. Donc pour les webhooks, une rotation plus fréquente que pour le polling est acceptable. Néanmoins, il n'y a pas d'intérêt à changer souvent : l'API Telegram Bot ne limite pas les requêtes par IP, et les limites sont liées au token. Réglez la rotation pour des raisons liées à votre infrastructure, pas pour l'API.

Surveillance de la santé sans système dédié

L'ensemble minimal à mettre en place tout de suite : une fois par minute, appelez getWebhookInfo et écrivez dans le log pending_update_count et last_error_message. Si la file grandit sur trois mesures consécutives, votre gestionnaire ne suit pas. Pour le polling, enregistrez l'heure du dernier getUpdates réussi : si plus de deux minutes se sont écoulées, la connexion est bloquée, redémarrez le processus. Cela suffit pour être informé des problèmes avant les clients.

Conseil : Loggez non seulement les erreurs, mais aussi le temps de chaque requête vers l'API Telegram Bot via le proxy. Une lente augmentation du temps de réponse moyen de 0,3 à 2 secondes vous préviendra d'une dégradation du canal des jours avant que le bot ne commence à perdre des messages.

Vérification du résultat : checklist d'une solution prête

Parcourez la liste. Chaque point doit être coché, alors seulement le bot sera considéré comme prêt pour de vrais utilisateurs.

Checklist

• La commande curl avec le paramètre -x via le proxy renvoie "ok":true sur la méthode getMe.
• Le script check.py affiche l'IP du proxy, et non la vôtre.
• Le polling répond une seule fois à un message, sans doublon.
• Après un arrêt et un redémarrage du polling, les messages manqués sont traités.
• Lors d'un changement d'IP forcé sur le proxy, le polling se rétablit seul en 3 à 5 secondes.
• Webhook : getWebhookInfo affiche votre url, un pending_update_count à zéro et un last_error_message vide.
• Une requête vers le webhook sans l'en-tête secret reçoit un 403.
• L'envoi rapide de 40 messages dans un même chat passe sans plantage, et les pauses retry_after sont visibles dans le log.
• Le token et les données du proxy sont dans .env, pas dans le code.

Comment tester de bout en bout

1. Lancez le bot dans le mode choisi.
2. Écrivez-lui depuis trois comptes différents, deux messages chacun.
3. Vérifiez les six réponses, une par message.
4. Cliquez dans l'espace client du proxy sur le lien de changement d'IP et envoyez immédiatement un autre message.
5. Le bot doit répondre en moins de 10 secondes.
6. Lancez le test de 429 de l'étape 5.
7. Vérifiez les logs : aucune exception non gérée ni trace d'erreur.

Indicateurs de succès

Temps de réponse du bot à un message inférieur à 2 secondes. Part de requêtes échouées vers l'API Telegram Bot après tous les essais inférieure à 0,1 %. Aucun doublon en 24 heures. Le pending_update_count dans getWebhookInfo ne dépasse pas dix aux heures de pointe. Si les indicateurs correspondent, félicitations : vous avez construit un schéma fiable qui tiendra de longs mois.

Erreurs courantes et leurs solutions

Erreur 409 Conflict lors de getUpdates

Cause : un webhook est installé pour le bot, ou deux instances de polling tournent. Solution : appeler deleteWebhook via le proxy, vérifier qu'un seul processus tourne. Vérifiez avec la commande ps aux | grep polling.

Le bot répond deux fois à chaque message

Cause : l'offset n'augmente pas, ou deux copies du bot tournent sur des serveurs différents avec le même token. Solution : vérifiez la ligne offset = update_id + 1, arrêtez les copies superflues. Pour le webhook, assurez-vous que nginx ne duplique pas les requêtes vers deux backends.

Erreur 407 Proxy Authentication Required

Cause : identifiants de proxy incorrects ou caractères spéciaux non encodés dans le mot de passe. Solution : revérifiez l'identifiant et le mot de passe dans l'espace client, encodez @, : et / dans le mot de passe, essayez l'authentification par IP si elle est disponible dans votre forfait.

Read timed out toutes les 50-60 secondes

Cause : le timeout du polling est supérieur ou égal au timeout d'inactivité du proxy. Solution : réduisez timeout dans getUpdates à 30-40 secondes, et gardez le timeout du client 10 secondes au-dessus.

Le webhook est installé mais les mises à jour n'arrivent pas

Cause : le port est fermé, le certificat est invalide ou le gestionnaire ne répond pas 200. Solution : regardez last_error_message dans getWebhookInfo, c'est un diagnostic précis. Vérifiez curl -I https://bot.example.com/tg/webhook depuis un autre ordinateur.

Wrong response from the webhook: 403 Forbidden

Cause : le token secret dans le code diffère de celui transmis à setWebhook. Solution : réinstallez le webhook avec la même valeur que dans le code. Rappelez-vous que setWebhook avec de nouveaux paramètres remplace entièrement les précédents.

429 constants sous faible charge

Cause : le bot envoie dans un même chat plus d'une fois par seconde, par exemple plusieurs messages d'affilée en réponse à une commande. Solution : regroupez les réponses en un seul message, utilisez editMessageText plutôt que de nouveaux messages pour la progression, ajoutez une pause entre les envois vers un même chat_id.

Le trafic passe en direct, en contournant le proxy

Cause : le dictionnaire proxies n'a pas la clé https, la variable d'environnement n'est pas visible par le processus, le framework n'a pas pris en compte le réglage. Solution : vérifiez l'IP sortante avec une requête vers api.ipify.org dans le même code que celui qui envoie les messages. Ne faites pas de suppositions, vérifiez concrètement.

SSL: CERTIFICATE_VERIFY_FAILED lors de requêtes via proxy

Cause : jeu de certificats racine obsolète ou heure système incorrecte. Solution : mettez à jour certifi, synchronisez l'heure. Ne désactivez jamais la vérification des certificats avec le paramètre verify=False : cela ouvre la possibilité de substituer le trafic contenant le token.

FAQ : questions fréquentes sur la configuration

Que choisir pour commencer : polling ou webhook ?

Le polling. Il fonctionne de partout, ne nécessite ni domaine ni certificat, et on peut passer au webhook plus tard en une heure. Le webhook a du sens quand le bot sert des milliers d'utilisateurs ou tourne sur un serveur où HTTPS est déjà présent.

Peut-on utiliser un seul proxy pour plusieurs bots ?

Oui. Les limites de l'API Telegram Bot sont liées au token du bot, pas à l'IP. Dix bots via un seul proxy ne se gênent pas du point de vue de l'API. La seule contrainte est la bande passante du proxy lui-même, largement suffisante pour des bots textuels.

Faut-il faire passer par le proxy à la fois le webhook et les réponses ?

Les requêtes entrantes du webhook arrivent directement sur votre serveur, il est par définition impossible de les faire passer par un proxy. Seuls les appels sortants passent par le proxy : sendMessage, setWebhook, getFile et les autres méthodes. C'est le schéma normal et le seul possible.

Comment savoir que les requêtes passent bien par le proxy ?

Dans le même code, interrogez https://api.ipify.org avec les mêmes réglages proxies et comparez avec votre IP réelle. En complément, consultez les statistiques de trafic dans l'espace client du proxy : le compteur doit augmenter pendant que le bot fonctionne.

Que faire si l'IP du proxy change pendant que le bot tourne ?

Rien, si vous avez utilisé le code de ce guide. Le polling interceptera la coupure de connexion et reprendra à l'offset enregistré. La fonction call répétera la requête échouée. Seule recommandation : ne pas régler une rotation plus fréquente que toutes les quelques minutes pour le mode polling.

SOCKS5 ou proxy HTTP pour l'API Telegram Bot ?

La différence pour un bot est presque nulle, les deux fonctionnent. Le proxy HTTP est plus simple à configurer et pris en charge par tous les clients sans paquets supplémentaires. SOCKS5 est plus pratique quand on veut garantir la résolution DNS côté proxy via le schéma socks5h. Choisissez ce que vous utilisez déjà dans d'autres projets.

Combien de messages peut-on envoyer sans recevoir de 429 ?

Tenez-vous à ces repères : jusqu'à 1 message par seconde dans un chat privé, jusqu'à 20 par minute dans un groupe, jusqu'à 25-30 par seconde au total. Pour les campagnes massives, prévoyez 20 messages par seconde et gérez impérativement retry_after, car les limites peuvent temporairement baisser en cas de forte charge sur Telegram.

Comment migrer en toute sécurité un bot déjà en production vers un proxy ?

Vérifiez d'abord le proxy avec curl sur getMe. Ajoutez ensuite la variable HTTPS_PROXY ou configurez proxies dans le code, lancez le bot avec un token de test. Ce n'est qu'après des vérifications réussies que vous basculerez le token de production. Gardez l'ancienne configuration sous la main pour un retour en arrière.

Comment annuler le webhook et revenir au polling ?

Un appel à deleteWebhook via le proxy. Si vous voulez conserver les mises à jour accumulées pour le polling, ne passez pas drop_pending_updates. Ensuite, lancez polling.py et le bot reprendra la file.

Peut-on définir plusieurs URL de webhook pour un même bot ?

Non, un bot a exactement un webhook. Si vous devez répartir la charge, placez derrière l'URL unique un équilibreur nginx qui distribue les requêtes sur plusieurs instances de l'application. Pour Telegram, cela ressemble à un seul point d'entrée.

Conclusion

Résumons le travail accompli. Vous avez créé un bot et obtenu un token, appris à vérifier le proxy avec curl et Python, et confirmé que le trafic vers l'API Telegram Bot passe par le bon chemin. Vous avez construit une boucle de long polling robuste, qui survit aux changements d'IP et ne duplique pas les messages. Vous avez mis en place un webhook avec un vrai certificat HTTPS et l'avez protégé par un token secret. Et le plus précieux : vous avez écrit une fonction unique qui respecte retry_after en cas de 429, répète les requêtes en cas de panne réseau et transforme un canal capricieux en lien fiable.

Que faire ensuite. Transformez le bot en service systemd pour qu'il redémarre après un redémarrage du serveur. Placez les tokens et les adresses de proxy dans des variables d'environnement sur la machine de production. Ajoutez un log simple des temps de réponse et consultez-le une fois par semaine. Si les utilisateurs deviennent nombreux, passez à la file d'envoi de la section avancée.

Vers quoi évoluer. Étudiez les méthodes de l'API Telegram Bot pour les boutons inline, les paiements et les mini-applications ; elles ouvrent aux bots des scénarios entièrement nouveaux pour le marketing et la vente. Maîtrisez les frameworks asynchrones aiogram ou python-telegram-bot ; ils prendront en charge la routine du polling et des répétitions, et vous comprenez déjà ce qui se passe sous le capot. Et surtout : n'ayez pas peur d'expérimenter sur un bot de test. Chaque erreur 429 ou 409 que vous avez attrapée et corrigée vous-même vous rend plus fort que n'importe quel modèle prêt à l'emploi. Vous allez y arriver.