09 - Connecter Telegram à Hermes Agent : guide complet

Connecter Telegram à Hermes Agent : guide complet

Telegram est devenu bien plus qu'une simple application de messagerie. Avec son API bot puissante, son support des médias, ses groupes à sujets et ses messages vocaux, c'est le compagnon idéal pour interagir avec Hermes Agent — où que vous soyez, depuis votre téléphone, votre tablette ou votre bureau.

Dans ce guide complet, nous voyons comment connecter Hermes Agent à Telegram de A à Z : de la création du bot jusqu'au déploiement 24/7 en passant par la sécurité, la gestion de plusieurs groupes et les cas d'usage concrets.

Pourquoi Telegram est le meilleur compagnon d'Hermes

Hermes Agent brille dans un terminal, mais tout le monde n'a pas un terminal sous la main à chaque instant. Telegram comble ce fossé avec des avantages uniques :

• Disponible partout : mobile, desktop, web — une seule conversation synchronisée
• Messages vocaux : envoyez un mémo vocal, Hermes le transcrit automatiquement via Whisper (local, Groq ou OpenAI)
• Support multimédia : images, PDF, fichiers — tout est géré nativement via le système MEDIA:
• Groupes à sujets (forum) : chaque topic = une session isolée avec son propre contexte
• Bot API mature : webhook, inline keyboards, réactions, streaming — tout est possible
• Open source : le client Telegram est open source, l'API est bien documentée et gratuite

💡 Analogie : si le terminal est le "bureau de l'agent", Telegram est son "téléphone portable" — toujours allumé, toujours joignable.

Créer un bot Telegram via @BotFather

Toute l'infrastructure Telegram repose sur un bot officiel. Voici comment le créer en 5 minutes.

Étape 1 : obtenir le token

1. Ouvrez Telegram et recherchez @BotFather
2. Envoyez /newbot
3. Choisissez un nom d'affichage (ex : "Mon Hermes Agent")
4. Choisissez un username unique terminant par bot (ex : mon_hermes_bot)
5. BotFather vous répond avec votre token API :

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

⚠️ Sécurité : gardez ce token secret. Quiconque le possède peut contrôler votre bot. S'il fuit, révoquez-le immédiatement via /revoke dans BotFather.

Étape 2 : personnaliser le bot (optionnel)

Améliorez l'expérience utilisateur avec ces commandes BotFather :

• /setdescription : texte affiché avant le premier message
• /setabouttext : description courte sur le profil
• /setuserpic : avatar du bot
• /setcommands : menu de commandes (le bouton / dans le chat)

Pour /setcommands, un bon point de départ :

help - Afficher l'aide
new - Nouvelle conversation
sethome - Définir ce chat comme canal principal
model - Changer de modèle IA
reset - Réinitialiser la session

Étape 3 : trouver votre User ID

Hermes utilise des IDs numériques pour contrôler l'accès. Ce n'est PAS votre username — c'est un nombre comme 123456789.

Envoyez un message à @userinfobot ou @get_id_bot. Notez ce numéro.

Configurer Hermes avec hermes gateway setup

Hermes offre un assistant interactif pour configurer la connexion Telegram.

Méthode interactive (recommandée)

hermes gateway setup

Sélectionnez Telegram dans le menu. L'assistant vous demande :

1. Votre bot token (celui de BotFather)
2. Vos user IDs autorisés (séparés par des virgules)
3. Il écrit automatiquement la configuration

Méthode manuelle

Ajoutez directement dans ~/.hermes/.env :

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

Pour plusieurs utilisateurs :

TELEGRAM_ALLOWED_USERS=123456789,987654321

Lancer la gateway

hermes gateway

Le bot doit apparaître en ligne en quelques secondes. Envoyez-lui un message pour vérifier.

Modes de conversation

Hermes Agent via Telegram supporte trois modes de conversation, chacun avec ses spécificités.

Mode privé (DM)

C'est le mode le plus simple. Vous chattez directement avec le bot. Chaque conversation DM obtient sa propre session avec historique, contexte et mémoire persistante.

Mode groupe

Hermes fonctionne aussi dans les groupes Telegram, mais nécessite une attention particulière au privacy mode.

Privacy mode ON (défaut) : le bot ne voit que :
- Les messages commençant par /
- Les réponses à ses propres messages
- Les messages des canaux où il est admin

Privacy mode OFF : le bot reçoit tous les messages du groupe.

Pour désactiver le privacy mode :
1. Messagez @BotFather
2. /mybots → sélectionnez votre bot
3. Bot Settings → Group Privacy → Turn off

⚠️ Important : après avoir changé le privacy mode, vous devez retirer et rajouter le bot au groupe. Telegram met en cache l'état du privacy à l'arrivée du bot.

Alternative : promouvez le bot en admin du groupe. Les admins voient tous les messages, peu importe le privacy mode.

Mode topic (forum)

Telegram Bot API 9.4 (février 2026) introduit les Private Chat Topics — des sujets de type forum directement dans les DM. Chaque topic = une session isolée.

Exemple de configuration dans ~/.hermes/config.yaml :

platforms:
  telegram:
    extra:
      dm_topics:
      - chat_id: 123456789
        topics:
        - name: General
          icon_color: 7322096
        - name: Website
          icon_color: 9367192
        - name: Recherche
          icon_color: 16766590
          skill: arxiv

💡 Le champ skill charge automatiquement un skill dans le topic. Ici, le topic "Recherche" charge le skill arxiv à chaque nouvelle session.

Gestion de plusieurs groupes et channels

Hermes peut gérer simultanément plusieurs groupes et canaux Telegram.

Contrôle par mention

Pour éviter que le bot ne réponde à tout dans un groupe actif :

telegram:
  require_mention: true
  mention_patterns:
    - "^\s*hermes\b"
  ignored_threads:
    - 31
    - "42"

Le bot répond quand :
- On utilise une commande /
- On répond à un de ses messages
- On le mentionne @botusername
- Le message correspond à un pattern (ici, commence par "hermes")

Les topics 31 et 42 sont toujours ignorés.

Allowlist par groupe

gateway:
  platforms:
    telegram:
      extra:
        group_allowed_chats:
          - "-1001234567890"
        group_allow_from:
          - "987654321"

• group_allowed_chats : tous les membres de ces groupes sont autorisés
• group_allow_from : seuls ces users spécifiques peuvent déclencher le bot dans les groupes (sans accès DM)

Home channel pour les tâches planifiées

Utilisez /sethome dans n'importe quel chat pour le désigner comme canal principal. Les résultats des tâches cron y sont livrés.

Configuration manuelle :

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Mes Notes"

💡 Les IDs de groupe sont négatifs (ex : -1001234567890). L'ID de votre DM est le même que votre user ID.

Commandes slash depuis Telegram

Depuis Telegram, vous disposez de plusieurs commandes intégrées :

• /help — afficher l'aide
• /new — démarrer une nouvelle conversation
• /reset — réinitialiser la session courante
• /model — changer de modèle IA (sélecteur interactif)
• /model <nom> — changer directement de modèle
• /model <nom> --global — rendre le changement persistant
• /sethome — définir le canal principal
• /skill-name — charger un skill (comme dans le terminal)

Le sélecteur de modèle interactif affiche des boutons inline avec navigation paginée entre providers et modèles — tout se passe dans le même message, sans encombrer le chat.

Envoi de fichiers et médias

Hermes utilise le système MEDIA: pour envoyer des fichiers via Telegram. Le gateway détecte les balises MEDIA:/chemin/vers/fichier dans les réponses de l'agent et les envoie comme pièces jointes natives.

Extensions supportées

• Images : png, jpg, jpeg, gif, webp, bmp, tiff, svg
• Audio : mp3, wav, ogg, m4a, opus, flac, aac
• Vidéo : mp4, mov, webm, mkv, avi
• Documents : pdf, txt, md, csv, json, xml, html, yaml, yml, log
• Bureautique : docx, xlsx, pptx, odt, ods, odp
• Archives : zip, rar, 7z, tar, gz, bz2

Piège Docker

Si votre backend terminal est Docker, les fichiers générés dans le container ne sont pas accessibles au gateway qui tourne sur l'hôte. Solution :

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/.hermes/cache/documents:/output"

Puis l'agent écrit dans /output/... dans Docker et émet le chemin hôte dans MEDIA:.

Messages vocaux

• Entrant : automatiquement transcrit via Whisper (local, Groq ou OpenAI)
• Sortant : les réponses TTS sont livrées comme bulles vocales natives Telegram
• Edge TTS nécessite ffmpeg pour la conversion Opus : sudo apt install ffmpeg

Formatage Markdown dans Telegram

Telegram utilise son propre format MarkdownV2, mais Hermes normalise automatiquement le rendu :

• Tables petites → converties en listes à puces par groupe de lignes
• Tables larges → blocs de code avec colonnes alignées
• Lien previews → désactivables via disable_link_previews: true

telegram:
  pretty_tables: true  # activé par défaut

Sécurité : allowlist et restriction d'accès

La sécurité est primordiale quand votre agent IA est exposé sur Telegram.

Couches de sécurité

1. TELEGRAM_ALLOWED_USERS : seuls ces users peuvent utiliser le bot (DMs + groupes)
2. TELEGRAM_GROUP_ALLOWED_USERS : autorisations spécifiques aux groupes (sans accès DM)
3. TELEGRAM_GROUP_ALLOWED_CHATS : tout membre de ces groupes est autorisé
4. require_mention : le bot ne répond que sur mention explicite
5. mention_patterns : patterns regex pour déclencher le bot
6. Exec Approval : les commandes dangereuses demandent confirmation ("yes"/"no")

Exemple de configuration sécurisée

TELEGRAM_ALLOWED_USERS=123456789
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890
TELEGRAM_REACTIONS=true

telegram:
  require_mention: true
  reactions: true

Les réactions (👀 → ✅/❌) donnent un retour visuel sur le traitement des messages.

Désactiver les previews de liens

Pour éviter les fuites d'informations via les previews :

gateway:
  platforms:
    telegram:
      extra:
        disable_link_previews: true

Gestion des files de messages

Hermes traite les messages de manière séquentielle par session. Quand vous envoyez plusieurs messages rapidement, ils sont mis en file et traités dans l'ordre. Chaque session (DM, topic, groupe) a sa propre file.

Pour les déploiements à haute charge, Hermes supporte le webhook mode — Telegram pousse les mises à jour vers votre URL HTTPS au lieu que le gateway interroge en continu :

TELEGRAM_WEBHOOK_URL=https://mon-app.fly.dev/telegram
TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)"

Le mode webhook est idéal pour les plateformes cloud (Fly.io, Railway, Render) avec auto-wake — la machine peut dormir entre les messages.

Cas d'usage concrets

1. Bot de support technique

Configurez Hermes dans un groupe support avec un skill dédié :

platforms:
  telegram:
    extra:
      group_topics:
      - chat_id: -1001234567890
        topics:
        - name: Support
          thread_id: 5
          skill: customer-support

Hermes répond automatiquement aux questions techniques avec le contexte de votre documentation.

2. Veille automatisée

Combinez le home channel avec les tâches planifiées :

TELEGRAM_HOME_CHANNEL=-1001234567890

Configurez un cron job dans Hermes qui fait une synthèse quotidienne de l'actualité tech et la livre dans votre canal Telegram.

3. Assistant personnel multi-projets

Utilisez les DM topics pour séparer vos projets :

• Topic "Dev" avec skill software-development — discussions code
• Topic "Rédaction" — rédaction d'articles et contenu
• Topic "Admin" — gestion système et DevOps

Chaque topic a sa session isolée, son historique et son contexte propre.

4. Automation d'équipe

Un groupe partagé avec allowlist par chat — tous les membres de l'équipe peuvent interagir avec l'agent sans configuration individuelle :

group_allowed_chats:
  - "-1001234567890"

Déployer en 24/7 avec systemd

Pour que votre gateway Telegram tourne en permanence sur un VPS, utilisez systemd.

💡 Hébergement : pour un VPS fiable et abordable, nous recommandons Hostinger — performances excellentes pour l'exécution d'agents IA.

Service systemd

Créez /etc/systemd/system/hermes-gateway.service :

[Unit]
Description=Hermes Agent Gateway (Telegram)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=hermes
WorkingDirectory=/home/hermes
ExecStart=/usr/local/bin/hermes gateway
Restart=always
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable hermes-gateway
sudo systemctl start hermes-gateway
sudo systemctl status hermes-gateway

Logs en temps réel :

journalctl -u hermes-gateway -f

Dépannage courant

Conclusion

Connecter Hermes Agent à Telegram transforme votre agent IA d'un outil de terminal en un assistant personnel accessible partout. La configuration prend moins de 5 minutes, et les possibilités sont vastes : DM privé, groupes collaboratifs, topics isolés par projet, messages vocaux, envoi de fichiers natifs, et déploiement 24/7 via systemd.

Les couches de sécurité (allowlists, require_mention, exec approval) garantissent que seul le personnel autorisé interagit avec l'agent, même dans des groupes publics.

Pour aller plus loin, explorez le système de Skills qui permet de charger des compétences spécialisées automatiquement dans chaque topic, la mémoire persistante pour que l'agent se souvienne de vos préférences, ou les fichiers de contexte pour personnaliser son comportement par projet.

Et si vous débutez avec Hermes, notre présentation complète vous guidera à travers l'installation et la configuration initiale.