🐍 Commandes — BSPy (Python)

Fonctionnement

Chaque commande de votre bot correspond à un fichier .py dans le dossier commands/.

Exemple de commande /start (fichier _start.py) :

Copier# Pas d'import nécessaire !
Bot.sendMessage("Bienvenue sur mon bot ! 🎉")
Bot.react("👋")

Configuration d'une commande

Dans l'application BotStrike, chaque commande dispose de ces paramètres. Tout est optionnel sauf le Nom. Chaque option agit automatiquement, sans écrire de code :

Alias — Plusieurs noms pour une même commande

Un alias permet à l'utilisateur de taper différentes variantes pour déclencher la même commande :

Copier# Commande : /start
# Alias : bonjour, hi, hello, salut
# → L'utilisateur peut taper l'un ou l'autre, le même script s'exécute

Bot.sendMessage("Bienvenue ! Comment puis-je vous aider ? 😊")

Réaction emoji automatique (autoret)

Configurer une réaction dans l'application évite d'écrire Bot.react() à chaque fois :

Copier# Config : réaction = "👍" (isBig = coché)
# Le bot réagit automatiquement avant d'exécuter ce script

Bot.sendMessage("Commande reçue ! ✅")
# Équivalent à écrire :
# Bot.react("👍", True)
# Bot.sendMessage("Commande reçue ! ✅")

Action de chat (indicateur d'écriture)

Copier# Config : action = "typing", durée = 2
# L'utilisateur voit "[Nom du bot] est en train d'écrire..." pendant 2 secondes
# puis le code s'exécute

res = HTTP.get("https://api.example.com/data")
Bot.sendMessage(res["body"])

🔁 Retry auto (retentative automatique)

Le champ « Délai retentative auto (secondes) » dans la configuration d'une commande permet de retenter automatiquement une fois l'envoi vers Telegram si la première tentative échoue (problème réseau passager, erreur serveur Telegram, etc.).

• 0 = désactivé (défaut, comportement classique).
• Minimum 2 secondes. Une valeur inférieure est interprétée comme désactivée.
• Recommandé : 6 secondes pour absorber un micro-incident sans rallonger inutilement la commande.

Méthodes couvertes : sendMessage, editMessageText, editMessageCaption, sendPhoto, sendVideo, sendDocument, sendAnimation, sendAudio, sendVoice, sendSticker.

Les erreurs de quota (HTTP 402) ne déclenchent pas de retry — c'est une situation finale qui exige une action utilisateur (rechargement d'itérations).

Attendre la réponse

Quand l'option « Attendre la réponse » est cochée dans la configuration de la commande, le bot attend automatiquement le prochain message de l'utilisateur.

La réponse de l'utilisateur est ensuite passée au script via la variable message.

Exemple : demander le nom

Copier# Fichier : ask_name.py (commande /ask_name)
# Option "Attendre la réponse" cochée dans la config

Bot.sendMessage("Comment tu t'appelles ?")

# La variable 'message' contient la réponse de l'utilisateur
# après qu'il ait écrit son prochain message

Via le code (sans cocher l'option)

Vous pouvez aussi programmer l'attente manuellement avec Bot.waitForResponse() :

Copier# Fichier : ask_age.py
Bot.sendMessage("Quel est ton âge ?")

def on_reply(u):
    msg = u.get("texte", "")
    Bot.sendMessage("Tu as " + msg + " ans !")

Bot.waitForResponse(on_reply)

Avec runCommand (séparation des commandes)

Au lieu de tout traiter dans un seul callback, vous pouvez rediriger la réponse vers une autre commande avec runCommand. Chaque commande gère son propre travail :

Copier# Fichier : ask_name.py — demande le nom
Bot.sendMessage("Comment tu t'appelles ?")
Bot.waitForResponse({"runCommand": "/got_name"})

Copier# Fichier : got_name.py — reçoit et traite la réponse
# 'message' contient la réponse de l'utilisateur
Props.set("nom_" + str(chat_id), message)
Bot.sendMessage("Merci " + message + " ! Quel est ton âge ?")
Bot.waitForResponse({"runCommand": "/got_age"})

Copier# Fichier : got_age.py — traite l'âge
nom = Props.get("nom_" + str(chat_id))
Bot.sendMessage(nom + ", tu as " + message + " ans ! ✅")

Réactions

Les réactions permettent de mettre un emoji sur le message de l'utilisateur. Il existe deux types :

Réaction simple

Un petit emoji qui apparaît dans le coin du message :

Copier# Réaction simple (par défaut)
Bot.react("👍")
Bot.react("❤️")
Bot.react("🤖")

Réaction isBig (grande animation)

Un gros emoji animé qui prend tout l'écran :

Copier# Grande réaction animée
Bot.react("👍", {"is_big": True})

Variables disponibles

Dans chaque fichier de commande, ces variables sont automatiquement disponibles (aucun import) :

🔍 Fonction inspect() — Débogage

inspect(val) convertit n'importe quelle valeur Python en texte lisible. Parfait pour afficher le contenu d'un dict ou d'un objet sans télécharger de module.

Copier# Afficher toutes les infos de l'utilisateur
Bot.sendMessage(inspect(user))

# Débugger une propriété stockée
val = Props.get("mon_objet")
Bot.sendMessage(inspect(val))

# Afficher n'importe quelle valeur
Bot.sendMessage(inspect({"a": 1, "b": [2, 3]}))
# Résultat :
# {
#   "a": 1,
#   "b": [2, 3]
# }

Boutons (Inline Keyboard & Reply Keyboard)

Telegram propose deux types de claviers : les boutons inline (sous le message) et les reply keyboards (menu en bas). Vous pouvez les personnaliser avec des styles, des liens, et plus.

Bouton inline simple (callback)

Un bouton qui déclenche une action dans le bot :

Copier# Bouton simple avec callback_data
Bot.sendButtons("Choisissez une option :", [
    {"text": "⭕ Normal", "data": "afficher_infos"},
    {"text": "📞 Contact", "data": "contact"}
])

Bouton URL (ouvrir un lien)

Un bouton qui ouvre un lien dans le navigateur :

Copier# Bouton qui ouvre une page web
Bot.sendButtons("🌐 Visitez notre site :", [
    {"text": "🔗 Ouvrir le site", "url": "https://exemple.com"},
    {"text": "💬 Telegram", "url": "https://t.me/moncanal"}
])

Styles de boutons

Telegram supporte des styles pour changer l'apparence des boutons inline :

Exemple complet avec styles (via Api)

Copier# Interface de boutons colorés
Api.sendMessage({
    "chat_id": chat_id,
    "text": "<b>🔥 Interface de Boutons</b>\n\nToutes les couleurs disponibles :",
    "parse_mode": "HTML",
    "reply_markup": {
        "inline_keyboard": [
            # Rangée 1 — Neutre et Principal
            [
                {"text": "⭕ Normal", "callback_data": "afficher_infos"},
                {"text": "🟦 Principal", "callback_data": "confirmer", "style": "primary"}
            ],
            # Rangée 2 — Succès et Danger
            [
                {"text": "🟩 Valider", "callback_data": "valider", "style": "success"},
                {"text": "🟥 Supprimer", "callback_data": "supprimer", "style": "danger"}
            ],
            # Rangée 3 — Avec icône custom
            [
                {"text": "⭐ Favoris", "callback_data": "favoris", "style": "primary", "icon_custom_emoji_id": "5368324170671202286"}
            ]
        ]
    }
})

Bouton copier du texte

Un bouton qui copie du texte dans le presse-papier de l'utilisateur :

Copier# Bouton qui copie un code promo
Api.sendMessage({
    "chat_id": chat_id,
    "text": "🎁 Votre code promo :",
    "reply_markup": {
        "inline_keyboard": [
            [{"text": "📋 Copier le code", "copy_text": {"text": "PROMO2026"}}]
        ]
    }
})

Reply Keyboard (menu en bas)

Un clavier personnalisé qui reste en bas de l'écran :

Copier# Menu classique (Bot.sendMenu)
Bot.sendMenu("👇 Choisissez :", [
    ["📊 Stats", "⚙️ Paramètres"],
    ["❓ Aide"]
])

Chaque bouton lance la commande qui porte exactement son texte : le bouton « 📊 Stats » lance la commande nommée 📊 Stats. Pour garder un texte libre, reliez le bouton à une commande avec command :

Copier# Chaque bouton mène à une commande, quel que soit son texte
Bot.sendMenu("👇 Choisissez :", [
    [{"text": "📊 Mes statistiques", "command": "/stats"}],
    [{"text": "❓ Besoin d'aide", "command": "/aide"}]
])

Passer une valeur par un bouton

Nom de la commande, une espace, puis la valeur : la commande la reçoit dans params. Une seule commande /rdv_ok sert ainsi tous les rendez-vous.

CopierBot.sendButtons("Rendez-vous R12 :", [
    {"text": "✅ Confirmer", "command": "/rdv_ok R12"},
    {"text": "❌ Refuser",   "command": "/rdv_non R12"},
])
# Dans /rdv_ok : params vaut "R12"
Bot.sendMessage("Rendez-vous " + params + " confirmé ✅")

Variante « à préfixe » : une commande nommée /rdv_ok_* (avec l'étoile) reçoit tout ce qui commence par /rdv_ok_ — /rdv_ok_R12, /rdv_ok_R13… La fin (R12) arrive dans params.

Navigation propre : un seul écran à la fois

Quand un bouton change d'écran, l'ancien ne doit pas rester au-dessus. Même genre de message (texte → texte, message riche → message riche) : modifiez-le avec Bot.editMessage / Bot.editRichMessage. D'un texte à une photo (ou l'inverse), Telegram ne sait pas transformer l'un en l'autre : effacez le message cliqué, puis envoyez le nouvel écran. Les boutons vont sous la photo, jamais dans un message à part.

Copier# /tuto, lancé par un bouton sous l'accueil (un message texte)
if request and request.get("callback_query"):
    Bot.deleteMessage()   # efface l'écran cliqué
Bot.sendPhoto("https://exemple.com/tuto.jpg", "📲 Étape 1 : …", {
    "buttons": [{"text": "🏠 Accueil", "command": "/start"}]
})

Reply Keyboard avec styles (via Api)

Copier# Clavier standard avec couleurs
Api.sendMessage({
    "chat_id": chat_id,
    "text": "👇 Choisissez une option :",
    "reply_markup": {
        "keyboard": [
            [
                {"text": "⭕ Menu Principal"},
                {"text": "🟦 Paramètres", "style": "primary"}
            ],
            [
                {"text": "🟩 Enregistrer", "style": "success"},
                {"text": "🟥 Annuler", "style": "danger"}
            ]
        ],
        "resize_keyboard": True
    }
})

Récapitulatif des propriétés d'un bouton inline

📐 Champ keyboard — syntaxe rapide (formulaire)

Le champ keyboard dans la configuration de la commande permet d'écrire un clavier en une ligne :

CopierYes{success}, No{danger} \n Annuler

Voir(view_data), Modifier(edit_data) \n Retour(back)

💰 Bot.currency() — compteur numérique

Copierwallet = Bot.currency(f"solde_{user['id']}")
wallet.add(100); wallet.sub(20); wallet.set(1000); wallet.reset()
Bot.sendMessage(f"Solde : {wallet} coins")

Exemples complets

Répéter un texte (/echo)

Copier# echo.py — /echo Bonjour tout le monde
if not params:
    Bot.sendMessage("❌ Utilisation : /echo <texte>")
    return
Bot.sendMessage("🔊 " + params)

Saluer avec réaction

Copier# start.py
Bot.react("👋", {"is_big": True})
Bot.sendMessage("Salut " + user["prenom"] + " ! 🎉")

Message auto-supprimé

Copier# secret.py — le message du BOT se supprime après 5 secondes
Bot.sendMessage("Ce message va disparaître... 👻", {"delete_after": 5})

Message silencieux (sans notification)

Copier# Envoyer sans déclencher de notification chez l'utilisateur
Bot.sendMessage("Mise à jour silencieuse 🔕", {"silent": True})

Épingler un message

Copier# Épingler — Telegram affiche "Bot a épinglé..."
Bot.sendMessage("📌 Annonce importante !", {"pin": True})

# Épingler sans le message système
Bot.sendMessage("📌 Annonce discrète", {"pin": True, "pin_silent": True})

Désépingler un message

Copier# Désépingler un message (par message_id)
Bot.unpinMessage(message_id)

# Désépingler le dernier message épinglé
Bot.unpinMessage()

Envoi via Api avec options

Copier# Api.sendPhoto avec suppression automatique
Api.sendPhoto({"chat_id": chat_id, "photo": "https://exemple.com/img.jpg", "caption": "Photo temporaire"})

# Api.sendMessage classique
Api.sendMessage({"chat_id": chat_id, "text": "Message direct", "disable_notification": True})

# Même chose, dans l'ordre de l'API Telegram (+ options en dernier)
Api.sendMessage(chat_id, "Message direct", {"disable_notification": True})
Api.sendPhoto(chat_id, "https://exemple.com/img.jpg", "Légende")

Combinaison d'options

Copier# Tout en un : silencieux + épinglé + supprimé après 60s
Bot.sendMessage("⚡ Promo flash !", {
    "silent": True,
    "pin": True,
    "pin_silent": True,
    "delete_after": 60
})

Supprimer le message de l'utilisateur

Copier# delete_user_msg.py — supprime le message de l'utilisateur
Api.deleteMessage({"chat_id": chat_id, "message_id": message_id})
Bot.sendMessage("✅ Message supprimé !")

Collecte de données

Copier# register.py
Bot.sendMessage("Quel est ton prénom ?")

def on_reply(u):
    nom = u.get("texte", "")
    Props.set("nom_" + str(chat_id), nom)
    Bot.sendMessage("Merci " + nom + ", inscrit ! ✅")

Bot.waitForResponse(on_reply)

📦 Médias, édition, action & User

Toutes ces fonctions sont disponibles directement dans n'importe quel fichier de commande, sans import.

📷 Envoyer une photo / vidéo / document

Copier# Photo (URL publique ou chemin /tmp)
Bot.sendPhoto("https://exemple.com/img.jpg", "📸 Légende sous la photo")

# Vidéo
Bot.sendVideo("https://exemple.com/clip.mp4", "🎬 Ma vidéo")

# Document (PDF, ZIP, etc.)
Bot.sendDocument("https://exemple.com/rapport.pdf", "📎 Voici le rapport")

# Fichier généré localement (PDF, image, ...)
path = Pdf.create({"title": "Facture"}); Pdf.h1("Facture #42"); Pdf.text("Total : 99€")
file_path = Pdf.save()  # /tmp/...pdf
Bot.sendDocument(file_path, "🧾 Votre facture")

♻️ Lien expiré ? Le média continue de partir

Quand vous envoyez un média par URL, Telegram télécharge le fichier et renvoie un file_id : une référence vers sa propre copie. BotStrike mémorise ce file_id au premier envoi réussi et le réutilise pour tous les appels suivants avec la même URL. Le lien d'origine n'a donc besoin d'être valide qu'une seule fois.

C'est ce qui rend utilisable un lien linkmedia.botstrike.net (généré par @CreatorLinksMediaBot), qui expire au bout d'1 heure : passé ce délai, la commande continue d'envoyer l'image sans erreur.

Copierurl = "https://linkmedia.botstrike.net/8e066ffe/cdc05/promo.jpg"

# 1er appel : Telegram télécharge l'URL, BotStrike retient le file_id
Bot.sendPhoto(url, "🔥 Notre promo du jour")

# Appels suivants (demain, dans 1 mois...) : le file_id part à la place.
# Le lien a beau être expiré, l'image arrive quand même.
Bot.sendPhoto(url, "🔥 Notre promo du jour")

Le cache couvre sendPhoto, sendVideo, sendDocument, sendAudio, sendVoice, sendAnimation (GIF), sendSticker et sendVideoNote — via Bot.* comme via Api.* :

Copier# Audio, voix, GIF et stickers s'écrivent en dictionnaire via Api
Api.sendAudio({"audio": url_mp3, "caption": "🎵 Notre jingle"})
Api.sendAnimation({"animation": url_gif})
Api.sendSticker({"sticker": url_webp})

CopierBot.sendPhoto(url, "Nouvelle version", {"force_refresh": True})

✏️ Éditer / supprimer un message

Copier# Éditer le dernier message du bot
Bot.sendMessage("⏳ Chargement...")
# ... traitement ...
Bot.editMessage("✅ Terminé !")

Copier# Éditer un message précis (par message_id)
Bot.editMessage("Nouveau texte", message_id=monMsgId)

Copier# Supprimer le message COURANT — celui que la personne vient
# d’envoyer, ou celui qui porte le bouton sur lequel elle a appuyé.
# ⚠️ Ce n’est PAS « le dernier message du bot ».
Bot.deleteMessage()

Copier# Effacer le menu après un clic sur son bouton :
# sur un appui, message_id est déjà celui du message au bouton.
# Le test est obligatoire — sans lui, une commande TAPÉE ferait
# disparaître le message de la personne.
if request and request.get("callback_query"):
    Bot.deleteMessage()

Copier# Supprimer un message précis
Bot.deleteMessage(message_id)

🎞️ Animation /ecrit — texte qui s'écrit lettre par lettre

Copier# Commande /ecrit
# Les Bot.editMessage sont collectés et exécutés EN SÉQUENCE après le script.
# go_to=next.actionN → passe à l'étape N. run_after=N → attend N secondes.
# Les indices DOIVENT être séquentiels (1, 2, 3…) — max next.action9.
Bot.sendMessage("je tape amas 1 à 1")
Bot.editMessage(" a",   opts={"go_to": next.action1, "run_after": 1})
Bot.editMessage(" am",  opts={"go_to": next.action2})
Bot.editMessage(" ama", opts={"go_to": next.action3})
Bot.editMessage(" amas")  # dernier : pas de go_to

⏳ Animation /tape — barre de chargement progressive

Copier# Commande /tape
Bot.sendMessage("⬜⬜⬜⬜  0%")
Bot.editMessage("🟩⬜⬜⬜  25%",  opts={"go_to": next.action1, "run_after": 1})
Bot.editMessage("🟩🟩⬜⬜  50%",  opts={"go_to": next.action2, "run_after": 1})
Bot.editMessage("🟩🟩🟩⬜  75%",  opts={"go_to": next.action3, "run_after": 1})
Bot.editMessage("🟩🟩🟩🟩  100%", opts={"go_to": next.action4, "run_after": 1})
Bot.editMessage("✅ Chargement terminé !")

⌨️ Action de chat (typing, upload…)

Copier# Affiche "... est en train d'écrire" pendant 3 secondes
Bot.action("typing", 3)
Bot.sendMessage("Voici la réponse !")

# Types valides : typing, upload_photo, upload_video,
# upload_document, upload_voice, record_voice, record_video, find_location

👤 User.* — données par utilisateur

Copier# Stocker / lire une donnée propre à l'utilisateur courant
User.setProp("langue", "fr")
langue = User.getProp("langue", "fr")  # 2e arg = défaut

# Compteurs
User.add("score", 10)   # +10
User.sub("score", 3)    # -3
score = User.getProp("score", 0)

# Envoyer un message à l'utilisateur
User.sendMessage("📬 Message privé pour toi !")

🔁 Bot.run — lancer une autre commande

Copier# Exécute /menu après 5 secondes
Bot.run({"command": "/menu", "run_after": 5})

# Avec un payload
Bot.run({"command": "/notify", "options": {"content": {"id": 42}}})

📚 Référence Telegram Bot API

BotStrike expose l'intégralité de l'API Bot Telegram. Toute méthode officielle peut être appelée via Api.<methode>({...}) (le chat_id du contexte est injecté automatiquement si vous l'omettez).

📥 Retour des fonctions Bot.*

Toutes les fonctions Bot.send* retournent l'objet Message Telegram complet :

Copierres = Bot.sendMessage("Coucou")
# res = {
#   "message_id": 1234,
#   "chat": {"id": 123456789, "type": "private"},
#   "from": {"id": 7890, "is_bot": True, "first_name": "MonBot"},
#   "date": 1734...,
#   "text": "Coucou"
# }

mid = res["message_id"]
Bot.editMessage("Coucou (édité)", mid)

⭐ Commande * — Interception universelle

La commande * est une commande spéciale qui se déclenche pour tous les messages qui ne correspondent à aucune autre commande. C'est le gestionnaire par défaut du bot.

Comment la créer

Créez un fichier nommé *.py dans votre bot. Il sera automatiquement associé à la commande * :

Copier# Fichier : *.py
# Se déclenche pour tout message non reconnu

Bot.sendMessage("Je n'ai pas compris votre message 🤔\nTapez /help pour voir les commandes disponibles.")

Utiliser le message reçu

La variable message contient le texte envoyé par l'utilisateur :

Copier# Fichier : *.py — répéter tout message non reconnu

Bot.sendMessage("Vous avez dit : " + message + "\n\nJe ne connais pas cette commande. Tapez /help.")
Bot.react("🤔")

Exemple : moteur de recherche simple

Copier# Fichier : *.py — tout message devient une recherche

if not message:
    Bot.sendMessage("Envoyez un texte pour rechercher.")
else:
    resultat = HTTP.get("https://api.exemple.com/search?q=" + message)
    Bot.sendMessage("🔍 Résultats pour : " + message + "\n" + str(resultat.get("body", "Aucun résultat")))

⚠️ Commande ! — Gestionnaire d'erreur

La commande ! est une commande spéciale qui s'exécute automatiquement quand une erreur survient dans le code d'une autre commande. Créez simplement une commande nommée ! dans BotStrike — le fichier créé sera !.py.

Comportement par défaut (sans commande !)

Si vous n'avez pas de commande !, le bot réagit avec 😢 et envoie un message localisé :

Créer la commande dans BotStrike

Dans l'application, nommez votre commande ! (point d'exclamation). Le fichier !.py est créé automatiquement. Deux variables spéciales sont injectées :

Exemples Python

Copier# Commande : ! — message d'erreur personnalisé

Bot.sendMessage(
    "⚠️ Une erreur est survenue dans la commande " + str(error_command) + ".\n"
    "Détail : " + str(error) + "\n"
    "Notre équipe a été notifiée. ✅",
    {"parse_mode": "HTML"}
)

Copier# Commande : ! — log + bouton support

Bot.react("😢")
Props.set("last_error_" + str(chat_id), error_command)

Bot.sendButtons(
    "🔧 Oups ! Un problème technique est survenu.\nNotre équipe va corriger ça.",
    [{"text": "💬 Contacter le support", "url": "https://t.me/BotstrikeAssiste"}]
)