Hermes Agent

Integration

Hermes Agent on Telegram

Connect Hermes Agent to Telegram with QR or BotFather setup. Understand user access, topics, offline messages, and how to verify a real reply.

Quick answer

Hermes connects to Telegram through a gateway running on your machine or host. Current dashboard and Desktop builds offer Messaging → Telegram → Create with QR; manual BotFather setup also works. Authorize your human account and prove one private reply before adding groups. A connected status alone does not prove the model completed a turn or Telegram delivered it.

Get Hermes in Telegram, hosted →

$49/mo or $39/mo billed yearly · AI included · 14‑day guarantee

Best for

Private mobile access to an agent you already run

Short research requests and voice-note handoffs away from a computer

Receiving approved scheduled reports in a known topic

Trusted groups with explicit sender access and mention rules

Features

  • ✓Private text, voice-note, image and file conversations with your Hermes agent
  • ✓QR creation or manual BotFather setup in the owning Hermes profile
  • ✓Separate authorization for human senders and whole groups
  • ✓DM topics with separate conversation sessions
  • ✓Scheduled results delivered to an explicitly chosen chat or topic
  • ✓Polling without a public inbound port, or authenticated webhook delivery
  • ✓Configurable handling of messages sent while the gateway is offline
  • ✓Reply recovery with possible-duplicate warnings after ambiguous sends

Setup path

  1. 1Choose the existing Hermes profile and host that will own the bot. Check hermes config path, hermes config env-path and hermes gateway status without exposing file contents.
  2. 2Open Messaging → Telegram → Create with QR in the current dashboard or Desktop app. Alternatively create a bot through @BotFather and run hermes gateway setup.
  3. 3Authorize your human numeric Telegram user ID, not the bot-token prefix. Review a DM pairing request locally if using pairing instead.
  4. 4For a first manual test run hermes gateway run and request a harmless marker in a private DM. Stop that foreground process before starting the installed gateway service with the same token.
  5. 5Verify a fresh reply after service startup. Then test only the group, topic, scheduled delivery or attachment your workflow actually needs.

Choose QR setup or the manual checklist

Current official Telegram docs describe Create with QR in the dashboard and Desktop app. It creates the bot, detects your Telegram user ID, writes the selected profile settings and restarts the gateway. The connection checklist covers both paths; the full setup guide adds commands and recovery checks.

  • •Keep bot tokens out of chats, repositories and screenshots.
  • •Use one gateway owner for each bot token; competing pollers can interrupt delivery.
  • •Test a private DM before adding a group or topic.

Bot identity, human access and group access

A token identifies the bot. Hermes separately decides whether a sender can invoke it. A topic decides where a conversation lives; it does not create a new permission boundary.

  • •TELEGRAM_ALLOWED_USERS grants named human accounts access in DMs and groups.
  • •TELEGRAM_GROUP_ALLOWED_USERS grants selected humans group-only access.
  • •TELEGRAM_GROUP_ALLOWED_CHATS authorizes every member of a specified group.
  • •BotFather privacy controls which messages Telegram delivers; Hermes mention rules are another gate.

Connected but silent: trace one fresh message

Send a harmless unique marker and follow it through inbound receipt, sender authorization, model completion and Telegram delivery. The gateway recovery guide explains process failures. Use the private WebUI for status and logs, but confirm the actual reply in Telegram.

  • •No inbound update points to transport, privacy, the wrong bot or an offline queue policy.
  • •An authorized update followed by a provider error is not a bot-token problem.
  • •A completed turn without a visible reply needs a destination or send-error check.
  • •Inspect any consequential external action before repeating its instruction.

Messages sent while the host is offline

Current official Telegram queue documentation, checked November 19, 2026, preserves pending updates on cold boot by default. Set drop_pending_on_cold_boot: true only to deliberately discard them. Watcher reconnects and conflict recovery preserve the queue. Check your installed version and explicit policy; the Telegram setup guide includes a harmless offline/online acceptance test.

  • •Old instructions may execute on startup; require fresh approval when their original intent is stale.
  • •Completed inbound update-ID receipts persist per bot for 24 hours as well as being tracked in memory; unreadable or expired receipts lose protection.
  • •Inbound deduplication does not retry failed replies or guarantee exactly-once external actions.
  • •A 409 conflict can recover after bounded retries; persistent token_in_use_elsewhere needs an ownership check, not another poller.

Topics separate conversations, not host permissions

Enable Threads and use /topic for parallel DM sessions. The root of a topic-enabled DM is the system lobby. Use separate profiles for different configurations and credentials; use runtime isolation too when different users must not share host access.

  • •Test a forum topic with its exact chat and thread IDs.
  • •After a BotFather privacy change, remove and re-add the bot before retesting.
  • •Pin scheduled output to its intended destination; see cron delivery.
  • •Optional group observation stores unmentioned messages as context. Enable it only for trusted chats with appropriate expectations.

Who keeps the gateway running?

Self-host for control over storage, tools, credentials and updates. Polling suits an always-on host without a public inbound port; webhook mode needs HTTPS and TELEGRAM_WEBHOOK_SECRET. Compare managed hosting when you do not want to maintain the runtime. Self-hosted WebUI already includes PTY/WebSocket Chat: the distinction is operational ownership, not whether browser chat exists.

  • •A laptop bot stops being available when its gateway stops.
  • •Verify current managed-plan channel support, limits and provider terms.
  • •Voice transcription, long context and scheduled work can add provider usage.
  • •An Online label can remain stale after a hard crash; test a real round trip.

Common setup issues

  • No inbound message: check the correct bot, owning gateway, polling conflicts and group privacy before changing the model.
  • Unauthorized user: check the human ID or pairing approval in the service profile. The bot-token prefix is not a human ID.
  • Reaction but no reply: inspect the provider request and Telegram send result separately. A reaction only shows partial progress.
  • Offline backlog missing: current docs preserve it by default. Check the installed version and whether drop_pending_on_cold_boot is explicitly true; Telegram only retains undelivered updates for up to 24 hours.
  • DM works but topic is silent: verify permissions and the exact chat_id plus message_thread_id, not only the parent group.
  • Docker-generated file will not send: the gateway needs a host-readable MEDIA path; use a narrow shared task mount, not the entire credential directory.

FAQ

How do I connect Hermes Agent to Telegram?

Use Messaging → Telegram → Create with QR in a current dashboard or Desktop build, or create a BotFather bot and run hermes gateway setup. Authorize your human account and test a private reply from the owning gateway.

Why is Hermes connected to Telegram but not replying?

Connected is only one checkpoint. Trace a new harmless message through inbound receipt, authorization, provider completion and Telegram delivery. Check the exact destination and do not repeatedly rotate a valid token.

Why are messages sent while my computer was off missing?

Current docs preserve pending updates by default (drop_pending_on_cold_boot: false). An explicit true value discards them at cold boot. Verify the installed version and policy; stale commands may execute on startup, and Telegram retention is no longer than 24 hours.

Can I use Telegram groups and topics?

Yes. Test one DM first, then configure human or group authorization, BotFather privacy and mention rules. Verify the exact chat and topic. Separate topics keep conversation sessions apart, not host secrets or filesystem permissions.

Does Telegram need a public port?

Default polling does not need a public inbound port. Webhook mode needs an HTTPS endpoint and TELEGRAM_WEBHOOK_SECRET. Verify the chosen host supports the intended wake-on-message behavior.

Can a recovered reply arrive twice?

Yes. An ambiguous send may be retried and labeled as a possible duplicate. Inspect the actual external result before rerunning an instruction that could publish, pay, deploy or contact someone.

Is FlyHermes required for browser chat or Telegram?

No. Self-hosted Hermes supports Telegram and WebUI Chat through PTY/WebSocket. Consider FlyHermes when you want managed operation rather than responsibility for runtime uptime, updates and recovery.

Related setup guides

Other Integrations