The n8n agent — the Telegram bot's brain

The bot is built in n8n as a single workflow, n8n/workflows/shopbot-telegram-agent.json. It's an AI agent pattern: a language model that can call tools, wrapped so that a Telegram message goes in and a helpful reply comes out. Nothing is hard-coded about what the customer can ask — the model decides which backend calls to make.

The flow

Telegram Trigger ─► ShopBot Agent ─► Send reply
                        │  ▲ │
        gpt-4o-mini ────┘  │ └──── Chat Memory (per chat id)
                           │
   tools ► search_products · check_availability · order_status
         · list_my_orders · place_order · create_payment_link

• Telegram Trigger receives each message. n8n auto-registers the Telegram webhook when the workflow is activated (because WEBHOOK_URL points at the public n8n URL).
• ShopBot Agent (@n8n/n8n-nodes-langchain.agent, the Tools Agent) is the orchestrator. It reads the message, decides which tools to call, loops until it has an answer, then produces the reply text.
• OpenAI gpt-4o-mini is the model — chosen as a fast, cheap, capable default for a chat agent. Temperature is low (0.3) so it follows the ordering rules instead of improvising.
• Chat Memory (a window buffer keyed by the Telegram chat id) gives the bot short-term memory, so "order 2 of those" resolves against what was just discussed.

The tools are just HTTP calls

Each tool is an n8n HTTP Request tool node pointed at the inventory backend on the private network (http://inventory:3700/...). The model fills in the {placeholders}; n8n makes the call and feeds the JSON back to the model.

Tool	Call	Auth
search_products	GET /api/products?search={query}	open
check_availability	GET /api/products/{product}/availability?qty={qty}	open
order_status	GET /api/orders/{ref}	open
list_my_orders	GET /api/orders?customer={chat-id}	open
place_order	POST /api/orders (items JSON)	X-API-Key
create_payment_link	POST /api/orders/{ref}/pay	X-API-Key

Two safety details worth calling out:

• The customer's identity isn't trusted to the model. place_order and list_my_orders fill the Telegram id from the trigger context ($('Telegram Trigger').item.json.message.from.id) via an n8n expression — not from a value the model could invent — so the bot can't place an order under someone else's id.
• Only the two write tools carry the API key, via a reusable n8n Header Auth credential. Reads need no secret.

Keeping the agent honest

The agent's system message encodes the shop's rules so the model can't promise what the backend hasn't confirmed:

1. Never invent products, prices, stock or order references — always use a tool.
2. Check availability before placing an order.
3. Read back items + total and get confirmation before place_order.
4. After ordering, return the reference and a Paystack payment link.
5. Be brief and chatty — it's Telegram, not a JSON dump.

This is the iron rule of grounding a shopping agent: the model handles language and intent, but every fact and side-effect goes through a tool the backend controls.

Validating without credentials

The workflow can't actually chat until the owner adds a Telegram token + OpenAI key (see the RUNBOOK). What was verified: the workflow imports cleanly into n8n 2.27 — every node type, type-version, and the special ai_languageModel / ai_memory / ai_tool connections are accepted — so it loads ready to wire up, not as a broken graph.