Tutoriel API Bot Telegram : Créez votre premier bot

Le tutoriel le plus rapide pour l’API Bot Telegram se résume en trois commandes : obtenir un jeton de BotFather, appeler getUpdates pour lire les messages, et appeler sendMessage pour y répondre. Tout le reste du développement de bots s’appuie sur cette boucle. Ce guide vous accompagnera tout au long du processus, de votre première requête cURL à un bot fonctionnel avec un webhook et une bibliothèque.

L’API Bot est une interface HTTP, ce qui signifie que vous pouvez la tester avec curl avant même d’écrire une seule ligne de code. Cela en fait l’une des API les plus conviviales à apprendre. Si vous êtes un développeur souhaitant un bot fonctionnel dès aujourd’hui, ou un créateur hésitant entre le code et une plateforme sans code comme TeleClaw, vous êtes au bon endroit.

À la fin de ce guide, vous comprendrez comment l’API authentifie les requêtes, comment recevoir et envoyer des messages, la différence entre le long polling et les webhooks, ainsi que les limites de débit qui posent problème à la plupart des premiers bots.

Points clés à retenir

• Un bot est un simple client HTTP. Chaque méthode est une requête vers https://api.telegram.org/bot<TOKEN>/METHOD_NAME, donc cURL suffit pour commencer.
• Trois méthodes essentielles pour démarrer : getMe pour vérifier le jeton, getUpdates pour lire les messages, et sendMessage pour répondre.
• Le long polling et les webhooks sont mutuellement exclusifs. Utilisez le polling pour les tests locaux, passez à un webhook pour la production.
• L’API est gratuite, mais Telegram limite l’envoi en masse à environ 30 messages par seconde à différents utilisateurs et un par seconde par chat.
• Une bibliothèque vous fait gagner du temps une fois que votre bot dépasse le stade du simple script. Utilisez python-telegram-bot, aiogram ou Telegraf.

Qu’est-ce que l’API Bot Telegram ?

L’API Bot Telegram est une interface basée sur HTTP qui permet de connecter votre code à Telegram via un bot. Selon l’introduction pour les développeurs de Telegram, les bots sont des comptes spéciaux qui ne nécessitent pas de numéro de téléphone et servent d’interface pour le code exécuté sur votre serveur.

Chaque requête que vous effectuez s’authentifie avec un jeton de bot plutôt qu’un compte utilisateur. Le jeton identifie le bot, vous devez donc le traiter comme un mot de passe et ne jamais le publier dans un dépôt public. La documentation de Telegram le dit clairement : enregistrez votre jeton dans un endroit sûr et ne le partagez pas.

L’API elle-même est gratuite. Telegram propose l’API Bot gratuitement depuis son lancement, sans frais par message et sans limite sur le nombre de bots que vous pouvez créer. C’est pourquoi tant d’outils communautaires, d’assistants de support et d’automatisations l’utilisent. Si vous débutez sur la plateforme, notre guide sur comment créer un bot Telegram couvre la configuration du compte plus en détail.

Étape 1 : Obtenez un jeton de bot auprès de BotFather

Ouvrez Telegram et recherchez @BotFather, le bot officiel pour créer et gérer d’autres bots. Démarrez une conversation et envoyez la commande /newbot.

BotFather vous demandera ensuite deux choses dans l’ordre :

1. Un nom d’affichage pour votre bot, comme “Mon Premier Bot API”.
2. Un nom d’utilisateur qui se termine par bot, comme mon_premier_bot_demo.

Une fois terminé, BotFather vous renverra un jeton API qui ressemble à 123456789:AAExampleTokenStringHere. Ce jeton est la seule information d’identification dont vous aurez besoin pour le reste de ce tutoriel.

Attention : Toute personne disposant de votre jeton contrôle votre bot. Gardez-le dans une variable d’environnement, pas dans le code source. S’il est compromis, envoyez /revoke à BotFather pour en obtenir un nouveau.

Étape 2 : Appelez votre première méthode de l’API Bot

Avant d’écrire le moindre programme, confirmez que le jeton fonctionne. La méthode getMe renvoie des informations de base sur votre bot et constitue le contrôle de santé standard. Remplacez <YOUR_TOKEN> par la valeur obtenue de BotFather.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

Une réponse réussie est un JSON avec "ok": true et l’identifiant, le nom et le nom d’utilisateur de votre bot. Si vous voyez "ok": false, le jeton est incorrect ou contient une faute de frappe.

Cette simple requête représente le schéma complet. Chaque méthode de l’API Bot Telegram suit la même structure : un appel HTTPS à https://api.telegram.org/bot<TOKEN>/METHOD_NAME, avec des paramètres dans la chaîne de requête ou le corps de la requête POST, et un objet JSON en retour. La liste complète se trouve dans la référence de l’API Bot, qui documente chaque méthode et objet dont vous aurez besoin.

Étape 3 : Recevoir et envoyer des messages

Rendons maintenant le bot utile. Il y a une règle qui surprend les débutants : un bot ne peut pas démarrer une conversation. L’utilisateur doit d’abord envoyer un message au bot. Alors, ouvrez votre bot dans Telegram et envoyez-lui n’importe quel texte, comme “bonjour”.

Ensuite, lisez ce message avec getUpdates, qui récupère les mises à jour entrantes en utilisant le long polling et renvoie un tableau d’objets de mise à jour.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

Dans la réponse, recherchez message.chat.id. Ce chat_id est l’adresse à laquelle vous répondrez. Copiez-le, puis appelez sendMessage :

curl -X POST https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage \
 -d chat_id=<CHAT_ID> \
 -d text="Bonjour de mon premier bot"

Votre bot répond dans le chat. Cet aller-retour, lire avec getUpdates et répondre avec sendMessage, est la boucle principale de la plupart des bots Telegram. Le paramètre text accepte jusqu’à 4096 caractères par message, donc les longues réponses doivent être divisées.

Deux détails à retenir lorsque vous développez cet exemple d’API de bot Telegram en code réel :

• Recalculez l’offset. Passez l’update_id de la dernière mise à jour plus un comme paramètre offset lors de votre prochain appel getUpdates, sinon Telegram continuera à renvoyer les mêmes mises à jour.
• Une méthode à la fois. getUpdates cesse de fonctionner dès que vous enregistrez un webhook, ce qui est le sujet de l’étape suivante.

Étape 4 : Choisir entre le long polling et un webhook

Telegram propose deux façons de recevoir les mises à jour, et vous ne pouvez en utiliser qu’une seule par bot à la fois.

• Le long polling signifie que votre code appelle getUpdates de manière répétée. C’est la méthode la plus simple pour l’apprentissage et le développement local car elle ne nécessite pas d’URL publique, juste un processus qui reste en cours d’exécution.
• Les webhooks signifient que Telegram pousse chaque mise à jour vers votre point de terminaison HTTPS sous forme de requête POST dès qu’elle se produit. C’est la norme de production : latence plus faible, pas de polling inactif, et une meilleure évolutivité sous un trafic constant.

Pour passer à un webhook, enregistrez votre URL HTTPS publique une seule fois :

curl "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://yourdomain.com/webhook"

Votre point de terminaison doit disposer d’un certificat TLS valide et renvoyer rapidement un code HTTP 200. Si les mises à jour cessent d’arriver, la première chose à faire est toujours d’inspecter l’erreur. Pour le processus complet d’enregistrement, de vérification et de dépannage, consultez notre guide de configuration de webhook pour bot Telegram. En bref : commencez par le polling pendant que vous construisez, passez à un webhook avant de lancer.

Étape 5 : Intégrer l’API dans une bibliothèque

Les requêtes cURL brutes sont excellentes pour l’apprentissage, mais les bots de production utilisent une bibliothèque. Une bibliothèque gère les appels API, l’analyse des mises à jour, les tentatives et l’état de la conversation, de sorte que vous n’écrivez que la logique spécifique à votre bot. Telegram répertorie les bibliothèques communautaires pour presque tous les langages sur sa page d’exemples de l’API Bot.

Choisissez en fonction du langage que vous connaissez déjà :

• Python : python-telegram-bot est du Python pur, entièrement asynchrone, et prend en charge Python 3.10 et versions ultérieures. aiogram et pyTelegramBotAPI sont des alternatives populaires.
• Node.js : Telegraf est mature et compatible TypeScript. node-telegram-bot-api est une option de longue date.

Voici le même bot écho en Python, le point de départ le plus courant pour un tutoriel sur l’API de bot Telegram en Python :

from telegram import Update
from telegram.ext import Application, MessageHandler, filters, ContextTypes

TOKEN = "YOUR_TOKEN"

async def echo(update: Update, context: ContextTypes. DEFAULT_TYPE):
 await update.message.reply_text(update.message.text)

app = Application.builder().token(TOKEN).build()
app.add_handler(MessageHandler(filters. TEXT & ~filters. COMMAND, echo))
app.run_polling()

Et l’équivalent Node.js avec Telegraf :

import { Telegraf } from 'telegraf'

const bot = new Telegraf(process.env. BOT_TOKEN)
bot.on('text', (ctx) => ctx.reply(ctx.message.text))
bot.launch()

Les deux font le même travail que la boucle cURL de l’étape 3, mais en quelques lignes et avec les parties complexes gérées pour vous. Maria, une développeuse backend qui prototypait un bot de support, est passée des tests cURL à python-telegram-bot en un après-midi et avait des gestionnaires de commandes et des boutons en ligne fonctionnels le même jour. Les concepts de l’API se sont directement transférés car la bibliothèque est une fine couche au-dessus des mêmes méthodes HTTP.

Limites de débit et quotas à connaître

L’API est gratuite, mais elle n’est pas illimitée. La FAQ des Bots de Telegram liste les directives qui empêchent votre bot d’être ralenti.

• Un message par seconde par chat. Dans une seule conversation, évitez d’envoyer plus rapidement.
• Environ 30 messages par seconde au total lors de l’envoi à de nombreux utilisateurs différents. Si vous dépassez, vous commencerez à recevoir des réponses HTTP 429 “Too Many Requests”.
• Environ 20 messages par minute au même groupe.

Lorsqu’une diffusion nécessite réellement plus, vous pouvez activer les Diffusions Payantes dans @BotFather, ce qui augmente la limite à environ 1000 messages par seconde. Les messages au-delà des 30 gratuits par seconde coûtent 0,1 Telegram Star chacun. La plupart des bots n’en ont jamais besoin, mais il est bon de savoir que la limite existe avant de concevoir une fonctionnalité de notification.

Respectez un 429 en lisant la valeur retry_after renvoyée par Telegram et en faisant une pause pendant ce nombre de secondes. Une bibliothèque gère cela pour vous, ce qui est une raison de plus de passer des requêtes brutes une fois que votre trafic est réel.

Oubliez le code : des bots IA sans serveur

Tous les projets n’ont pas besoin d’une base de code personnalisée. Si votre objectif est un assistant IA dans un groupe Telegram, l’API Bot est une infrastructure que vous ne souhaitez peut-être pas maintenir vous-même, en particulier la couche d’hébergement, HTTPS et webhook.

TeleClaw est une plateforme sans code qui exécute le bot pour vous et connecte Claude AI directement. Vous ajoutez @claw à votre groupe, collez votre jeton BotFather dans le tableau de bord et configurez le comportement sans toucher à setWebhook ni à la gestion des limites de débit. Tomas, qui gère une communauté crypto de 4 000 membres, a remplacé un bot personnalisé à moitié terminé par TeleClaw et a mis en place la modération IA et les réponses aux FAQ le soir même.

C’est la même API Bot en dessous. Vous choisissez d’opérer la couche serveur vous-même ou de laisser une plateforme le faire. Explorez ce que cela couvre sur la page des fonctionnalités de TeleClaw, et comparez les options dans notre récapitulatif des meilleurs bots Telegram. Pour une construction purement via tableau de bord, consultez notre guide de chatbot Telegram sans code.

Conclusion

Vous avez maintenant une bonne compréhension du fonctionnement de l’API Bot Telegram : un jeton de BotFather, des méthodes HTTP comme getMe, getUpdates et sendMessage, le choix entre le long polling et les webhooks, et une bibliothèque pour tout encapsuler une fois que votre bot grandit. L’API est gratuite, bien documentée et suffisamment accessible pour être testée avec cURL en quelques minutes.

La prochaine étape la plus rapide est la plus petite. Ouvrez @BotFather, exécutez /newbot et envoyez votre première requête getMe pour confirmer le jeton. De là, vous pouvez développer en Python ou Node, ou ignorer complètement le serveur. Pour lancer un bot alimenté par l’IA en quelques minutes au lieu de jours, ajoutez @claw à votre groupe et configurez-le dans le tableau de bord TeleClaw.