Jarvis — Module 09

● Interface · Telegram · Texte

Ce module connecte Hermes Agent à un bot Telegram pour les échanges texte. Le token du bot reste stocké localement dans ~/.hermes/.env, l’accès est limité à votre identifiant Telegram, et la Gateway existante assure la connexion persistante. La voix sera configurée séparément dans le Module 10.

Point de départ

Hermes + Gateway opérationnels

Point d’arrivée

Bot Telegram texte fonctionnel

Sécurité

Token secret + allowlist

Avant de commencer

Prérequis

Modules 00 à 08 validés.
hermes gateway status fonctionne.
Vous disposez de l’application Telegram.
Vous pouvez dialoguer avec @BotFather.

Règle de sécurité

Ne publiez jamais le token Telegram.
Ne mettez pas le token dans un SKILL.md.
Restreignez le bot à votre identifiant Telegram.
N’activez pas l’accès global en production.

Important : tous les exemples utilisent des placeholders. Remplacez METTRE_VOTRE_TOKEN_TELEGRAM et METTRE_VOTRE_ID_TELEGRAM uniquement sur votre machine. Ne remplacez jamais les placeholders dans une copie publique de cette documentation.

Légende des actions

Lecture seuleModificationValidationOptionnel

Installation pas à pas

09.1 · Vérifier la Gateway Hermes

Lecture seule

hermes gateway status

Pourquoi : Telegram s’appuie sur la Gateway déjà installée au Module 06.

Résultat attendu : La Gateway est active. Si elle ne l’est pas, corrigez d’abord le Module 06.

09.2 · Créer le bot avec BotFather

Modification

# Dans Telegram, ouvrir @BotFather puis envoyer :
/newbot

Pourquoi : Telegram exige qu’un bot soit créé par le service officiel BotFather.

Résultat attendu : BotFather vous demande un nom d’affichage, puis un username unique se terminant par bot, et fournit ensuite un token secret.

09.3 · Conserver le token hors de la documentation

Validation

# Ne collez pas le token ici.
# Conservez-le temporairement dans votre gestionnaire de mots de passe
# jusqu'à l'étape 09.7.

Pourquoi : Toute personne possédant le token peut contrôler le bot.

Résultat attendu : Le token n’apparaît ni dans l’historique de commandes, ni dans un fichier public, ni dans un skill.

09.4 · Personnaliser le bot — optionnel

Optionnel

# Commandes BotFather utiles :
/setdescription
/setabouttext
/setuserpic
/setcommands

Pourquoi : Ces réglages améliorent l’expérience utilisateur sans modifier la connexion Hermes.

Résultat attendu : Le bot possède éventuellement une description, une image et un menu de commandes.

09.5 · Définir un menu minimal — optionnel

Optionnel

help - Afficher l'aide
new - Démarrer une nouvelle conversation
sethome - Définir cette discussion comme canal principal

Pourquoi : BotFather peut afficher ces commandes directement dans le menu Telegram.

Résultat attendu : Le bouton / du bot propose les commandes principales.

09.6 · Trouver votre identifiant Telegram

Lecture seule

# Dans Telegram :
# 1. Ouvrir @userinfobot
# 2. Envoyer /start
# 3. Relever votre identifiant numérique

METTRE_VOTRE_ID_TELEGRAM

Pourquoi : Hermes utilise l’identifiant numérique permanent pour l’allowlist, pas le @username.

Résultat attendu : Vous connaissez votre identifiant Telegram personnel sans le publier.

09.7 · Sauvegarder le fichier de secrets Hermes

Modification

cp ~/.hermes/.env ~/.hermes/.env.backup-$(date +%Y%m%d-%H%M%S)

Pourquoi : Créer un rollback avant d’ajouter la configuration Telegram.

Résultat attendu : Une copie horodatée de ~/.hermes/.env existe.

09.8 · Ajouter Telegram dans ~/.hermes/.env

Modification

nano ~/.hermes/.env

# Ajouter :
TELEGRAM_BOT_TOKEN="METTRE_VOTRE_TOKEN_TELEGRAM"
TELEGRAM_ALLOWED_USERS="METTRE_VOTRE_ID_TELEGRAM"

Pourquoi : Le token et l’allowlist sont chargés par la Gateway sans être intégrés à la documentation ou aux skills.

Résultat attendu : Les deux variables existent dans ~/.hermes/.env.

09.9 · Protéger le fichier .env

Modification

chmod 600 ~/.hermes/.env
stat -c '%a %n' ~/.hermes/.env

Pourquoi : Limiter l’accès aux secrets au propriétaire du fichier.

Résultat attendu : Le mode affiché est 600.

09.10 · Vérifier les variables sans afficher le token

Validation

grep '^TELEGRAM_BOT_TOKEN=' ~/.hermes/.env | sed 's/=.*/=<SECRET PRESENT>/'
grep '^TELEGRAM_ALLOWED_USERS=' ~/.hermes/.env | sed 's/=.*/=<ALLOWLIST PRESENT>/'

Pourquoi : Confirmer que la configuration existe sans révéler les valeurs.

Résultat attendu : Les deux variables sont signalées comme présentes.

09.11 · Redémarrer la Gateway

Modification

hermes gateway restart
hermes gateway status

Pourquoi : La Gateway doit relire le fichier .env et charger l’adaptateur Telegram.

Résultat attendu : La Gateway redémarre et reste active.

09.12 · Contrôler la connexion Telegram dans les logs

Validation

journalctl --user -u hermes-gateway -n 100 --no-pager | grep -Ei 'telegram|gateway|error|warning'

Pourquoi : Vérifier que l’adaptateur Telegram se connecte et identifier immédiatement une erreur de token ou de dépendance.

Résultat attendu : Les logs indiquent une connexion Telegram active, sans erreur bloquante.

09.13 · Tester un premier échange texte

Validation

# Dans Telegram, ouvrir votre bot puis envoyer :
Bonjour Jarvis. Réponds uniquement : Telegram fonctionne.

Pourquoi : Valider le chemin complet Telegram → Gateway → Hermes → modèle local → Telegram.

Résultat attendu : Le bot répond dans la conversation Telegram.

09.14 · Définir le canal principal

Modification

# Dans le chat Telegram qui doit recevoir les notifications :
/sethome

Pourquoi : Les tâches planifiées et notifications proactives ont besoin d’un canal de destination.

Résultat attendu : Hermes confirme que cette conversation devient le canal principal.

09.15 · Vérifier qu’aucun accès global n’est activé

Validation

grep '^TELEGRAM_ALLOW_ALL_USERS=true' ~/.hermes/.env && echo 'A CORRIGER' || echo 'OK - acces global desactive'

Pourquoi : Un bot Hermes pouvant utiliser des outils ne doit pas accepter n’importe quel utilisateur.

Résultat attendu : OK - acces global desactive.

09.16 · Pairing par code — alternative optionnelle

Optionnel

# Si Hermes fournit un code de pairing à un utilisateur autorisé :
hermes pairing list
hermes pairing approve telegram METTRE_VOTRE_CODE_PAIRING

# Pour retirer ultérieurement un accès :
hermes pairing revoke telegram METTRE_ID_TELEGRAM_A_REVOQUER

Pourquoi : Le pairing permet d’ajouter un utilisateur sans modifier et redémarrer l’allowlist statique.

Résultat attendu : Seuls les utilisateurs explicitement approuvés peuvent dialoguer avec le bot.

09.17 · Test fonctionnel Golden

Validation

# Depuis Telegram :
Donne-moi le hostname de la machine et l'état d'Ollama. Ne modifie rien.

Pourquoi : C’est le test non destructif retenu dans le Golden Build pour vérifier l’accès aux outils depuis Telegram.

Résultat attendu : Hermes répond avec les informations demandées sans effectuer d’action de modification.

Alternative : assistant de configuration Hermes

Option plus simple : au lieu d’éditer ~/.hermes/.env manuellement, vous pouvez lancer hermes gateway setup, sélectionner Telegram, saisir le token puis votre identifiant Telegram. Le mode manuel reste documenté ici car il permet de comprendre exactement quelles variables sont utilisées.

Utilisation en groupe — optionnel

DM personnel

C’est le mode le plus simple et le plus sûr pour Jarvis. TELEGRAM_ALLOWED_USERS limite l’accès aux identifiants autorisés.

Groupes / forums

Hermes propose aussi des restrictions dédiées aux groupes, notamment TELEGRAM_GROUP_ALLOWED_USERS et TELEGRAM_GROUP_ALLOWED_CHATS. N’ouvrez pas le bot à un groupe sans définir explicitement la politique d’accès.

Privacy Mode

Le réglage /setprivacy de BotFather contrôle les messages de groupe visibles par le bot. Il n’est pas nécessaire pour un usage en message privé.

Dépannage rapide

Le bot ne répond pas

Vérifiez hermes gateway status, puis les logs avec journalctl --user -u hermes-gateway -f. Contrôlez ensuite la présence du token et de l’allowlist sans afficher leurs valeurs.

Utilisateur refusé

Vérifiez que vous avez utilisé l’identifiant numérique Telegram et non votre @username. Un changement d’allowlist nécessite un redémarrage de la Gateway.

Token compromis

Dans BotFather, révoquez immédiatement le token, générez-en un nouveau, remplacez la valeur dans ~/.hermes/.env, puis redémarrez la Gateway.

La voix ne marche pas

C’est normal à ce stade : ce module valide uniquement le texte. STT, TTS et /voice on seront configurés dans le Module 10.

Références officielles

Validation du Module 09

Ne passez au module suivant que lorsque tous les points applicables sont validés.

Le bot a été créé via BotFather.

Le token n’apparaît dans aucun fichier public ou skill.

Votre identifiant Telegram numérique est connu.

TELEGRAM_BOT_TOKEN est présent dans ~/.hermes/.env.

TELEGRAM_ALLOWED_USERS limite l’accès.

~/.hermes/.env est protégé en mode 600.

La Gateway redémarre sans erreur Telegram bloquante.

Un échange texte avec le bot fonctionne.

/sethome a défini le canal principal.

TELEGRAM_ALLOW_ALL_USERS=true n’est pas activé.

Le test Golden lecture seule fonctionne depuis Telegram.

STOP — Module 09 validé

Telegram texte est maintenant opérationnel. Le Module 10 ajoutera la transcription et la synthèse vocale locales sans modifier cette base.

← Module précédent Revenir à l’ordre des modules