Comment utiliser BotFather pour créer un bot Telegram avec des commandes personnalisées ?

Introduction à BotFather et aux commandes personnalisées

BotFather, le bot officiel de Telegram, vous permet de créer et gérer vos propres bots. Chaque bot peut répondre à des commandes personnalisées que vous définissez. Ce guide vous explique pas à pas comment utiliser BotFather pour configurer ces commandes, depuis la création du bot jusqu'à l'implémentation côté serveur. Contrairement à une idée reçue, BotFather n'est pas limité à un plan tarifaire : il est entièrement gratuit, et la puissance des commandes dépend uniquement de votre code. Nous allons comparer les différentes familles de commandes disponibles : commandes textuelles classiques, commandes inline, boutons de réponse et menus contextuels. Chaque type débloque une interaction plus riche avec les utilisateurs, et nous verrons comment les choisir selon vos besoins.

Matrice des fonctionnalités : quelles commandes pour quel usage ?

Avant de plonger dans la configuration, il est utile de comprendre les paliers de fonctionnalités que BotFather permet d'activer. En réalité, BotFather ne gère que la définition des noms de commandes (par exemple /start, /help). La logique derrière chaque commande est entièrement codée par le développeur via l'API Telegram. Voici un aperçu des types de commandes que vous pouvez exposer :

• Commandes textuelles simples : l'utilisateur tape /commande et le bot répond. Idéal pour les actions de base (démarrer, aide, paramètres).
• Commandes avec paramètres : le bot peut interpréter des arguments après la commande, comme /météo Paris.
• Commandes inline : l'utilisateur tape @votrebot requête dans n'importe quelle conversation, et le bot propose des résultats. Nécessite de déclarer le mode inline dans BotFather.
• Boutons de commande (clavier personnalisé) : bien que ce ne soit pas une “commande” au sens strict, BotFather permet d'activer le mode clavier pour simplifier l'interaction.
• Commandes via des menus de bot : depuis 2024, Telegram a introduit les menus de commandes persistants (affichés dans la barre de saisie). Leur contenu est défini via BotFather.

Ces types ne s'excluent pas mutuellement. Vous pouvez par exemple avoir des commandes textuelles classiques tout en proposant une interface inline. Le choix dépend de votre scénario : une commande simple est plus directe, tandis qu'une inline permet à d'autres utilisateurs d'interagir avec votre bot sans l'ajouter. Pour vous guider, un tableau récapitulatif figure en fin de guide.

Créer un bot et définir ses premières commandes

Ouvrez Telegram et recherchez le contact BotFather (vérifiez le badge “vérifié” à côté de son nom). Si vous n'avez pas encore de bot, envoyez la commande /newbot et suivez les instructions : donnez un nom public (ex. « MonAssistant ») puis un username unique se terminant par bot (ex. MonAssistantBot). BotFather vous remettra un token d'API (une chaîne de caractères comme 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11). Conservez ce token en sécurité : il permet de contrôler votre bot.

Pour ajouter une commande personnalisée, utilisez la commande /setcommands dans le chat avec BotFather. Envoyez-lui simplement une liste au format :

start - Démarrer le bot
help - Afficher l'aide
meteo - Consulter la météo d'une ville

Chaque ligne est une commande (sans le /) suivie d'un tiret et d'une description courte. BotFather confirme la mise à jour. Désormais, lorsque l'utilisateur tape / dans le chat avec votre bot, les commandes apparaissent dans un menu déroulant. Cette configuration est instantanée et ne nécessite aucun redémarrage de votre serveur.

Sur mobile vs desktop

La procédure via BotFather est identique sur toutes les plateformes : vous tapez simplement les commandes dans la conversation. Cependant, la gestion des commandes une fois configurées diffère :

• Android & iOS : Après avoir tapé /, un menu contextuel apparaît avec la liste des commandes et leurs descriptions. Sur iOS, il faut parfois appuyer sur le bouton “+” puis “Commandes” si le clavier cache la barre.
• Desktop (Windows, macOS, Linux) : Le menu des commandes s'affiche automatiquement dès que vous tapez le slash. Vous pouvez naviguer avec les flèches et valider avec Entrée.

Cette différence d'interface n'affecte pas le comportement du bot : une fois la commande envoyée, le traitement côté serveur reste le même.

Débloquer des paliers avancés : commandes inline, boutons et plus

BotFather offre plusieurs réglages qui activent des fonctionnalités supplémentaires. Contrairement à un système de paliers payants, ces options sont toutes gratuites mais nécessitent une validation de votre part. Explorons les principales.

1. Activer le mode inline

Pour que les utilisateurs puissent invoquer votre bot depuis n'importe quel chat en tapant @votrebot, vous devez activer le mode inline. Envoyez /setinline à BotFather et choisissez un placeholder (ex. « Recherchez quelque chose… »). Une fois activé, votre bot recevra des requêtes inline_query que vous devez traiter via l'API. Ce palier débloque une interaction bien plus large, car le bot n'a pas besoin d'être membre du groupe pour être utilisé. Exemple concret : un bot de citation qui retourne une phrase célèbre en fonction du mot-clé tapé.

2. Ajouter un clavier de commandes

BotFather ne permet pas directement de configurer des boutons de réponse (ceux-ci sont gérés par votre code). Cependant, il existe une commande /setcommands qui définit les commandes suggérées dans le menu. Pour aller plus loin, vous pouvez utiliser la commande /setmenubutton (disponible depuis la version de BotFather de 2024) pour ajouter un bouton “Menu” qui ouvre une URL ou une commande. Envoyez /setmenubutton, choisissez votre bot, puis indiquez le texte et le lien (ou la commande). Ce palier est particulièrement utile pour les bots qui proposent une interface Web ou une documentation.

3. Gérer les droits dans les groupes

Quand votre bot est invité dans un groupe, vous pouvez préciser quelles commandes sont accessibles via /setgrouppermissions dans BotFather. Par exemple, vous pouvez limiter le bot à répondre uniquement aux commandes /start et /help dans un groupe, tandis que les autres commandes ne fonctionnent qu'en privé. Cela évite que le bot spamme un groupe avec des interactions non pertinentes et améliore l'expérience collective.

Côté serveur : comment le code traite les commandes

Une fois les commandes définies dans BotFather, votre serveur (ou votre script) doit les reconnaître et y répondre. L'API Telegram envoie une mise à jour contenant un objet Message avec un champ text commençant par /. Voici un exemple minimal en Python avec la bibliothèque python-telegram-bot (version 20.x).

from telegram.ext import Application, CommandHandler

async def start(update, context):
    await update.message.reply_text('Bonjour ! Je suis votre assistant.')

async def help(update, context):
    await update.message.reply_text('Commandes disponibles : /start, /help, /meteo')

async def meteo(update, context):
    ville = ' '.join(context.args) if context.args else 'Paris'
    reponse = f'Météo pour {ville} : ensoleillé (exemple)'
    await update.message.reply_text(reponse)

def main():
    app = Application.builder().token('VOTRE_TOKEN').build()
    app.add_handler(CommandHandler('start', start))
    app.add_handler(CommandHandler('help', help))
    app.add_handler(CommandHandler('meteo', meteo))
    app.run_polling()

if __name__ == '__main__':
    main()

Notez que le nom de la commande (sans le /) est passé à CommandHandler. Les arguments sont disponibles dans context.args. Ce code fonctionne aussi bien en polling qu'en webhook. Le choix entre les deux dépend de votre infrastructure : le polling est plus simple pour un développement local, tandis que le webhook nécessite une URL publique et un certificat SSL.

Gérer les commandes inline

Pour les requêtes inline, vous devez utiliser un InlineQueryHandler. Exemple :

from telegram.ext import InlineQueryHandler
from telegram import InlineQueryResultArticle, InputTextMessageContent

async def inline_query(update, context):
    query = update.inline_query.query
    # logique de recherche…
    results = [
        InlineQueryResultArticle(
            id='1',
            title='Résultat pour ' + query,
            input_message_content=InputTextMessageContent('Vous avez cherché : ' + query)
        )
    ]
    await update.inline_query.answer(results)

app.add_handler(InlineQueryHandler(inline_query))

Cette capacité correspond au palier “inline” activé via BotFather. Sans cette activation, le bot ignorera les requêtes inline. Assurez-vous d'avoir bien suivi l'étape de configuration côté bot avant d'implémenter ce handler.

Intégration avec d'autres services et automations

Les commandes personnalisées deviennent puissantes lorsqu'elles sont liées à des API externes. Par exemple, une commande /news peut interroger un flux RSS, une commande /translate peut appeler un service de traduction. Pour cela, votre code doit effectuer une requête HTTP dans le handler. Assurez-vous de gérer les timeouts et les erreurs pour ne pas bloquer le bot. Il est recommandé d'utiliser des appels asynchrones (par exemple aiohttp avec Python).

Un cas d'usage courant est l'assistant domestique : le bot reçoit une commande /lampe allumer et envoie une requête à un serveur local. La sécurité est cruciale : ne révélez jamais votre token d'API ou vos clés secrètes dans le code source côté client. Utilisez des variables d'environnement et validez toutes les entrées utilisateur.

Migration : d'un bot simple à un système multi-commandes

Si vous commencez avec une poignée de commandes et que vous souhaitez évoluer vers une architecture plus modulaire, planifiez la migration de votre base de code. Une approche courante consiste à séparer chaque commande dans son propre fichier ou classe, et à les enregistrer dynamiquement. Cela facilite l'ajout de nouvelles commandes sans toucher au fichier principal. De plus, pensez à utiliser des middlewares pour la journalisation, les limites de taux et l'autorisation.

Les commandes définies dans BotFather ne sont que des étiquettes ; votre code peut les interpréter comme bon vous semble. Par exemple, vous pouvez créer une commande /admin qui n'est accessible qu'à certains utilisateurs (vérification de l'ID Telegram dans votre base de données). Cette flexibilité vous permet de faire évoluer votre bot sans jamais toucher la configuration BotFather, tant que les noms de commandes restent inchangés.

Dépannage fréquent

Voici les problèmes courants rencontrés lors de la configuration des commandes personnalisées, avec leurs causes et solutions.

Les commandes n'apparaissent pas dans le menu

Symptôme : après avoir exécuté /setcommands, l'utilisateur ne voit pas les commandes lorsqu'il tape /.
Cause possible : le bot a été recréé avec un nouveau token, ou les commandes ont été définies avant la création du bot.
Vérification : envoyez /setcommands à nouveau et suivez les invites. Assurez-vous d'avoir sélectionné le bon bot (BotFather affiche le nom du bot en question).
Résolution : redéfinissez les commandes. Le menu est mis à jour en quelques secondes côté serveur Telegram ; aucun rafraîchissement manuel n'est nécessaire.

Le bot ne répond pas à une commande

Symptôme : l'utilisateur envoie /maCommande mais le bot ne réagit pas (pas d'accusé de réception).
Cause possible : votre code ne gère pas cette commande (handler manquant) ou bien le bot n'a pas été redémarré après modification du code.
Vérification : consultez les logs de votre serveur. Si vous utilisez le polling, vérifiez que le script tourne. Si vous utilisez un webhook, testez-le avec une requête POST factice (par exemple via curl).
Résolution : ajoutez le handler approprié et redémarrez le processus. Assurez-vous que le nom de la commande correspond exactement à celui défini dans BotFather (sensible à la casse ? en réalité, les commandes sont insensibles à la casse du côté client, mais dans le handler vous devez utiliser la forme en minuscules).

Le mode inline ne fonctionne pas

Symptôme : taper @votrebot texte n'affiche rien ou affiche “Aucun résultat”.
Cause possible : le mode inline n'est pas activé via /setinline, ou votre code ne répond pas correctement aux requêtes inline.
Vérification : vérifiez dans BotFather que le mode inline est bien “Enabled”. Ensuite, activez les logs de votre serveur pour voir si des requêtes inline_query arrivent.
Résolution : activez le mode inline dans BotFather. Dans votre code, implémentez un InlineQueryHandler et appelez answer() avec au moins un résultat.

Bonnes pratiques et limites à connaître

• Limites des commandes : BotFather ne permet pas de commandes avec des espaces ou des caractères spéciaux. Utilisez uniquement des lettres minuscules et des traits d'union (ex. /meteo-paris).
• Nombre de commandes : il n'y a pas de limite officielle documentée, mais une trop longue liste peut devenir difficile à gérer pour l'utilisateur. Restez en dessous de 30-40 commandes principales ; pour des actions spécifiques, préférez des boutons ou des menus contextuels.
• Performances : chaque appel de commande est une requête HTTP. Si votre bot traite des milliers de commandes par seconde, le polling peut devenir un goulot d'étranglement ; passez en webhook et utilisez un load balancer.
• Sécurité : ne faites jamais confiance aux entrées utilisateur. Validez et échappez les arguments pour éviter les injections.
• Compatibilité : les commandes personnalisées fonctionnent dans les conversations privées et les groupes (sauf si restreint). Les commandes inline ne fonctionnent que si le bot est en mode inline activé.

Ces bonnes pratiques vous aideront à maintenir un bot stable, sécurisé et agréable à utiliser.

Liste de contrôle des scénarios applicables et non applicables

Avant d'implémenter des commandes personnalisées, demandez-vous si c'est la bonne approche :

Ce tableau vous permet de choisir rapidement le type d'interaction le plus adapté à chaque besoin. Adaptez-le à votre contexte.

Questions fréquentes

Conclusion

Utiliser BotFather pour créer un bot Telegram avec des commandes personnalisées est une opération simple mais puissante. En définissant soigneusement vos commandes et en implémentant la logique côté serveur, vous offrez une expérience utilisateur fluide et interactive. Les paliers que nous avons parcourus — commandes textuelles, inline, et menus — couvrent la majorité des besoins. N'oubliez pas que la configuration dans BotFather n'est que la partie émergée de l'iceberg ; la vraie valeur réside dans le code que vous écrivez. Pour approfondir, explorez l'API Telegram officielle et les bibliothèques comme python-telegram-bot ou node-telegram-bot-api. Avec ces outils, vous pouvez transformer un simple assistant en un système interactif complet.