Comment programmer l'envoi de messages avec l'API Telegram Bot ?
Apprenez à programmer l'envoi de messages avec l'API Telegram Bot : configuration, envoi simple, médias, planification et bonnes pratiques. Tutoriel complet 2026.
Introduction : programmer l'envoi de messages avec l'API Telegram Bot
L'API Bot de Telegram offre aux développeurs un moyen puissant d'automatiser l'envoi de messages. Que vous souhaitiez notifier des utilisateurs, diffuser des informations ou intégrer un chatbot, maîtriser l'envoi de messages via l'API Telegram Bot est une compétence fondamentale. Cet article vous guide pas à pas, de la création d'un bot à l'envoi de messages textuels, médias et programmés, en respectant les bonnes pratiques et en évitant les pièges courants. Nous aborderons également les limites et les alternatives pour une exploitation fiable. Pour les développeurs, comprendre ces mécanismes permet de délivrer des notifications en temps réel, que ce soit pour des alertes système ou des campagnes marketing.
Prérequis techniques
Avant de pouvoir envoyer le moindre message, vous devez disposer d'un bot Telegram et de son token d'authentification. La création d'un bot se fait via le BotFather, le bot officiel de gestion des bots. Ouvrez une conversation avec @BotFather sur Telegram et envoyez la commande /newbot. Suivez les instructions pour choisir un nom et un username (qui doit se terminer par bot). Une fois créé, vous recevrez un token HTTP API, par exemple 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Ce token est votre identifiant unique pour interagir avec l'API.
Conservez ce token en sécurité : toute personne qui le possède peut contrôler votre bot. Ne le partagez jamais publiquement, et utilisez de préférence des variables d'environnement dans votre code. Exemple : stockez-le dans un fichier .env avec TELEGRAM_BOT_TOKEN='votre_token' et accédez-y via os.getenv('TELEGRAM_BOT_TOKEN').
Envoi d'un message texte simple
L'endpoint fondamental pour envoyer un message texte est sendMessage. Il s'agit d'une requête POST (ou GET) à l'URL : https://api.telegram.org/bot<TOKEN>/sendMessage. Les paramètres obligatoires sont chat_id (l'identifiant de la conversation destinataire) et text (le contenu du message).
Pour obtenir le chat_id, vous pouvez envoyer un message à votre bot depuis un compte utilisateur, puis interroger l'endpoint getUpdates. Par exemple, avec curl (en remplaçant <TOKEN> et <CHAT_ID> par vos valeurs) :
curl -X POST https://api.telegram.org/bot<TOKEN>/sendMessage -d chat_id=<CHAT_ID> -d text="Bonjour depuis mon bot !"
La réponse de l'API est un objet JSON contenant le message envoyé. Vous pouvez également utiliser des bibliothèques comme python-telegram-bot (Python) ou node-telegram-bot-api (Node.js). Exemple en Python avec gestion des erreurs :
import requests
TOKEN = "votre_token"
CHAT_ID = "123456789"
url = f"https://api.telegram.org/bot{TOKEN}/sendMessage"
data = {"chat_id": CHAT_ID, "text": "Bonjour depuis mon bot !"}
try:
response = requests.post(url, data=data)
response.raise_for_status()
except requests.exceptions.RequestException as e:
print(f"Erreur : {e}")
Pourquoi utiliser POST plutôt que GET ?
POST est recommandé pour éviter d'exposer les paramètres dans l'URL (notamment le token) et pour supporter des payloads plus longs. GET fonctionne mais est moins sécurisé et peut être limité en taille de requête.
Envoi de messages avec mise en forme
L'API Telegram Bot permet d'envoyer des messages formatés en Markdown ou HTML. Pour cela, ajoutez le paramètre parse_mode avec la valeur MarkdownV2 ou HTML. Attention : les caractères spéciaux doivent être échappés. Exemple avec HTML :
curl -X POST https://api.telegram.org/bot<TOKEN>/sendMessage \ -d chat_id=<CHAT_ID> \ -d text="<b>Gras</b> et <i>italique</i>" \ -d parse_mode="HTML"
Avec MarkdownV2, utilisez *gras* _italique_ mais échappez les caractères comme _, *, [, etc. avec un backslash. Exemple : pour envoyer _important_, écrivez \_important\_. L'échappement est source d'erreurs fréquentes ; testez toujours avec un message de débogage.
Envoi de médias (photos, documents, vidéos)
Au-delà du texte, votre bot peut envoyer des photos (sendPhoto), des documents (sendDocument), des vidéos (sendVideo), de l'audio, etc. Chaque endpoint nécessite un fichier, soit en l'uploadant directement (multipart/form-data), soit en fournissant un file_id d'un fichier déjà envoyé sur Telegram.
Exemple d'envoi d'une photo avec curl :
curl -X POST https://api.telegram.org/bot<TOKEN>/sendPhoto \ -F chat_id=<CHAT_ID> \ -F photo=@/chemin/vers/image.jpg \ -F caption="Légende de la photo"
L'utilisation de file_id est plus performante si le fichier a déjà été téléchargé sur Telegram (par exemple, via un autre bot). Le file_id est valide pour le même bot. Pour envoyer un document, remplacez photo par document. Exemple : après avoir reçu une photo via getUpdates, utilisez son file_id pour l'envoyer à nouveau.
Programmation d'envois différés
L'API Telegram Bot ne possède pas de fonctionnalité native de planification d'envoi. Pour programmer l'envoi d'un message à une date ultérieure, vous devez mettre en place un mécanisme externe : un serveur qui exécute des tâches planifiées (cron, systemd timer, ou un service comme AWS Lambda ou Google Cloud Scheduler).
Par exemple, vous pouvez écrire un script Python qui utilise la bibliothèque schedule ou APScheduler pour déclencher l'envoi à un moment précis. Exemple avec APScheduler :
from apscheduler.schedulers.background import BackgroundScheduler
import requests
def send_message():
requests.post(f"https://api.telegram.org/bot{TOKEN}/sendMessage", data={"chat_id": CHAT_ID, "text": "Message programmé"})
scheduler = BackgroundScheduler()
scheduler.add_job(send_message, 'date', run_date='2023-12-31 23:59:00')
scheduler.start()
L'important est que votre bot soit en ligne (via long polling ou webhook) au moment de l'envoi, ou que le planificateur appelle directement l'API.
Avertissement
Ne confiez pas la planification à un bot client qui se déconnecte. Utilisez un service dédié avec une disponibilité garantie. Les bots Telegram ne doivent pas stocker de tâches planifiées en mémoire ; préférez une base de données pour la persistance.
Gestion des erreurs et limites de débit
L'API impose des rate limits pour éviter les abus. En cas de dépassement, vous recevrez une réponse HTTP 429 avec un en-tête retry-after. Votre code doit implémenter un backoff exponentiel et respecter les limites. Exemple : attendez retry-after secondes avant de réessayer, puis doublez le délai à chaque échec. Par ailleurs, des erreurs comme chat not found (chat_id invalide) ou bot was blocked by the user doivent être gérées.
Conseil pratique : loggez toutes les réponses d'erreur et les paramètres de la requête pour faciliter le débogage. Utilisez des try/except dans vos scripts et capturez les exceptions spécifiques à l'API.
Bonnes pratiques de sécurité et de fiabilité
- Ne stockez jamais le token en clair dans le code ; utilisez des variables d'environnement.
- Limitez les commandes du bot aux administrateurs si nécessaire (via la liste des utilisateurs autorisés).
- Pour les envois en masse, respectez une cadence raisonnable (20 messages par seconde environ, selon la documentation).
- Implémentez une file d'attente et un mécanisme de retry pour les échecs temporaires.
- Utilisez les webhooks plutôt que le long polling pour une réactivité optimale, en configurant un certificat SSL valide.
Ces pratiques garantissent un fonctionnement fiable et sécurisé de votre bot, même en production.
Dépannage courant
Le bot n'envoie pas de message
Vérifiez d'abord que le token est correct. Testez avec getMe : curl https://api.telegram.org/bot<TOKEN>/getMe. Si cela fonctionne, le problème vient probablement du chat_id. Assurez-vous que l'utilisateur a bien démarré une conversation avec le bot (envoi de /start). Sinon, le bot ne peut pas envoyer de message à cet utilisateur (sauf si le chat est un groupe où le bot est administrateur).
Erreur 400 Bad Request
Cela indique souvent un paramètre manquant ou mal formaté. Vérifiez le format du chat_id (doit être un entier, mais peut être un username précédé de @ pour les groupes), le texte (ne doit pas être vide), ou le parse_mode (valeurs autorisées). Exemple : un chat_id de groupe commence généralement par un signe négatif.
Questions fréquentes
Puis-je programmer un message sans serveur externe ?
Non, l'API Telegram Bot n'offre pas de planification intégrée. Vous devez utiliser un système de tâches planifiées (cron, serveur, fonction cloud).
Comment envoyer un message à un groupe dont je suis administrateur ?
Utilisez l'ID du groupe (négatif pour les supergroupes). Vous pouvez l'obtenir en ajoutant le bot au groupe et en consultant getUpdates. Le bot doit être administrateur pour envoyer des messages si le groupe est privé.
Quelle est la limite de débit de l'API ?
La documentation officielle indique une limite d'environ 30 messages par seconde par chat, et 20 messages par seconde pour les groupes. Ces limites peuvent varier ; respectez les en-têtes retry-after en cas de refus.
Puis-je envoyer un message à un utilisateur qui n'a pas démarré le bot ?
Non, sauf si l'utilisateur est membre d'un groupe où le bot peut envoyer des messages. Le bot ne peut pas initier une conversation privée sans que l'utilisateur ne l'ait d'abord contacté.
Conclusion
L'envoi de messages via l'API Telegram Bot est simple une fois les bases comprises. Retenez les points essentiels : utilisez le bon endpoint, gérez les erreurs, respectez les limites de débit, et pour la planification, passez par un service externe. Avec ces connaissances, vous pouvez construire des bots utiles et fiables. N'oubliez pas de consulter la documentation officielle pour les détails complets.
En regardant vers l'avenir, l'API Telegram Bot continue d'évoluer avec des fonctionnalités comme les boutons inline et les commandes personnalisées. Une observation empirique des mises à jour récentes suggère que la planification native pourrait être envisagée, mais pour l'instant, les solutions externes restent la norme. Restez informé via le canal @BotNews pour les nouveautés.