Canaux et gateway : connecter Telegram, Discord, Slack, WhatsApp et Home Assistant a Hermes Agent

Introduction

Le gateway de messagerie est le composant de Hermes Agent qui le rend accessible depuis vos plateformes de messagerie quotidiennes. C'est un processus unique qui se connecte simultanement a toutes les plateformes configurees -- Telegram, Discord, Slack, WhatsApp, Home Assistant, et plus de 15 autres --, gere les sessions de conversation, execute les taches cron et delivre les messages vocaux.

Cette page couvre la connexion aux cinq plateformes les plus demandees, l'installation du gateway comme service systeme, la gestion des autorisations utilisateur, l'envoi de messages sortants depuis un script, le diagnostic des pannes de reception et l'isolation des sessions multi-utilisateurs.

Pour une vue d'ensemble de toutes les plateformes supportees et de leurs capacites (voix, images, fichiers, fils de discussion, reactions, streaming), consultez la documentation officielle du gateway.

Questions couvertes

q-121: Comment connecter Telegram a Hermes Agent ?

Telegram est la plateforme la plus riche en fonctionnalites pour Hermes Agent : voix, images, fichiers, fils de discussion, indicateur de frappe et streaming sont tous supportes.

Etape 1 : Creer un bot via BotFather

Ouvrez Telegram, cherchez @BotFather et envoyez /newbot. Choisissez un nom d'affichage et un nom d'utilisateur (qui doit se terminer par bot). BotFather vous remet un token API de la forme 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ. Conservez-le secret : quiconque le possede controle votre bot.

Etape 2 : Configurer Hermes

La methode recommandee est l'assistant interactif :

hermes gateway setup

Selectionnez Telegram dans le menu, collez le token, et l'assistant ecrit la configuration. Vous pouvez aussi configurer manuellement dans ~/.hermes/config.yaml :

gateway:
  platforms:
    telegram:
      enabled: true
      token: "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"

Etape 3 : Demarrer le gateway

hermes gateway start

Votre bot Telegram est operationnel. Envoyez-lui un message direct pour verifier.

Points d'attention :

• Mode Privacy pour les groupes : par defaut, un bot Telegram ne voit que les messages qui commencent par / ou qui le mentionnent. Pour qu'il voie tous les messages d'un groupe, desactivez le mode privacy via /setprivacy dans BotFather.
• Groupes : utilisez allow_from pour restreindre les groupes autorises. Le bot repond dans les groupes seulement quand il est mentionne, sauf configuration contraire.
• Voice : les messages vocaux Telegram sont automatiquement transcrits (speech-to-text). Les reponses vocales (text-to-speech) sont activees avec /voice on.
• Webhook : pour les deploiements cloud, Telegram supporte le mode webhook en alternative au polling. Consultez la documentation Telegram pour la configuration.

q-122: Comment connecter Discord a Hermes Agent ?

Discord offre le support le plus complet apres Telegram : voix, images, fichiers, fils de discussion, reactions, indicateur de frappe et streaming.

Etape 1 : Creer une application Discord

Allez sur le portail developpeur Discord, creez une nouvelle application, puis allez dans Bot et copiez le token du bot.

Etape 2 : Inviter le bot sur votre serveur

Dans l'onglet OAuth2 > URL Generator, selectionnez le scope bot et les permissions Send Messages, Read Message History, Attach Files, Use Slash Commands. Ouvrez l'URL generee pour inviter le bot.

Etape 3 : Configurer Hermes

Via l'assistant interactif :

hermes gateway setup

Ou manuellement dans ~/.hermes/config.yaml :

gateway:
  platforms:
    discord:
      enabled: true
      token: "VOTRE_TOKEN_DISCORD"
      extra:
        allow_from: ["111", "222", "333"]

Les identifiants dans allow_from sont les Discord User IDs (activez le mode developpeur dans Discord pour les obtenir : clic droit sur un utilisateur > Copier l'ID).

Comportement par defaut :

• DMs : le bot repond a chaque message, sans mention necessaire. Chaque DM a sa propre session.
• Salons serveur : le bot ne repond que lorsqu'il est @mentionne. Pour des salons sans mention, utilisez DISCORD_FREE_RESPONSE_CHANNELS.
• Sessions multi-utilisateurs : par defaut, group_sessions_per_user: true isole les sessions par utilisateur dans un meme salon. Deux personnes qui parlent dans #recherche ne partagent pas le meme historique.

Voice sur Discord : Hermes Agent peut rejoindre un canal vocal Discord. Utilisez /voice join dans un salon texte pour le faire rejoindre le canal vocal associe, puis /voice leave pour le deconnecter.

q-123: Comment connecter Slack a Hermes Agent ?

Slack utilise le Socket Mode (WebSocket), ce qui signifie que votre instance Hermes n'a pas besoin d'etre accessible publiquement -- elle fonctionne derriere un pare-feu, sur un laptop ou un serveur prive.

Etape 1 : Generer le manifeste

Hermes peut generer un manifeste Slack complet qui declare toutes les commandes slash, les scopes OAuth et les abonnements aux evenements :

hermes gateway manifest slack

Cette commande ecrit un fichier slack_app_manifest.json et affiche les instructions pour le coller.

Etape 2 : Creer l'application Slack

Allez sur api.slack.com/apps, cliquez sur Create New App, choisissez From an app manifest, selectionnez votre workspace, collez le contenu du manifeste, revisez et cliquez sur Create.

Etape 3 : Installer l'application sur le workspace

Dans l'interface de l'application Slack, allez dans Install App et cliquez sur Install to Workspace. Vous obtenez un Bot Token (xoxb-...) et un App-Level Token (xapp-...).

Etape 4 : Configurer Hermes

hermes gateway setup

Ou manuellement :

gateway:
  platforms:
    slack:
      enabled: true
      bot_token: "xoxb-..."
      app_token: "xapp-..."

Points d'attention :

• Tokens : le Bot Token (xoxb-) et l'App-Level Token (xapp-) sont tous deux obligatoires.
• Identification utilisateur : les utilisateurs sont identifies par leur Slack Member ID (ex. U01ABC2DEF3).
• Scopes : sans channels:history et groups:history, le bot ne recoit pas les messages dans les salons. Sans files:read, il ne peut pas lire les pieces jointes.
• Indicateur de frappe : Slack affiche "is thinking..." pendant le traitement. Desactivez-le avec typing_indicator: false si vous le trouvez genant.

q-124: Comment connecter WhatsApp a Hermes Agent ?

Hermes Agent se connecte a WhatsApp via un pont base sur Baileys, qui emule une session WhatsApp Web. Aucun compte Meta Business ni verification Business n'est requis.

Deux modes :

Etape 1 : Lancer l'assistant

hermes whatsapp

L'assistant vous demande le mode (bot ou self-chat), installe les dependances du pont si necessaire, puis affiche un QR code dans le terminal.

Etape 2 : Scanner le QR code

Ouvrez WhatsApp sur votre telephone, allez dans Parametres > Appareils connectes > Connecter un appareil, et scannez le QR code. Une fois apparie, la session est sauvegardee automatiquement.

Etape 3 : Configurer Hermes

Ajoutez dans ~/.hermes/.env :

WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot
WHATSAPP_ALLOWED_USERS=15551234567

Les numeros sont au format international sans le +.

Avertissements :

• Risque de bannissement : WhatsApp ne supporte pas officiellement les bots tiers hors Business API. Utilisez un numero dedie, ne faites pas de spam, et n'automatisez pas l'envoi sortant vers des personnes qui n'ont pas ecrit en premier.
• Protocole Web : WhatsApp met a jour periodiquement son protocole Web, ce qui peut casser temporairement la compatibilite. Mettez a jour Hermes (hermes update) et re-appariez si le bot cesse de fonctionner apres une mise a jour WhatsApp.
• Prerequis : Node.js v18+ et npm sont necessaires pour le pont Baileys.

Pour un usage professionnel stable, utilisez la WhatsApp Business Cloud API (necessite un compte Meta Business et une URL de webhook publique).

q-125: Comment connecter Home Assistant a Hermes Agent ?

Home Assistant s'integre comme une plateforme de messagerie a part entiere, avec quatre outils dedies pour le controle domotique.

Etape 1 : Creer un token d'acces

Dans votre instance Home Assistant, allez dans votre Profil (cliquez sur votre nom dans la barre laterale), descendez jusqu'a Long-Lived Access Tokens, cliquez sur Create Token, donnez-lui un nom comme "Hermes Agent", et copiez le token.

Etape 2 : Configurer les variables d'environnement

Dans ~/.hermes/.env :

HASS_TOKEN=votre-token-longue-duree
HASS_URL=http://192.168.1.100:8123

HASS_URL est optionnel et pointe par defaut vers http://homeassistant.local:8123.

Etape 3 : Demarrer le gateway

hermes gateway start

Home Assistant apparait comme une plateforme connectee aux cotes de Telegram, Discord, etc.

Outils domotiques actives automatiquement :

Des que HASS_TOKEN est configure, le toolset hermes-homeassistant s'active avec quatre outils :

• ha_list_entities : lister toutes les entites disponibles
• ha_get_state : obtenir l'etat d'une entite specifique
• ha_list_services : lister les services disponibles
• ha_call_service : appeler un service (allumer une lumiere, regler un thermostat, etc.)

Filtrage des evenements (optionnel) :

Pour limiter les evenements que le gateway ecoute, configurez watch_domains et watch_entities dans ~/.hermes/config.yaml :

gateway:
  platforms:
    homeassistant:
      enabled: true
      extra:
        watch_domains:
          - climate
        - light
        watch_entities:
          - sensor.front_door_battery
        ignore_entities:
          - sensor.uptime
        cooldown_seconds: 30

q-126: Comment installer le gateway Hermes Agent comme service ?

Le gateway peut etre installe comme service systeme pour demarrer automatiquement au boot et survivre aux deconnexions.

Linux (systemd) :

# Service utilisateur (recommande pour laptops et machines de dev)
hermes gateway install

# Service systeme (recommande pour VPS et serveurs headless)
sudo hermes gateway install --system

Commandes de gestion :

hermes gateway start
hermes gateway stop
hermes gateway restart
hermes gateway status

Service utilisateur + linger pour VPS headless :

Un service systeme necessite sudo pour chaque redemarrage, y compris le redemarrage automatique apres hermes update. Pour un VPS headless, un service utilisateur avec linger donne le meme comportement au boot sans privileges root :

sudo loginctl enable-linger $USER
hermes gateway install

Apres cela, hermes update peut redemarrer le gateway sans mot de passe.

macOS (launchd) :

hermes gateway install

Le plist est cree dans ~/Library/LaunchAgents/ai.hermes.gateway.plist. Il capture votre PATH au moment de l'installation. Si vous installez de nouveaux outils (Node.js, ffmpeg) apres coup, re-executez hermes gateway install pour mettre a jour le PATH.

Watchdog systemd (Linux uniquement) :

Pour detecter les blocages de la boucle evenementielle Python, activez le watchdog dans ~/.hermes/config.yaml :

gateway:
  systemd_watchdog_seconds: 120

Puis regenerer l'unite de service :

hermes gateway install

Le gateway envoie des heartbeat tant que sa boucle evenementielle progresse. Systemd le redemarre si les heartbeat s'arretent. La valeur 0 (defaut) conserve le comportement Type=simple.

Installations multiples :

Si vous avez plusieurs installations Hermes avec des repertoires HERMES_HOME differents, chacune obtient son propre nom de service : hermes-gateway pour ~/.hermes, hermes-gateway-<hash> pour les autres.

q-127: Comment autoriser un utilisateur avec le systeme de pairing ?

Le systeme de pairing permet d'autoriser des utilisateurs sans pre-configurer leurs identifiants. Quand un utilisateur inconnu envoie un message direct au bot, il recoit un code de pairing a usage unique.

Activer le pairing :

Dans ~/.hermes/config.yaml :

gateway:
  unauthorized_dm_behavior: pair

Par defaut, le gateway refuse tous les utilisateurs qui ne sont pas dans une allowlist ou apparies via DM. Le pairing est une alternative aux allowlists manuelles.

Fonctionnement :

1. Un utilisateur inconnu envoie un DM au bot.
2. Le bot repond avec un code de pairing (ex. XKGH5N7P).
3. L'administrateur approuve le code via la CLI.
4. L'utilisateur est definitivement autorise pour cette plateforme.

Commandes de gestion :

# Lister les utilisateurs en attente et approuves
hermes pairing list

# Approuver un code de pairing
hermes pairing approve telegram ABC12DEF

# Revoquer l'acces d'un utilisateur
hermes pairing revoke telegram 123456789

# Supprimer tous les codes en attente
hermes pairing clear-pending

Securite :

• Les codes de pairing expirent apres 1 heure.
• Ils sont limites en debit (rate-limited).
• Ils utilisent une generation cryptographique aleatoire.
• L'email est une exception : les expéditeurs inconnus sont ignores sauf si le pairing email est explicitement active.

Docker : les commandes de pairing doivent etre executees en tant qu'utilisateur hermes dans le conteneur :

docker exec -u hermes hermes-agent hermes pairing approve telegram ABC12DEF

Admins vs utilisateurs reguliers :

Une fois autorise, un utilisateur peut etre admin ou simple utilisateur. Les admins ont acces a toutes les commandes slash ; les utilisateurs reguliers n'ont acces qu'aux commandes explicitement autorisees (user_allowed_commands). Le minimum toujours autorise est /help et /whoami.

q-128: Comment envoyer un message sortant depuis un script ?

Plusieurs mecanismes permettent d'envoyer des messages sortants depuis un script ou un processus externe.

1. Cron avec livraison (recommande) :

La methode la plus integree est un cron Hermes Agent avec l'option --deliver. Le resultat de la tache est livre sur la plateforme de votre choix :

hermes cron create "0 */6 * * *" \
  "Verifie la sante de tous les services et resume en 3 lignes" \
  --name "Verification des services" \
  --deliver telegram

Les crons peuvent livrer sur Telegram, Discord, Slack, et d'autres plateformes. Voir la page Automatiser pour le detail complet.

2. Webhooks :

Le gateway expose un serveur API qui accepte des requetes HTTP entrantes. Configurez un webhook dans ~/.hermes/config.yaml et envoyez des requetes POST authentifiees par HMAC-SHA256. Le contenu du message est traite par l'agent et la reponse est delivree sur la plateforme configurer.

3. Commande /background :

Depuis n'importe quelle plateforme connectee, lancez une tache en arriere-plan :

/background Verifie la sante de tous les serveurs et alerte-moi si quelque chose ne va pas

Le resultat est delivre automatiquement dans le chat d'origine quand la tache se termine.

4. API Server :

Le toolset hermes-api-server permet un acces programmatique complet. Activez-le dans la configuration pour exposer une API REST que vos scripts peuvent appeler.

5. Cron en mode script (sans agent) :

Pour des taches deterministes sans cout LLM, utilisez no_agent=True :

hermes cron create "0 9 * * *" \
  --script "rapport-quotidien.sh" \
  --no-agent \
  --name "Rapport quotidien" \
  --deliver telegram

q-129: Comment diagnostiquer un gateway qui ne recoit plus les messages ?

Quand le gateway cesse de recevoir des messages, suivez cette procedure de diagnostic en couches.

1. Verifier l'etat du gateway :

hermes gateway status

Si le gateway n'est pas en cours d'execution, demarrez-le :

hermes gateway start

2. Consulter les logs :

cat ~/.hermes/logs/gateway.log | tail -50

Cherchez les motifs ERROR, WARNING, circuit breaker, ou paused. Les logs indiquent souvent la cause exacte.

3. Verifier l'etat des adaptateurs :

Depuis n'importe quelle plateforme connectee, utilisez la commande slash :

/platform list

Cela affiche l'etat de chaque adaptateur : running, paused (pause manuelle), ou paused-by-breaker (disjoncteur declenche automatiquement).

4. Disjoncteur automatique (circuit breaker) :

Chaque adaptateur est protege par un disjoncteur. Des echecs repetes (coupures reseau, reponses 5xx, rate-limiting, deconnexions WebSocket) declenchent une pause automatique. Le disjoncteur ne se rearme pas automatiquement -- c'est intentionnel pour eviter les rafales de reconnexion.

Pour reprendre :

/platform resume telegram

Avant de reprendre, verifiez que la plateforme upstream est en bonne sante (statut de l'API Telegram, statut Discord, etc.).

5. Verifier les dependances :

cd ~/.hermes/hermes-agent && uv pip install -e ".[messaging]"

6. Verifier les conflits de port :

lsof -i :8080

7. Verifier la configuration :

hermes config show

8. Pour les plateformes webhook (Slack, WhatsApp Cloud API) :

Assurez-vous que votre serveur est accessible publiquement et que l'URL du webhook est correctement configuree.

9. Mode foreground pour diagnostic :

Lancez le gateway en mode foreground pour voir les logs en direct :

hermes gateway run

10. WSL :

Sur WSL, le gateway peut se deconnecter. Utilisez tmux ou nohup :

tmux new -s hermes 'hermes gateway run'
# Pour rattacher plus tard : tmux attach -t hermes

q-130: Comment isoler les sessions de plusieurs utilisateurs sur le meme gateway ?

Hermes Agent propose plusieurs mecanismes pour isoler les sessions de plusieurs utilisateurs partageant le meme gateway.

1. Isolation par defaut (par utilisateur) :

Sur Discord, le comportement par defaut est group_sessions_per_user: true. Dans un salon partage, chaque utilisateur a sa propre session isolee. Alice et Bob qui parlent dans #recherche ne partagent ni historique ni contexte.

Pour desactiver cette isolation et avoir une session partagee pour tout le salon :

gateway:
  platforms:
    discord:
      extra:
        group_sessions_per_user: false

Attention : une session partagee signifie que les utilisateurs partagent la croissance du contexte et les couts de tokens, et qu'une tache longue d'un utilisateur peut gonfler le contexte de tous les autres.

2. Profils separes (agents differents) :

Pour une isolation complete (configurations, cles API, memoire, skills et sessions distincts), creez des profils Hermes Agent separes :

hermes -p alice setup
hermes -p bob setup

Chaque profil a son propre gateway, ses propres tokens de bot, et sa propre base de sessions. Voir la page Profils et delegation pour le detail complet.

3. Multiplexage de profils sur un seul gateway :

Pour eviter de lancer plusieurs processus gateway, utilisez le multiplexage :

gateway:
  multiplex_profiles: true
  profile_routes:
    - name: equipe-dev
      platform: discord
      guild_id: "1234567890"
      profile: dev
    - name: equipe-support
      platform: discord
      guild_id: "1234567890"
      chat_id: "9876543210"
      profile: support
    - name: groupe-telegram
      platform: telegram
      chat_id: "-1001234567890"
      profile: tg-profile

Un seul processus gateway route les messages vers le profil approprie en fonction de la plateforme, du serveur et du salon d'origine.

4. Allowlists et controle d'acces :

Restreignez quels utilisateurs peuvent acceder au bot sur chaque plateforme :

gateway:
  platforms:
    discord:
      extra:
        allow_from: ["111", "222", "333"]
        allow_admin_from: ["111"]
        user_allowed_commands: [status, model]

Les utilisateurs non listes sont refuses. Combinez avec le systeme de pairing pour une autorisation dynamique.

5. DM pairing pour l'auto-enregistrement :

Activez unauthorized_dm_behavior: pair pour que les nouveaux utilisateurs recoivent un code de pairing plutot que d'etre refuses silencieusement. L'administrateur approuve les codes via hermes pairing approve.

Sources

• Documentation officielle Hermes Agent -- Messaging Gateway (https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)
• Documentation officielle Hermes Agent -- Telegram Setup (https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram)
• Documentation officielle Hermes Agent -- Discord Setup (https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord)
• Documentation officielle Hermes Agent -- Slack Setup (https://hermes-agent.nousresearch.com/docs/user-guide/messaging/slack)
• Documentation officielle Hermes Agent -- WhatsApp Setup (https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp)
• Documentation officielle Hermes Agent -- Home Assistant Integration (https://hermes-agent.nousresearch.com/docs/user-guide/messaging/homeassistant)
• Documentation officielle Hermes Agent -- Security (https://hermes-agent.nousresearch.com/docs/user-guide/security)
• Documentation officielle Hermes Agent -- FAQ (https://hermes-agent.nousresearch.com/docs/reference/faq)
• Documentation officielle Hermes Agent -- Profiles (https://hermes-agent.nousresearch.com/docs/user-guide/profiles)
• Documentation officielle Hermes Agent -- Multi-Profile Gateways (https://hermes-agent.nousresearch.com/docs/user-guide/multi-profile-gateways)
• Depot GitHub NousResearch/hermes-agent, commit b4f8c491

Liens internes proposes

• Configurer Hermes Agent
• Securite
• Automatiser
• Depannage
• Profils et delegation
• FAQ
• Comprendre Hermes Agent
• Sources
• Methodologie