HHermes Explained

Interfaces

Telegram Gateway

A mobile control surface that routes Telegram messages into Hermes sessions.

Importance 4/59 backlinks1 source refs

Telegram Gateway

What it is

A mobile control surface that routes Telegram messages into Hermes sessions.

In plain terms

Picture a single phone line wired straight into that mail depot, except this one can split into private extensions too — Telegram’s ‘topics’ — so a work thread and a personal thread don’t get tangled into one shared inbox. Only numbers already on the door’s guest list get through, unless the office manager has decided to leave that particular door open to everyone.

Why it matters

Messages from a Telegram chat route directly into a Hermes session through this gateway, which is what makes a phone a legitimate control surface for the agent rather than just a notification channel. It shows up as the most commonly used mobile entry point across the beginner-route content, likely because Telegram’s bot API is straightforward to wire up compared to platforms requiring more elaborate approval flows. Like WhatsApp and Discord, it shares the underlying gateway service rather than running its own separate connection layer.

How it works

TelegramAdapter (plugins/platforms/telegram/adapter.py) subclasses the shared platform-adapter base and keeps a connection open by long-polling Telegram’s servers through python-telegram-bot’s start_polling, rather than requiring a public webhook URL reachable from the open internet — workable for a laptop or home server with no fixed address. A retry ladder watches for stalled connections and can fall back to a direct-IP network path if the usual one degrades. Thread routing runs through shared adapter code (gateway/platforms/base.py), which maps Telegram’s forum topics and private-chat ‘DM topics’ onto Hermes’s own thread_id concept, so a reply lands back in the exact lane the question came from instead of the main chat. Which numbers are allowed through comes from an environment variable the adapter checks per sender; a separate variable, read by Hermes’s cron scheduler rather than the adapter itself, decides which chat gets cron or notification output by default.

A concrete example

A user texts the Hermes bot inside a private Telegram topic they set up for household groceries.

  1. The message arrives over the open long-poll connection, tagged with that topic’s thread ID.
  2. Hermes checks the sender’s Telegram ID against the allowlist, finds a match, and hands the text to the agent session already tracking that topic.
  3. The agent adds two items to a saved shopping list and writes a short reply.
  4. Because the reply carries the same thread ID back, it appears inside the groceries topic rather than the bot’s general chat.

How it connects

This note belongs to the Interfaces family. Its closest neighboring concepts are: Gateway, WhatsApp Gateway, Agent Runtime, Personal OS.

Source evidence

  • plugin:platforms/telegram — Explicit Source Map scope boundary: The platform plugin is outside the approved Core scope.

Workflows

  • Gateway Mobile Command Center
  • Hermes Agent 完整入門：打造安全、可持續成長的私人 AI 助理
  • Ten Hermes Workflows That Turn a Chatbot into a 24/7 Assistant
  • From Zero to a Personal AI Assistant: Building Hermes on a VPS Without Creating a Mess
  • Hermes Agent for Beginners: A Step-by-Step Route from Empty Server to Useful Automation
  • Building a Personal AI System with Hermes, Local Models, Automation, and a Shared Knowledge Base
  • Ten Underused Hermes Features That Reveal Its Real Power
  • Inside Hermes: How the Agent Loop, Context, Memory, Gateways, and Cron Jobs Work Together