Telegram Orchestrator

1. Quoi ? — Définition et contexte

Le Telegram Orchestrator est le workflow N8N qui sert de point d’entrée principal pour interagir avec l’infrastructure. Il reçoit les messages et callbacks Telegram et les route vers les handlers appropriés.

Bot Telegram

Un bot Telegram est un programme qui peut recevoir et envoyer des messages sur Telegram. Combiné avec N8N, il devient une interface de contrôle pour votre infrastructure : tapez une commande, le bot exécute une action et vous répond.

Composants du système

Composant	Rôle
Telegram Bot	Interface utilisateur (messages, boutons)
IA Router	Détection d’intent via Claude
Command Router	Gestion des commandes /xxx
Menu Handler	Gestion des callbacks boutons
Service Handlers	Exécution des actions (Docker, N8N, etc.)

Architecture visuelle

Message/Callback Telegram
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│              Telegram Orchestrator                       │
│  ├─ Extract userId/chatId                               │
│  ├─ Check if user banned                                │
│  └─ Route by update type                                │
└───────────────────────┬─────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│  IA Router  │  │  Command    │  │   Menu      │
│  (Claude)   │  │   Router    │  │  Handler    │
│             │  │  (/docker)  │  │ (callbacks) │
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                │
       ▼                ▼                ▼
┌─────────────────────────────────────────────────────────┐
│              Service Handlers                            │
│  ├─ Docker Handler (status, restart, logs, update)      │
│  ├─ N8N Handler (workflows, logs, data tables, triggers)│
│  ├─ General Handler (help, chat Claude)                 │
│  └─ Voice Handler (transcription Whisper)               │
└─────────────────────────────────────────────────────────┘

---

2. Pourquoi ? — Enjeux et motivations

Problèmes résolus

Problème	Sans orchestrator	Avec orchestrator
Accès SSH distant	Connexion SSH pour chaque action	Message Telegram depuis le mobile
Commandes complexes	Mémoriser les commandes Docker	Langage naturel + menus
Sécurité	SSH exposé	Bot authentifié + whitelist
Réactivité	Pas de notification des problèmes	Alertes + actions immédiates

Fonctionnalités clés

Fonction	Description
Authentification	Whitelist d’utilisateurs, approbation admin
Intent detection	Claude analyse le langage naturel
Menus interactifs	Boutons inline pour actions fréquentes
Multi-service	Docker, N8N, Odoo depuis une interface unique
Transcription	Messages vocaux → texte → action

---

3. Comment ? — Mise en œuvre technique

Authentification

Flow d’authentification :

Message reçu
     │
     ▼
┌─────────────────────────┐
│  Check If User Banned   │ ← Data Table "banned_users"
└───────────┬─────────────┘
            │
   ┌────────┴────────┐
   ▼                 ▼
Banned           Not Banned
   │                 │
   ▼                 ▼
Ignore         Check authorized_users
                     │
              ┌──────┴──────┐
              ▼             ▼
         Authorized    Unauthorized
              │             │
              ▼             ▼
          Process      Alert admin
          request      [Approve] [Deny]

Data Tables :

Table	Colonnes	Usage
authorized_users	telegram_id, name, is_admin, permissions	Utilisateurs autorisés
banned_users	telegram_id, reason, date	Utilisateurs bloqués
pending_approvals	telegram_id, request_date	En attente d’approbation

Sécurité

Ne jamais autoriser automatiquement les nouveaux utilisateurs. Chaque demande doit être approuvée manuellement via les boutons Telegram envoyés aux admins.

IA Router (Claude)

Prompt d’analyse :

const prompt = `Tu es un système de détection d'intent pour un assistant Telegram.
Retourne UNIQUEMENT un JSON valide (pas de markdown, pas de backticks).

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

Services:
- odoo: factures, devis, contacts, clients, projets, CRM
- n8n: workflows, automatisations, executions
- docker: containers (restart, status, logs)
- general: conversation, questions générales

Message utilisateur: ${text}`;

Exemples de routing :

Message	Service	Action	Params
”redémarre n8n”	docker	restart	{container: "n8n"}
”montre les workflows actifs”	n8n	list_workflows	{filter: "active"}
”c’est quoi ce truc?“	general	chat	-
”cherche le contact Jean”	odoo	search_contact	{name: "Jean"}

Scoring de confiance :

Confidence	Comportement
≥ 0.7	Route directement vers le service
0.5 - 0.7	Demande confirmation (boutons)
< 0.5	Route vers general

Fallback Chain :

1. Claude Sonnet (via claude-ollama) — Prioritaire
2. Claude Haiku — Si quota Sonnet épuisé
3. Keyword routing — Si API indisponible

Command Router

const MENU_COMMANDS = {
  '/menu': 'main',
  '/start': 'main',
  '/docker': 'docker',
  '/help': 'help',
  '/n8n': 'n8n'
};

Commande	Menu Type	Description
/menu	main	Menu principal
/start	main	Menu principal (Telegram standard)
/docker	docker	Menu actions Docker
/help	help	Aide et commandes disponibles
/n8n	n8n	Menu gestion N8N (admin only)

Commandes vs texte

Les commandes exactes (ex: /docker) vont au Command Router. Les commandes avec arguments (ex: /docker status) passent par l’IA Router pour extraction des paramètres.

Menu Handler

Conventions de callback :

# Navigation
menu_main                        → Menu principal
menu_docker                      → Menu Docker
menu_n8n                         → Menu N8N (admin)

# Docker actions
menu_docker_stacks_<action>      → Liste stacks pour action
docker_<action>_<stack>          → Exécute action sur stack

# N8N actions
menu_n8n_workflows               → Liste workflows
n8n_wf_<id>                      → Toggle workflow
n8n_run_<id>                     → Exécuter workflow

# User management
approve_<userId>                 → Approuver utilisateur
deny_<userId>                    → Refuser utilisateur

Exemple de menu :

┌──────────────────────────────┐
│       Menu Principal          │
├──────────────────────────────┤
│ [🐳 Docker]   [📊 Status]    │
│ [⚙️ N8N]      [❓ Aide]      │
└──────────────────────────────┘

Service Handler Docker

Action	Commande	Protection
status	docker compose ps --format json	Tous
logs	docker compose logs --tail 100	Tous
restart	docker compose restart	Sauf security-stack
stop	docker compose stop	Sauf security-stack
update	docker compose pull && up -d	Sauf security-stack

Protection security-stack

Le security-stack (Caddy + CrowdSec) est protégé contre les actions destructrices. Un restart accidentel couperait l’accès à tous les services.

Format de réponse :

🐳 Status: n8n-stack

✅ n8n (running) - Up 3 days
✅ n8n-worker-1 (running) - Up 3 days
✅ n8n-worker-2 (running) - Up 3 days
✅ n8n-postgres (running) - Up 3 days
✅ n8n-redis (running) - Up 3 days

Service Handler N8N

Accès réservé aux admins.

Action	Description
list_workflows	Liste workflows avec pagination
toggle_workflow	Active/désactive un workflow
list_executions	Dernières exécutions (filtres)
execute_trigger	Déclencher un workflow manuellement

Trigger Whitelist :

Seuls les workflows dans n8n_trigger_whitelist peuvent être déclenchés :

Catégorie	Exemples
backup	Backup DB, Export workflows
sync	Sync GitHub, Sync Odoo
cleanup	Clean logs, Purge pending

Rate Limiting

Les triggers manuels sont limités à 1 par minute par workflow pour éviter les abus.

Voice Handler

Durée	Service
≤ 30s	Groq Whisper (gratuit, rapide)
> 30s	ElevenLabs Scribe (diarisation)

Voir Voice Transcription pour les détails.

Best Practices N8N

Ordre des conditions dans Parse Callback :

// ✅ BON - Du plus spécifique au plus général
if (callbackData.startsWith('menu_n8n')) { ... }
else if (callbackData.startsWith('menu_docker_stacks_')) { ... }
else if (callbackData.startsWith('menu_')) { ... }

// ❌ MAUVAIS - menu_ attrape tout
if (callbackData.startsWith('menu_')) { ... }
else if (callbackData.startsWith('menu_n8n')) { ... }  // Jamais atteint !

Échappement HTML :

const escapeHtml = (text) => {
  return text
    .replace(/&/g, '&')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;');
};

---

4. Et si ? — Perspectives et limites

Limites actuelles

Limite	Impact	Mitigation
Latence Claude	2-5s pour intent detection	Cache des intents fréquents
Pas de multi-langue	Prompts en français uniquement	Suffisant pour usage personnel
Rate limiting Telegram	30 messages/seconde max	Non atteint en usage normal

Scénarios d’évolution

Si besoin de commandes vocales avancées :

• Intégrer un assistant vocal dédié
• Permettre les conversations multi-tours
• Ajouter la synthèse vocale pour les réponses

Si équipe multi-utilisateurs :

• Permissions granulaires par handler
• Logs d’audit des actions
• Notifications de groupe pour les actions critiques

Si besoin d’autres services :

• Ajouter un handler pour chaque nouveau service
• Pattern existant facilement extensible
• Claude s’adapte automatiquement aux nouveaux services

---

Pages liées

Infrastructure

• N8N en mode Queue — Backend automation
• AI Stack — Claude Ollama pour intent detection

Workflows

• Voice Transcription — Transcription vocale
• Docker Auto-Updates — Mises à jour automatiques
• Notification Hub — Routage notifications

Référence

• Glossaire — Webhook, Callback, Intent