Comment programmer l'envoi de messages sur Telegram avec l'API Bot ?

Introduction à l'API Bot Telegram

L'API Bot Telegram permet aux développeurs d'automatiser l'envoi de messages, que ce soit pour des notifications, des rappels ou la diffusion d'informations. Contrairement à l'API client, l'API Bot est conçue pour être légère et accessible via HTTP, sans nécessiter de sessions persistantes. Cet article vous guide pas à pas pour programmer l'envoi de messages sur Telegram à l'aide de l'API Bot, en utilisant la dernière version disponible en 2026. Vous apprendrez à créer un bot, récupérer son token, envoyer un message simple, planifier des envois réguliers et appliquer les bonnes pratiques de sécurité et de fiabilité.

Création du bot via @BotFather

La première étape consiste à créer un bot Telegram. Ouvrez Telegram et recherchez @BotFather, le bot officiel de gestion des bots. Envoyez la commande /newbot et suivez les instructions : choisissez un nom (affiché) et un nom d'utilisateur (unique, se terminant par bot). Une fois le bot créé, BotFather vous fournira un token d'accès, une chaîne de caractères unique qui authentifie votre bot. Conservez ce token en lieu sûr – il permet de contrôler entièrement votre bot. Pour vérifier vos bots existants, utilisez la commande /mybots dans @BotFather.

Récupération du token et configuration

Le token ressemble à 1234567890:ABCdefGHIjklmNOPQRstuvWXYZ. Il est essentiel pour toutes les requêtes à l'API. Vous pouvez également consulter la liste de vos bots via /mybots dans @BotFather, puis sélectionner le bot pour voir ou révoquer le token. Notez que si vous révoquez le token, l'ancien cesse immédiatement de fonctionner ; mettez à jour vos scripts en conséquence. Pensez à stocker le token dans une variable d'environnement plutôt que directement dans le code, comme nous le verrons dans la section des bonnes pratiques.

Envoi d'un message simple avec l'API

L'API Bot offre une méthode sendMessage qui accepte entre autres les paramètres chat_id (identifiant du destinataire) et text. Le chat_id peut être l'ID d'un utilisateur, d'un groupe ou d'un canal. Pour obtenir l'ID d'un utilisateur, vous pouvez faire en sorte que l'utilisateur envoie un message à votre bot, puis consulter les mises à jour via getUpdates. Voici un exemple minimal en Python utilisant la bibliothèque requests :

import requests

token = "VOTRE_TOKEN_ICI"
chat_id = "ID_DU_DESTINATAIRE"
message = "Bonjour, ceci est un message automatisé."

url = f"https://api.telegram.org/bot{token}/sendMessage"
payload = {
    "chat_id": chat_id,
    "text": message,
    "parse_mode": "HTML"
}
response = requests.post(url, data=payload)
if response.status_code == 200:
    print("Message envoyé avec succès")
else:
    print(f"Erreur : {response.text}")

L'exemple ci-dessus envoie un message simple. Vous pouvez également utiliser parse_mode pour du formatage basique (HTML ou Markdown) et d'autres paramètres comme disable_web_page_preview ou reply_to_message_id. La réponse de l'API inclut l'objet message envoyé, ce qui permet de confirmer son bon acheminement.

Programmation d'envois planifiés

Pour envoyer des messages à intervalles réguliers, vous pouvez utiliser un planificateur de tâches système. Sur Linux, cron est l'outil standard. Par exemple, pour envoyer un message tous les jours à 8h du matin, créez une tâche cron :

0 8 * * * /usr/bin/python3 /chemin/vers/votre/script.py

Sur Windows, utilisez le Planificateur de tâches. Vous pouvez également envisager des services cloud comme AWS Lambda (avec une fonction déclenchée par cron) ou des bots hébergés sur un serveur VPS. L'essentiel est que le script s'exécute au moment souhaité et appelle l'API. Une autre approche consiste à utiliser une boucle avec time.sleep dans le script lui-même, mais cela nécessite que le processus reste actif en continu.

Scénarios d'utilisation typiques

L'automatisation des messages via l'API Bot convient à de nombreux cas :

Rappels personnels : Envoyer un message quotidien pour prendre un médicament ou boire de l'eau.
Notifications d'événements : Alerter un groupe d'utilisateurs d'une nouvelle publication sur un blog, d'un tweet ou d'un changement de prix.
Diffusion d'actualités : Un bot peut envoyer le bulletin météo tous les matins à une liste de diffusion.
Automatisation de tâches : Intégrer des alertes de monitoring (ex. serveur down, seuil de logs atteint).

Ces exemples montrent la polyvalence de l'API Bot. Dans chaque cas, le script doit être capable de gérer les erreurs, les limites de débit et les changements d'état du chat (comme le blocage du bot par un utilisateur).

Bonnes pratiques

Pour garantir la fiabilité et la sécurité de votre bot, suivez ces recommandations :

Gérez les limites de débit (rate limiting) : L'API Bot impose une limite de 30 messages par seconde par chat. En cas de dépassement, vous recevrez une erreur 429. Implémentez une logique d'attente avec time.sleep ou utilisez des files d'attente.
Ne stockez jamais le token en clair dans le code : Utilisez des variables d'environnement ou un fichier de configuration exclu du contrôle de version.
Vérifiez les erreurs : Un chat_id peut devenir invalide si l'utilisateur bloque le bot. Traitez les réponses HTTP non-200 et réessayez si approprié.
Respectez la vie privée : N'envoyez pas de messages non sollicités à des utilisateurs qui n'ont pas interagi avec votre bot. Les bots ne peuvent pas envoyer de message à un utilisateur qui ne les a pas contactés en premier (sauf dans les groupes ou canaux où le bot est administrateur).

En appliquant ces principes, vous réduisez les risques de blocage de votre bot par Telegram et améliorez l'expérience utilisateur.

Limites de l'API Bot

L'API Bot présente certaines limitations importantes :

Impossible d'initier une conversation avec un utilisateur : Un bot ne peut envoyer un message privé que si l'utilisateur a déjà envoyé un message au bot. Pour les notifications, vous devez d'abord demander aux utilisateurs de démarrer une conversation.
Limite de caractères : Un message texte ne peut dépasser 4096 caractères. Pour des messages plus longs, utilisez le paramètre text avec le mode Markdown ou HTML, mais la limite reste la même. Vous pouvez diviser le message en plusieurs envois.
Pas de programmation intégrée : L'API Bot elle-même ne propose pas de fonctionnalité de planification ; vous devez la mettre en œuvre côté client.

Ces contraintes sont connues et documentées. Les contournements, comme l'utilisation de groupes ou de canaux, permettent de les atténuer dans la plupart des cas d'usage.

Dépannage courant

Voici les problèmes fréquents et leurs solutions :

Symptôme	Cause probable	Solution
Erreur 403 Forbidden	Le bot n'a pas les droits ou le chat_id est invalide	Vérifiez que le bot est administrateur du groupe/canal ou que l'utilisateur a démarré le bot.
Erreur 429 Too Many Requests	Dépassement de la limite de débit	Attendez quelques secondes, puis réessayez. Réduisez la fréquence des envois.
Aucun message reçu	Token incorrect ou chat_id erroné	Vérifiez le token avec une simple requête `getMe`.

Le tableau ci-dessus couvre les erreurs les plus courantes. En cas de problème persistant, consultez la documentation officielle de l'API Bot ou les journaux d'erreur de votre script.

Questions fréquentes

Puis-je envoyer un message à un utilisateur qui n'a jamais parlé à mon bot ?

Non, la politique de Telegram interdit aux bots d'envoyer des messages privés à des utilisateurs qui n'ont pas initié la conversation. Vous pouvez contourner cette limitation en utilisant un canal ou un groupe où le bot est administrateur, ou en demandant aux utilisateurs de s'abonner à un canal.

Comment obtenir le chat_id d'un utilisateur ou d'un groupe ?

Pour un utilisateur, faites-lui envoyer un message à votre bot, puis appelez la méthode getUpdates. Le chat_id apparaît dans le champ message.chat.id. Pour un groupe ou un canal, ajoutez le bot comme administrateur, puis envoyez un message dans celui-ci ; le chat_id sera retourné dans getUpdates.

L'API Bot supporte-t-elle l'envoi de fichiers ou d'images ?

Oui, l'API Bot propose des méthodes comme sendPhoto, sendDocument, sendAudio, etc. Vous pouvez envoyer un fichier directement depuis une URL ou en téléchargeant un fichier local. Les limites de taille sont de 50 MB pour les téléchargements, et les types de fichiers courants (images, PDF, audio) sont bien supportés.

Quelle est la meilleure façon de sécuriser le token ?

Utilisez des variables d'environnement (ex. export BOT_TOKEN=... sous Linux) ou un fichier de configuration .env externe au code source. Ne commitez jamais le token dans un dépôt Git. Si vous utilisez un service cloud, utilisez le gestionnaire de secrets intégré, comme AWS Secrets Manager ou GitHub Secrets.

Conclusion

Programmer l'envoi de messages sur Telegram avec l'API Bot est une tâche simple mais puissante. En combinant la création d'un bot via @BotFather, l'utilisation de l'API HTTP et un planificateur de tâches, vous pouvez automatiser une grande variété de notifications. N'oubliez pas de respecter les limites de débit, de sécuriser votre token et de prendre en compte les restrictions concernant l'initiation des conversations. Avec ces bases, vous êtes prêt à intégrer Telegram dans vos workflows automatisés. Pour explorer davantage, consultez la documentation officielle de l'API Bot et expérimentez avec des fonctionnalités avancées comme les webhooks et les messages inline.