See llms.txt for all machine-readable content.

Back to Templates

Route Telegram conversations between Hermes and your main workflows

Created by

Created by: Paul Jackways || pauljackways
Paul Jackways

Last update

Last update a day ago

Categories

Quick overview

Facilitates determinism and offloads memory management for small, locally hosted agents.
Acts as a generic proxy between a main n8n workflow, Hermes, and Telegram.
Deterministically stores chat history, prompts, and JSON return schema.

To be paired with my "Small-model deterministic workflow architecture". This workflow may not be uploaded yet.

How it works

  1. User initiates workflow either from the workflow directly, or with a "/load" message in Telegram that bypasses Hermes and goes straight to the n8n endpoint (/load is not tied to any taskID). Look to "Small-model deterministic workflow architecture" for a serving suggestion.
  2. Fresh Hermes instance initiated by proxy, passes it the task plus a generic context specifying its roles and tools.
  3. Hermes decides whether it can complete the task by forming the correct return schema and calling the n8n proxy webhook, or whether it needs information from the user, and so calls Telegram proxy webhook
  4. Whatever Hermes does is stored in the task history, the instance is then "/stop"ped, stopped runs are then deleted from the table of active runs.
  5. Replies to Hermes from Telegram (based on a specific task) are appended to the history table and a new Hermes instance is called.

Setup

  1. Create a Telegram bot, set YOUR_BOT_TOKEN and YOUR_CHAT_ID in the Telegram Bot API request URLs/bodies, and set ALLOWED_CHAT to the same chat ID.
  2. Create and select the required n8n Data Tables (proxy_poll_state, task, and hermes_runs) and ensure they include the columns referenced in the workflow (for example key/value, history, schema, and run_id).
  3. Add an HTTP Header Auth credential for the Hermes API and replace the placeholder credential ID/name used by the Hermes run and stop requests.
  4. Update the Hermes API base URL (host.docker.internal:8642) and the local n8n webhook targets (127.0.0.1:5678/webhook/...) to match your environment.
  5. Copy and configure the webhook URLs (proxy-intake, proxy-prompt, proxy-telegram, and proxy-submit) in the systems that call them (for example your Hermes orchestrator and upstream n8n workflow).

Additional info

Users should build tools n8n_tool and telegram_user for their Hermes bots. I can put mine on GitHub and link them if anyone needs.

The "proxy_poll_state" and everything else related to polling is to accommodate users long-polling telegram over HTTP. If you are running HTTPS, such as with a reverse proxy, you can replace these sections with a direct webhook.

Extra function "/forget" clears the task chat history, prompting Hermes to start again - for chats that are going nowhere, or where you want a new approach

Extra function "/remember" prompts Hermes to pick up the task again in the case that the server goes down, Hermes is restarted, whatever. Note that this only works with stateless workflows such as my "Small-model deterministic workflow architecture"

Each call to Hermes is a new instance. This avoids issues such as Hermes not releasing its turn, or looping infinitely from halting the workflow.

Each call to Hermes is immediately "/stop"ped after tool use. This avoids issues such as Hermes not releasing its turn, or looping infinitely from taking up processor power and wasting tokens.