Routage Multi-Bot Telegram

Ce skill gère l’architecture où plusieurs bots Telegram sont connectés à Hermes, chacun dédié à un contexte métier (support, alertes, commandes, factures, etc.), avec routage automatique du message vers le bon bot.

Complémentaire du skill session-routing (qui gère Topics/Profiles/Kanban au sein d’un seul bot).

🔍 Logique de Routage Contexte → Canal

🛠️ Workflow d’Installation

Phase 1 : Inventaire

1. Lire le Sheet d’inventaire des bots (colonne standard : Nom, Description, Usage, Signature, Token, URL, ChatID, Statut)
2. Vérifier les tokens : Si le token contient ***, c’est qu’il est tronqué — la vraie clé secrète a été remplacée. Il faut impérativement récupérer le token complet depuis @BotFather.
   • Vrai token : 8247499204:*** (46 chars)
   • Tronqué : 8247499204:*** (les *** sont LITTÉRAUX dans la cellule)
3. SBF_LivraisonBot a Token sécurisé — impossible de récupérer le token sans @BotFather
4. Demander à l’utilisateur de récupérer les tokens complets depuis @BotFather

Phase 2 : Capture des Chat IDs

Étape par étape (pour un humain) :

1. Ouvrir Telegram sur le téléphone/desktop 📱
2. Chercher le bot dans la barre de recherche (ex: @sbf_supportbot)
3. Cliquer sur Démarrer ou envoyer /start
4. Envoyer n’importe quel message (même /start suffit)
5. Répéter pour chaque bot de la liste

Puis, côté terminal (moi) :

# Pour chaque bot dont on a le TOKEN COMPLET :
curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates" | python3 -c "
import json,sys
d=json.load(sys.stdin)
for u in d.get('result',[]):
    m=u.get('message',{}) or u.get('edited_message',{})
    c=m.get('chat',{})
    print(f'Chat ID: {c.get(\"id\")} | Type: {c.get(\"type\")} | Titre: {c.get(\"title\",c.get(\"first_name\",\"?\"))}')"

Phase 3 : Ajout dans .env

echo 'TELEGRAM_TOKEN_SBF_SUPPORT=8247499204:ABC...' >> ~/.hermes/.env
echo 'TELEGRAM_TOKEN_SBF_ALERTES=8319284012:ABC...' >> ~/.hermes/.env
# ... etc
chmod 600 ~/.hermes/.env

Phase 4 : Configuration gateways (config.yaml)

gateways:
  telegram:
    enabled: true
    token: "${TELEGRAM_TOKEN_BFNOUS}"       # bot principal
  telegram_alertes:                          # bot alertes
    enabled: true
    token: "${TELEGRAM_TOKEN_SBF_ALERTES}"
  telegram_support:                          # bot support
    enabled: true
    token: "${TELEGRAM_TOKEN_SBF_SUPPORT}"
  # ... ajouter les autres

Phase 5 : Routage dans le code

Utiliser send_message(target="telegram:CHAT_ID") pour délivrer au bon canal :

# Exemple : alerte serveur → SBF_AlertesBot
send_message(target="telegram:-100...ALERTES_CHAT_ID", message="🔴 Attaque SSH détectée !")

Phase 6 : Mise à jour du Sheet

Mettre à jour la colonne Chat ID dans le Sheet d’inventaire.

📋 Structure du Sheet d’Inventaire

Colonnes attendues (standard) : 0. Nom Bot Telegram

1. Description
2. Usage / Workflow
3. Signature Courte
4. Token API (peut être tronqué → ***)
5. URL Telegram Bot
6. Chat ID (vide tant que non capturé)
7. Statut Actif (Oui/Non) 8-10. Dernière mise à jour, Responsable, Notes

⚠️ Pièges Connus

Latence / bot silencieux

• Avant de conclure que Telegram est down, vérifier les logs gateway + agent : Telegram peut être connecté et recevoir les messages, mais attendre une compression de contexte ou une grosse requête modèle.
• Marqueurs typiques : inbound message sans response ready, puis Preflight compression, context compression started, ou requêtes modèle à très gros input tokens.
• Si api.telegram.org répond vite et que ✓ telegram connected est présent, le problème est généralement côté session Hermes/modèle/contexte, pas côté Telegram.
• Ne pas redémarrer le gateway sans prévenir si une session est active : ça peut couper un run en cours. Préférer /new ou /reset si l’utilisateur accepte de repartir proprement.
• Coolify vs gateway natif : ne jamais affirmer que Telegram est connecté à l’app Coolify seulement parce que les logs Telegram existent. Corréler 3 preuves : statut de l’app Coolify cible (running:healthy, pas restarting:unknown), montage du même HERMES_HOME/volume (/home/bf/.hermes → chemin conteneur attendu), et logs récents du conteneur Coolify montrant telegram connected/polling. Si les logs mentionnent hermes-gateway.service, traiter cela comme indice d’un gateway natif hors Coolify.
• Détails et commandes redacted : references/telegram-gateway-latency-diagnostics.md.

Tokens

• Les tokens dans le Sheet sont tronqués (la partie secrète est remplacée par ***)
• SBF_LivraisonBot avait Token sécurisé — pas de token du tout dans le sheet
• Les tokens complets ne sont disponibles QUE dans les messages @BotFather (une seule fois après création)
• Si perdu, il faut recréer le bot via @BotFather → /newbot

Chat IDs

• Les Chat IDs individuels (DM) sont des entiers (ex: 7346401040)
• Les Chat IDs de groupe commencent par -100 (ex: -1001234567890)
• Un bot doit recevoir AU MOINS UN MESSAGE avant d’apparaître dans getUpdates
• getUpdates ne montre que les messages récents — si le bot est inactif depuis longtemps, l’update a expiré

Gateways Hermes

• Chaque gateway ajoute un peu de overhead mémoire
• Les gateways sont indépendants — chaque bot a son propre cycle de polling
• Les tokens des gateways sont stockés dans .env (chmod 600)
• Redémarrer le gateway après configuration : hermes gateway restart
• Vérifier la connexion : hermes gateway status

Routage

• send_message(target="telegram:CHAT_ID") fonctionne avec le gateway PRINCIPAL
• Pour utiliser un AUTRE gateway comme expéditeur, il faut préciser le bon canal
• Les notifications cron peuvent être dirigées vers n’importe quel bot via le paramètre deliver

🔗 Références

• Sheet d’inventaire SBF : https://docs.google.com/spreadsheets/d/1n-KUeluojOmvhy3t2sdIA4Fu0gTeVYaEpRhRjuqj9mY/edit
• Session-routing skill : routage interne (Topics/Profiles/Kanban)
• Hermes gateway docs : docs/user-guide/messaging/telegram.md