Hermes Agent + Telegram : le bot AI au petit oignon

🎙️ Podcast : Écouter

Je vais pas te mentir, j'ai passé des heures à configurer des bots Telegram avant Hermes. Token ici, webhook là, une couche de Flask pour faire le relais, un cron pour le keepalive, et à la fin t'as un bot qui répond "pong" et c'est tout.

Hermes Agent a changé la donne. Nous Research a fait le boulot — et le résultat, c'est que configurer un agent Telegram complet prend littéralement 5 minutes de setup et 10 minutes de polish. Le reste, c'est le gateway qui le fait.

Parlons de ce qui est arrivé récemment, parce que Hermes a pris pas mal de features Telegram dans ses dernières versions (v0.14 à v0.16), et tout ça cumulé fait une stack sacrément propre.

Ce que Hermes apporte aujourd'hui sur Telegram

Le gateway Hermes est un processus unique qui connecte 20+ plateformes. Telegram est clairement la mieux équipée — et c'est voulu. Voilà ce qui tourne aujourd'hui.

Les réactions. T'as déjà envoyé un message à un bot et attendu 30 secondes sans savoir s'il t'a entendu ? Hermes répond avec 👀 pendant qu'il réfléchit, ✅ quand c'est fait, ❌ si ça a merdé. C'est bête comme un truc, mais ça change tout le ressenti. Tu parles pas à un trou noir.

Le streaming en temps réel. Le bot peut t'écrire token par token, comme ChatGPT. Pas de "typing..." qui dure 2 minutes puis un mur de texte qui tombe — tu vois la réponse arriver en direct.

Les messages enrichis. Tableaux, task lists, formules mathématiques — tout passe nativement en Markdown Telegram. C'est opt-in (rich_messages: true dans la config), mais une fois activé, l'agent peut te sortir des tableaux de benchmarks sans se galérer. Pratique.

La voix — dans les deux sens. Tu envoies un vocal, il est transcrit automatiquement (Whisper local ou Groq/OpenAI), et l'agent peut répondre avec sa propre voix en MP3/Ogg natif. Edge TTS, Grok, OpenAI — le provider est configurable.

Les topics privés. Bot API 9.4 permet d'avoir des workspaces isolés dans un même DM. Tu peux avoir un topic "Dev" qui charge automatiquement tes skills de coding, un topic "Veille" avec les skills de recherche. Chaque topic est une conversation indépendante.

Le multi-session avec /topic. Même principe mais en dynamique : tu tapes /topic dans le DM racine, ça crée une session parallèle. Tu peux en avoir 5 en cours, passer de l'une à l'autre avec /topic <id>. Utile quand tu gères plusieurs contextes en même temps.

Le mode webhook. Parfait pour les déploiements cloud (Fly.io, Railway) — le bot peut s'endormir entre les messages et se réveiller à la demande. Plus besoin de garder un processus poller qui tourne H24.

Les fallbacks réseau. DNS-over-HTTPS, proxy SOCKS5, IP de fallback hardcodée — si t'es derrière un firewall qui bloque api.telegram.org, Hermes trouve un chemin. C'est du détail technique, mais c'est le genre de truc qui te sauve un déploiement à 23h.

Et les crons, évidemment. Un bot Telegram qui peut te poster un rapport de santé serveur toutes les 6h, le Morning Brief à 6h30, les alertes disque — tout ça sans que tu demandes. La config cron d'Hermes livre directement sur Telegram.

Bon. Venons-en au sujet principal.

Configurer un bot Telegram pour Hermes — version "au petit oignon"

L'idée, c'est pas juste de faire fonctionner le truc. C'est d'avoir un bot sécurisé, réactif, qui gère les groupes, la voix, et qui te donne pas envie de l'éteindre au bout de 3 jours.

Étape 1 — Le bot lui-même

Va voir @BotFather sur Telegram. /newbot, un nom, un username qui finit par _bot. Tu récupères un token qui ressemble à ça : 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ.

Astuce : utilise directement /setcommands avec ça :

help - Aide et infos
new - Nouvelle conversation
model - Voir/changer le modèle
status - Infos session
stop - Arrêter la tâche en cours
sethome - Définir ce chat comme home channel

Tes commandes apparaîtront dans le menu du bot. Fait pro.

Trouve ton user ID. Message à @userinfobot ou @getidsbot. Il te renvoie un nombre à 9-10 chiffres. C'est ton identifiant Telegram. Note-le.

Étape 2 — Hermes côté serveur

Le plus court chemin :

hermes gateway setup

Assistant interactif, il te demande le token, ton user ID, et configure le .env automatiquement.

Si tu préfères le faire à la main, dans ~/.hermes/.env (ou ~/.hermes/profiles/<profile>/.env si t'as plusieurs profils) :

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=8122470680
TELEGRAM_HOME_CHANNEL=8122470680

La hiérarchie : y'a un .env global (~/.hermes/.env) et un par profil. Le profile écrase le global. Si t'as plusieurs profils, mets le token dans le profile, pas dans le global.

Vérifie le token avant de lancer :

curl -s "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getMe"

Tu devrais voir {"ok":true,"result":{...}} avec ton bot ID. Si c'est 401, ton token est invalide.

Étape 3 — La config qui fait la différence

Le vrai setup, c'est dans config.yaml. Voilà une config complète qui gère :

Les réactions (👀✅❌)
Le streaming token par token
Les messages enrichis (tableaux, maths)
La sécurité groupe
Les commandes pour utilisateurs normaux vs admins

telegram:
  allowed_chats:
    - '-1004489857282'
  allow_from:
    - '8122470680'
  group_allow_from:
    - '8122470680'
  reply_to_mode: off
  reactions: true
  rich_messages: true
  extra:
    free_response_chats:
      - -1004489857282
    allow_admin_from:
      - '8122470680'
    user_allowed_commands:
      - status
      - model
      - help
      - new
      - stop

Décryptage rapide :

reactions: true — active 👀 pendant la réflexion, ✅/❌ à la fin. Ça change tout en terme de feedback utilisateur.
rich_messages: true — l'agent peut envoyer des tableaux, listes à puces, formules. Opt-in, mais à activer.
free_response_chats — le bot répond dans le groupe sans avoir besoin d'être mentionné. Sans ça, il ignore tout sauf /command et @mention.
reply_to_mode: off — le bot arrête de quote ton message à chaque réponse. Plus propre.
allow_admin_from + user_allowed_commands — toi t'as accès à toutes les commandes, les autres membres du groupe ne peuvent utiliser que status/model/help/new/stop. Pas de terminal pour les invités.
allowed_chats + allow_from — double filtre : qui peut parler au bot (user ID) et où (chat ID). Sans ça, n'importe qui qui trouve ton bot peut l'utiliser.

Étape 4 — Voice + STT

Si tu veux que ton bot réponde aux vocaux et parle :

Dans .env :

# Pour la transcription des vocaux entrants
WHISPER_MODEL=base          # local, plus privé
# ou
STT_PROVIDER=groq           # plus rapide, cloud

# Pour la réponse vocale
TTS_PROVIDER=edge           # gratuit, voix HenriNeural, nécessite ffmpeg

Note : Edge TTS a besoin de ffmpeg pour convertir en Ogg/Opus (le format natif des voice bubbles Telegram). Si t'as pas ffmpeg, les réponses vocales seront envoyées comme fichiers audio, pas comme voice bubbles.

Pour les fichiers lourds (>20MB), t'as besoin de déployer ton propre Bot API Server local. Hermes le supporte, mais c'est une étape supplémentaire. Pour 95% des usages, les 20MB du cloud Telegram suffisent.

Étape 5 — Group Privacy (le piège classique)

Par défaut, un bot Telegram ne voit PAS les messages des groupes. Il voit seulement ceux qui le mentionnent ou les commandes.

Deux solutions :

BotFather → /mybots → Bot Settings → Group Privacy → Disable. Puis supprime le bot du groupe et ré-ajoute-le. C'est le seul moyen : Telegram cache le statut de privacy au moment où le bot rejoint un groupe. Tant que tu le ré-ajoutes pas, il a toujours l'ancien statut.
Promote le bot en Admin du groupe. Ça bypass le privacy mode. Pratique si tu veux pas le ré-ajouter.

Étape 6 — Lancer et vérifier

# Test rapide (foreground)
hermes gateway

# Installation permanente
hermes gateway install
systemctl --user start hermes-gateway
systemctl --user status hermes-gateway

Si ça marche pas, les logs disent tout :

journalctl --user -u hermes-gateway --since "1 min ago" --no-pager

Étape 7 (bonus) — La SOUL.md

Le bot Telegram d'Hermes lit ton SOUL.md et AGENTS.md. C'est ça qui définit sa personnalité. Un bot Telegram sans SOUL.md, c'est un bot qui répond en "Hello! I'm a helpful AI assistant" — formaté, poli, chiant.

Ma SOUL.md à moi commence par "d3x. Dex version 3.0. Même ADN, nouveau châssis, moins de blabla." Et ça se ressent dans chaque réponse.

Si tu veux un agent utile et pas un drone corporate, prends 10 minutes pour écrire sa personnalité. Ça paie cent fois plus que de tweaker le prompt.

Les petits plus qui font la différence

Les topics privés (DM topics). Si t'as plusieurs projets, configure des topics dans ton DM :

platforms:
  telegram:
    extra:
      dm_topics:
      - chat_id: 8122470680
        topics:
        - name: Dev
          skill: coding-agents
        - name: Veille
          skill: morning-brief

Chaque topic charge automatiquement les skills correspondants. T'as pas à repréciser le contexte à chaque fois.

Le mode webhook. Si t'héberges sur Fly.io ou Railway :

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

Le bot s'endort entre les messages. Idéal pour les déploiements serverless où tu paies à l'activité.

Les crons avec livraison Telegram. La killer feature. Un exemple concret :

hermes cron create \
  --name "health-check" \
  --schedule "0 */6 * * *" \
  --prompt "Check disk usage, Docker status, and uptime. Report only if something is wrong." \
  --deliver telegram

Le résultat arrive directement sur Telegram. À 6h du matin, t'as un "⚠️ Disk at 87%" qui te réveille. C'est le bot qui parle, pas un système de monitoring impersonnel.

Ce qu'il faut retenir

Hermes Agent a transformé Telegram en une vraie interface d'agent AI. Pas un chatbot à réponses pré-écrites — un agent autonome avec mémoire, skills, voix, et scheduled tasks, accessible depuis ton téléphone.

Les features clés à retenir :

Réactions + streaming = fin du syndrome du trou noir
Voix bidirectionnelle = tu peux lui parler, il te répond
DM Topics + multi-session = plusieurs contextes sans t'y perdre
Groupes sécurisés = commandes admin vs user, whitelist à tous les niveaux
Crons Telegram = le bot te ping tout seul quand y'a un truc

Le setup prend 5 minutes. La config fine prend 20 minutes. Et après, t'as un agent AI qui vit dans ta poche, répond sur Telegram, et fait tourner ton infrastructure sans que tu lèves le petit doigt.

Et franchement, pour quelqu'un qui a bricolé des bots Telegram avec des scripts Python et des webhooks Flask, la différence est saisissante. C'est comme passer d'une mobylette à une Tesla — les deux vont quelque part, mais l'expérience de conduite n'a rien à voir.

Si tu veux creuser, la doc Telegram Hermes est bien foutue. Et pour la config avancée (pairing team, exec approval, isolation Docker), le guide Team Telegram Assistant est la référence.