Hermes Agent

Hermes Agent Guide

Hermes Agent Telegram setup: from first DM to reliable replies

·Hermes Agent Telegram setup

Set up Hermes Agent on Telegram with QR or BotFather, authorize your account, verify a private reply, and handle groups, offline messages and recovery safely.

Get FlyHermes Pro →

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

Prefer to self-host? Read the free install guide (MIT) →

Telegram is an interface to your Hermes Agent, not the machine that runs it. A bot token, an authorized sender, a working model provider and a running gateway all have to agree before a message can complete a round trip.

Quick answer#

Use Messaging → Telegram → Create with QR in the current Hermes dashboard or Desktop app, or create a bot manually with BotFather and run hermes gateway setup. Authorize your human Telegram account, start the gateway on the intended profile, and test one private message before adding a group or topic. If the bot is connected but silent, trace that new message through receipt, authorization, inference and delivery rather than repeatedly rotating the token.

For a shorter checklist, use connect Telegram to Hermes. The Telegram integration overview explains access, topics and hosting choices.

1. Choose the profile and machine first#

A personal laptop is enough for a trial, but the bot stops answering when its gateway stops. An always-on machine needs service supervision, provider access and persistent Hermes state. Running two gateways with the same bot token can cause polling conflicts; use one owner for that token.

From the account that runs the gateway, check paths without printing their contents:

hermes --version
hermes config path
hermes config env-path
hermes gateway status

For an existing named profile, use hermes -p PROFILE config env-path and the same profile selection for gateway commands. Replace PROFILE with its real name. A shell using the default profile cannot prove that a service launched under another account loaded the same configuration.

Hermes profiles separate configuration, sessions and credentials. They are not an operating-system sandbox: processes under the same host account can still have overlapping filesystem access. Use separate runtime accounts or containers when the trust boundary requires it.

2. Create the bot and authorize the human#

Current official Telegram documentation provides two paths:

  • Dashboard or Desktop: open Messaging → Telegram and select Create with QR. Scan the code or follow the link in Telegram. Hermes creates the bot, detects your user ID, writes the bot token and allowed-user setting into the selected profile, and restarts its gateway.
  • Manual: message @BotFather, run /newbot, choose a unique username ending in bot, then run hermes gateway setup and select Telegram. Enter the token and your human user ID in the setup flow.

Do not paste the real token into an agent conversation, screenshot, repository or support post. Revoke a leaked token through BotFather.

Keep these identifiers separate:

  • TELEGRAM_BOT_TOKEN controls the bot. Its numeric prefix is the bot's ID.
  • TELEGRAM_ALLOWED_USERS authorizes human sender IDs. Get yours from @userinfobot or @get_id_bot; your username is not the value.
  • TELEGRAM_GROUP_ALLOWED_USERS authorizes selected senders in groups without granting them DM access.
  • TELEGRAM_GROUP_ALLOWED_CHATS authorizes every member of specified groups. A supergroup ID commonly starts with -100.
  • message_thread_id identifies a topic inside a chat. It is neither a sender ID nor a replacement for the chat ID.

An unknown DM sender can also request pairing. Review the request locally with hermes pairing list and approve only the intended person with hermes pairing approve telegram <code>. Replace the placeholder with the actual pending code. In Docker, run pairing as the gateway's application user so the protected pairing record remains readable by that process.

3. Prove one private round trip#

For a first foreground test, run hermes gateway run. Keep the terminal open and send this harmless request from your authorized Telegram account:

Reply with TELEGRAM-CHECK-1 only. Do not run tools or change anything.

Confirm that exact reply arrives in the same DM. Inspect the gateway's configured provider and profile separately; asking the model to name itself is not a reliable configuration check.

After the foreground test, stop that process before starting a service with the same bot token. Use the supported service setup for your host:

hermes gateway install
hermes gateway start
hermes gateway status

Then send a fresh check with a different marker. For an existing service after a deliberate configuration change, use hermes gateway restart. Do not start an additional foreground poller as a diagnostic shortcut.

The gateway troubleshooting guide covers service and adapter failures. Provider authentication, unavailable models and quota errors belong to a different stage than Telegram permissions.

4. Find where a silent message stopped#

Use the timestamp and destination of one fresh test. Avoid reposting a real instruction that might already have changed an external system.

  1. No inbound update: confirm the bot username, owning gateway and transport. In a group, check Telegram privacy. If the message was sent while the host was off, check the cold-boot policy below.
  2. Update received, sender rejected: inspect the human allowlist or pairing record in the owning profile. Do not substitute the bot-token prefix or enable broad public access to make the error disappear.
  3. Authorized message, no model response: inspect the provider error and the service's environment. A reaction or typing indicator does not prove inference completed.
  4. Completed response, no visible reply: inspect Telegram send errors, rate limits and the exact destination thread. Before repeating a consequential task, check its actual result.

Use the private Hermes WebUI to inspect status and logs. It also supports real browser Chat through PTY/WebSocket; browser Chat working does not prove Telegram delivery works. Keep administrative access protected.

5. Decide what happens to messages sent while offline#

Current Telegram documentation preserves the cold-boot backlog by default. The setting is drop_pending_on_cold_boot: false; set it to true only when you deliberately want startup to discard pending messages. This corrects older advice that described dropping the queue as the current default. Check the documentation against your installed version and inspect any explicit setting before assuming a default applies.

Merge the chosen policy into the existing profile configuration, without duplicate YAML keys:

platforms:
  telegram:
    extra:
      drop_pending_on_cold_boot: false

Keeping the queue means old instructions may execute when the host starts. Before a planned shutdown, decide whether queued publishing, deployments or messages to other people will still be authorized on return. Use fresh approval for stale consequential actions. Set true when discarding that backlog is the intended policy; it is not a repair for a competing poller.

Test with harmless markers during an idle maintenance window: stop the intended gateway normally, send an offline marker, start that same owner, and then send a different online marker. Check both outcomes against your explicit policy. Do not stop a busy task or use a real transaction as the experiment. This is a proposed acceptance check, not a bot test we performed.

Keep three mechanisms separate:

  • Pending inbound queue: Telegram holds undelivered updates for no longer than 24 hours. Current Hermes docs say brief watcher reconnects and polling-conflict recovery preserve this queue, regardless of the cold-boot discard setting.
  • Repeated-update suppression: completed update IDs are also persisted per bot under the Hermes home for 24 hours, alongside bounded in-memory protection. A restart therefore does not automatically erase all duplicate protection. An unreadable receipt file or expired receipt can remove that protection.
  • Reply recovery and external actions: inbound receipts do not retry a failed reply or promise exactly-once tool execution. After a crash, a partially processed update can still be redelivered. Inspect the actual external result before repeating any consequential instruction.

For a suspected replay, compare the bot/profile, chat/topic, update_id, update kind, message_id and receive time. Matching text or a matching message ID alone is not proof of the same inbound update; an edit can have a new update ID.

Sources checked November 19, 2026: the official cold-boot pending queue and repeated inbound updates sections. These describe current documented behavior, not a guarantee that an older installed release implements it.

6. Add one group or topic, not every destination at once#

First test an explicit mention in one trusted group. Telegram privacy controls which group messages reach the bot; Hermes authorization and mention rules decide which received messages it may act on. Disabling privacy does not authorize users, and authorizing a whole group grants broader access than allowlisting individual senders.

If ordinary group messages must reach Hermes, change BotFather privacy or the bot's admin status as documented. After a privacy change, remove and re-add the bot so Telegram refreshes the group's delivery rules. Test again in the exact forum topic, not only the parent group.

For parallel private conversations, enable the bot's Threads setting and use /topic. Each DM topic gets its own Hermes session. /new resets that topic's conversation; separate topics do not isolate host secrets or tool permissions. The root of a topic-enabled DM is a system lobby, so put normal agent work in a topic.

If scheduled results should reach a topic, configure the exact delivery destination and TELEGRAM_CRON_THREAD_ID where applicable. Follow the cron delivery guide and verify a harmless result in that destination. A successful scheduler run or a working ordinary DM does not prove topic delivery.

7. Keep transport, attachments and cost checks separate#

Polling is the default for an always-on host and needs no public inbound port. Webhook mode needs a public HTTPS endpoint and TELEGRAM_WEBHOOK_SECRET; it can suit hosts designed to wake on inbound requests. Verify the host's actual wake and timeout behavior. Do not assume a webhook makes an arbitrary sleeping machine reachable.

Before switching transport, inspect the bot's registered webhook with Telegram's read-only getWebhookInfo method, using an authorized local client without exposing its token. An empty URL means no webhook is registered; a nonempty URL prevents polling from receiving updates. Do not run diagnostic getUpdates calls alongside a live poller or delete a production webhook as a token test. The Telegram 409 recovery checklist explains competing consumers, stale status and how to verify inbound progress.

Telegram keeps undelivered updates for no longer than 24 hours. Keeping the cold-boot queue does not extend that limit, and an explicit cold-boot discard policy can remove updates earlier. For long outages, check what actually ran before resending old instructions; do not assume the backlog can be recovered.

For generated files, the gateway must be able to read the final MEDIA:/... path. A file visible only inside a Docker tool sandbox may not be visible to the host gateway. Use a deliberate shared task mount and the corresponding host-readable path, not a mount exposing all Hermes credentials.

Optional group observation stores unmentioned messages as context without making the agent reply to each one. Use it only in trusted chats with participants' expectations in mind. It can increase context usage; voice transcription, scheduled tasks and long conversations can also add cost. Check provider costs and rate limits before changing models to treat a routing problem.

An optional Online label in the bot profile is only a hint. A hard crash can leave stale profile text. A fresh harmless round trip is stronger evidence.

A real deployment lesson, with limits#

Tessa Kriesel's Railway deployment account describes running Hermes as a persistent Docker service with Telegram as its interface. Her May 12, 2026 article reports problems involving startup commands, state persistence and subprocess cleanup. It is one creator's deployment account, not our benchmark or a claim that every current installation has those bugs.

The useful lesson is to verify the long-running service, not only the token. Use the current official docs for supported commands and the current Docker installation guide for image and persistence paths rather than copying a historical deployment file unchanged.

Self-host or choose managed operation?#

Self-host when you want control over the machine, credentials, tools, storage and update schedule. That also makes you responsible for the gateway staying online and recovering safely.

Consider FlyHermes managed hosting when operating the runtime is the work you want to avoid. Compare current channel support, provider terms and plan limits before choosing. This is an ownership decision: self-hosted Hermes already supports Telegram and browser Chat; managed hosting is not required merely to access those interfaces.

Before calling your setup ready, verify a private reply, the intended group/topic if used, the chosen offline-message behavior and one safe attachment if the workflow needs files. Keep those checks small enough to repeat after an update.

Frequently Asked Questions

Do I have to create the bot manually in BotFather?

No. Current dashboard and Desktop builds offer Messaging → Telegram → Create with QR. Manual BotFather creation and hermes gateway setup remain available.

Which ID goes in TELEGRAM_ALLOWED_USERS?

Use your human numeric Telegram user ID, not the bot-token prefix, group chat ID or topic ID. Pairing is another way to approve a specific DM sender.

Why does the bot react but never answer?

A reaction does not prove model completion or final delivery. Check one fresh message in gateway logs, identify whether inference failed, and inspect the send result and exact destination before changing credentials.

How do I preserve messages sent while the gateway was offline?

Current docs preserve the backlog by default with platforms.telegram.extra.drop_pending_on_cold_boot: false. An explicit true value discards it on cold boot. Verify your installed version and policy; stale instructions can execute on startup, and Telegram retention is no longer than 24 hours.

Does recovery guarantee a task runs exactly once?

No. Current docs describe bounded in-memory protection plus completed update-ID receipts persisted per bot for 24 hours. Receipt expiry, unreadable state, partial processing and downstream effects still prevent an exactly-once guarantee. Inspect external results before retrying.

Do topics isolate credentials and files?

No. Topics separate conversation sessions. Profiles separate configuration and credentials, but strict filesystem isolation also requires appropriate host accounts, containers or other runtime controls.

Why can Telegram not send a file created in Docker?

The sending gateway must read the final MEDIA path. Use a deliberate shared task mount and a host-readable path; do not expose the entire Hermes credential directory to solve one attachment issue.

Should I self-host or choose FlyHermes?

Self-host for control over runtime, storage and tools. Consider FlyHermes to offload operational upkeep, checking current channel support and plan terms. Self-hosted Hermes already supports Telegram and browser Chat.

Will keeping the cold-boot queue recover every Telegram message after an outage?

No. Telegram stores undelivered updates for no longer than 24 hours. Current watcher reconnects and conflict recovery preserve the queue, but an explicit cold-boot discard policy can drop it earlier. Queue retention is not exactly-once execution.

Prefer to self-host? Full control, MIT licensed, on your own infrastructure. View install guide →

Keep reading

Related Hermes Agent guides