Telegram Orchestrator

1. What? — Definition and context

The Telegram Orchestrator is the N8N workflow that acts as the entry point for every human interaction with the VPS infrastructure. It receives every message and every Telegram callback, checks authentication, routes to the right handler, and delegates long-running tasks to 13 callback sub-workflows + 4 extracted service handlers.

Fire-and-forget vs wait-for-result

The callback sub-workflows (SW-1 through SW-13) are fire-and-forget: the orchestrator triggers them, does not read their return value, and stays free to handle other messages. The service handlers (Docker, Odoo, N8N, General) are wait-for-result: the orchestrator waits for the response to format it and send it back to the user.

Top-level components

Component	Role
Telegram Bot	User-facing surface (messages, inline buttons, ForceReply)
AI Router	Intent detection via Claude (5 services: docker, n8n, odoo, content, general)
Command Router	Parsing of /menu, /docker, /n8n, /odoo, /help, /notif, /todo, /triage, /projet, /note, /blog, /research, /new, /conv, /endconv, /model, /plan, /templates, /mcp
13 callback sub-workflows	Auth, menus, n8n actions, photos, conversations, file provider, etc.
4 service handlers	Docker, Odoo, N8N, General (Claude chat)
Binary Content Handler	Photos (via Vision OCR), voice notes, vCard, PDF, videos
Conversation Agent + Plan Engine	Multi-turn conversations and action plans

Architecture diagram

The 21 commands

Category	Commands
Menu	/menu, /start, /docker, /n8n, /odoo, /help, /notif, /todo, /triage
Content	/note, /blog, /research
Conversation	/new, /conv, /endconv, /model, /plan, /templates, /mcp
Project	/projet (sub-commands list, create, status with paginated picker)

---

2. Why? — Stakes and motivations

Problems solved

Problem	Without orchestrator	With orchestrator
Remote SSH access	SSH connection for every action	Telegram message from mobile
Complex commands	Memorise Docker commands	Natural language + menus
Security	Exposed SSH	Authenticated bot + whitelist
Reactivity	No problem notifications	Alerts + immediate actions

Why a sub-workflow refactoring (#273-#294)?

The initial orchestrator had grown to 224 nodes, to the point of slowing the N8N UI and making editing risky (moving a node could break off-screen connections). Three refactoring waves brought the parent down to 124 nodes by extracting fire-and-forget paths:

Wave	Issue	Effect
Phase 1	#273	224 → 142 nodes (5 SWs)
Phase 2	#273	142 → 98 nodes (5 additional SWs)
Conv Mgr	#278	47→21 + 32 (Conversation Command Handlers)
SH-N8N	#279	Service Handler N8N 40→6 + SH-N8N Action Executor 37
Photo routing	#176	+9 nodes for photo conv-routing + SW-13
MCP menu	#294	Conv Agent 16→21 + SW-11 72→87

Each SW has a strict contract: passthrough or typed input, return value ignored by the parent (for fire-and-forget), no side effect on the main runtime.

Key features

Feature	Description
Authentication	User whitelist, admin approval, ban list
Intent detection	Claude analyses natural language (5 services)
Interactive menus	Inline buttons for frequent actions
Multi-service	Docker, N8N, Odoo, Content from a single interface
Voice + Photo	Audio transcription + image extraction
Conversations	Multi-turn with Redis memory and tool calls
Action plans	Multi-step with hybrid escalation
MCP	Native n8n tools enabled per conversation

---

3. How? — Technical implementation

Authentication

Step	Action
1. Extract user ID	Pull userId, chatId, firstName from the message or callback
2. Check banned	Lookup Data Table Telegram Banned Users
3. Check authorised	Lookup Data Table Telegram Authorized users
4. Pending approval	If not authorised: Data Table Telegram Pending Approvals + admin alert

AI Router (Claude)

When a text message is not an exact command and no conversation is active, the AI Router detects intent via Claude (cli-ollama):

const prompt = `You are an intent detection system for a Telegram assistant.
Return ONLY valid JSON (no markdown, no backticks).

Format: {
  "intent": "<action>",
  "service": "<odoo|n8n|docker|general>",
  "action": "<specific>",
  "params": {},
  "confidence": <0.0-1.0>
}

Services:
- odoo: invoices, quotes, contacts, customers, projects, CRM
- n8n: workflows, automations, executions
- docker: containers (restart, status, logs)
- general: conversation, generic questions

User message: ${text}`;

Confidence	Behaviour
≥ 0.7	Routes directly to the service
0.5 - 0.7	Asks confirmation (buttons)
< 0.5	Routes to general

Fallback chain: claude-sonnet-yolo (priority) → claude-haiku-yolo (if quota exceeded) → keyword routing (if API down).

Service Handlers

Four specialised service handlers, each with a narrow responsibility:

Service Handler Docker

Action	Command	Protection
status	docker compose ps --format json	All
logs	docker compose logs --tail 100	All
restart	docker compose restart	Except security-stack
update	docker compose pull && up -d	Except security-stack

security-stack protection

The security-stack (Caddy + CrowdSec) is protected against destructive actions. An accidental restart would cut access to every service.

Service Handler N8N (refactoring #279)

The SH-N8N parent only handles the admin check and delegation. All N8N execution logic lives in SH-N8N Action Executor (37 nodes).

Action	Description
list_workflows	List workflows with pagination
toggle_workflow	Enable / disable a workflow
list_executions	Recent executions (filters)
execute_trigger	Trigger a whitelisted workflow

Trigger whitelist: only workflows present in n8n_trigger_whitelist can be triggered manually (rate limit: 1/min/workflow).

Service Handler Odoo (refactoring #187)

33 nodes after the /projet extension. Covers contacts, invoices, quotes, CRM, projects. The Odoo Project Picker sub-workflow (SW-12) handles project pagination when the list overflows the inline keyboard.

Service Handler General

10 nodes for /help and the generic Claude chat (open-ended questions outside any specific service).

Binary Content Handler

The Binary Content Handler (21 nodes) handles media:

Type	Pipeline
Photo	Vision OCR (sub-workflow 14n, classification + structured extraction)
Voice	Voice Transcription (Groq ≤30s, ElevenLabs >30s)
vCard	Ingress Contacts → Odoo res.partner
PDF / video	Metadata extraction + summary

Vision OCR returns a {status, docType, extracted, text} contract. Depending on docType:

docType	Routing
business_card	Odoo contact creation via Ingress Contacts (fire-and-forget)
invoice / screenshot / handwritten / general_document	Display + [Discuss] button that starts a conversation
not_document	Switch to AI Router for conversational handling
error	Error notification via Notification Hub

Callback convention

# Navigation
menu_<section>                  → Menu (main, docker, n8n, odoo, help, notif, todo)

# Docker
menu_docker_stacks_<action>     → Stack list for action
docker_<action>_<stack>         → Run action on stack

# N8N (admin)
menu_n8n_workflows              → Workflow list
n8n_wf_<id>                     → Toggle workflow
n8n_run_<id>                    → Trigger workflow

# Conversations
conv_switch_<id>                → Change active conversation
conv_delete_<id>                → Archive
plan_exec_<shortId>             → Execute a plan
plan_modify_<shortId>           → Edit a plan
plan_cancel_<shortId>           → Cancel a plan

# User management
approve_<userId>                → Approve user (admin)
deny_<userId>                   → Deny user (admin)

# Photos (#176)
photo_discuss_<shortId>         → Start a conversation about the photo
photo_dismiss_<shortId>         → Ignore the photo

# Notifications hub
notif_<action>_<id>             → approve / retry / details / ignore

Parse Callback condition order

Parse Callback conditions must go from most specific to most general. A startsWith('menu_') condition placed before startsWith('menu_n8n') would capture every N8N route. Always test long prefixes before short ones.

Best practice: __rl resource locator

Execute Workflow nodes MUST use the __rl format for workflowId, otherwise they fail silently at runtime:

{
  "workflowId": {
    "__rl": true,
    "value": "<workflow-id>",
    "mode": "id"
  },
  "options": {}
}

The flat format {"mode": "id", "workflowId": "<id>"} produces “No information about the workflow to execute found” without surfacing the error.

---

4. What if? — Outlook and limits

Current limits

Limit	Impact	Mitigation
Claude latency	2-5s for intent detection	Cache for frequent intents to design
No multi-language	Prompts in French only	Sufficient for personal use
Telegram rate limiting	30 messages/second max	Never reached in normal use
Non-document photos = 2 LLM calls	Detection + generic analysis	Acceptable for the conversation context

Evolution scenarios

If the team moves to multi-user:

• Granular per-handler permissions (currently: admin / non-admin)
• Per-user audit logs of actions
• Group notifications for critical actions

If functional extension is needed:

• Add a service to the Service Router Switch (new case)
• Or enable an MCP server via the /mcp command in a conversation
• The system is extensible by design — every addition is isolated in its own sub-workflow

If latency becomes critical:

• Pre-fetch frequent Data Tables in N8N memory cache
• Pipeline Odoo calls (already partially done)
• Migrate fire-and-forget paths to a dedicated Bull queue

---

Related pages

Infrastructure

• N8N Queue Mode — Automation backend
• AI Stack — cli-ollama for intent detection

Workflows

• Conversational system — Multi-turn conversations, plans, MCP
• Content Pipeline — Note and article capture
• Voice Transcription — Voice transcription
• Vision OCR — Photo classification + extraction
• Docker Updates — DIUN approvals via callbacks
• Notification Hub — Notification routing + callbacks
• Error Handler — Orchestrator error capture

Reference

• Glossary — Webhook, Callback, Intent, Sub-workflow