Intégration Telegram — configuration et utilisation

Un bot par projet. Chaque worker IA reçoit son propre topic dans un Supergroupe Telegram — les messages sont automatiquement routés vers le bon worker et la réponse revient dans le même topic.

À quoi ça ressemble en action

Supergroup "My Project"
├── 📌 General          ← general chat (not bound)
├── 🔵 Developer        ← messages → Developer worker
└── 🟢 Consultant       ← messages → Consultant worker

Tu écris dans le topic Developer → Arc OS le traite via Claude → la réponse apparaît dans le même topic.

Telegram et le dashboard CRM sont deux canaux vers le même worker. Tu peux démarrer une conversation dans Telegram et la continuer dans le CRM — le contexte est conservé.

Configuration

Étape 1 — Crée un bot dans BotFather

Ouvre @BotFather dans Telegram
Envoie /newbot
Saisis le nom du bot (par exemple : My Project)
Saisis un username — il doit se terminer par bot (par exemple : my_project_arc_bot)
BotFather te renvoie un token au format 123456789:AABBccDDee...

⚠️ Enregistre le token — tu en auras besoin pour configurer le CRM.

Étape 2 — Crée un Supergroupe avec des Topics

2.1 Crée le groupe

Telegram Desktop / Mobile :

Touche l'icône crayon → Nouveau groupe
Ajoute n'importe quel membre (tu pourras le retirer plus tard)
Donne un nom au groupe → Créer

2.2 Active les Topics

Ouvre les paramètres du groupe (touche le nom en haut)
Modifier → trouve la section Topics
Active le toggle — Telegram convertit automatiquement le groupe en Supergroupe

2.3 Trouve l'ID du Supergroupe

L'ID du Supergroupe commence toujours par -100.

Option A — via @userinfobot :

Transfère n'importe quel message du groupe vers @userinfobot
Le bot renvoie l'ID au format -1001234567890

Option B — via Telegram Web :

Ouvre le groupe sur web.telegram.org
La barre d'adresse contiendra une URL du type #-1001234567890
Copie le nombre, signe moins inclus

Étape 3 — Ajoute le bot comme administrateur

Ouvre les paramètres du groupe → Administrateurs
Ajouter un admin → dans le champ de recherche, saisis @your_bot_username (l'username complet avec @)
Choisis le bot dans la liste → OK
Les permissions par défaut conviennent — laisse-les telles quelles

⚠️ Le bot n'apparaîtra pas dans la recherche si tu tapes un username partiel ou omets le @. Saisis l'@username exact.

Étape 4 — Crée des topics pour les workers

Dans le groupe, touche + → Nouveau topic :

Nomme les topics d'après les workers : Developer, Consultant, ou des noms personnalisés
Tu peux choisir des couleurs/icônes pour plus de commodité

Étape 5 — Connecte dans le CRM

Ouvre arc-os.co → sélectionne le projet → Paramètres du projet
Trouve la section Channels → clique sur Connect Telegram

5.1 Saisis les détails du bot

Champ	Ce qu'il faut saisir
Bot Token	Le token de BotFather (`123456789:AABBcc...`)
Supergroup ID	L'ID du groupe (`-1001234567890`)

Clique sur Verify & get topics.

5.2 Vérification

Le CRM vérifie :

✅ Le token est valide
✅ Le bot est administrateur du groupe
✅ La liste des topics est chargée

5.3 Lie les topics aux workers

Pour chaque topic, choisis un worker dans le dropdown :

Developer  →  [developer     ▾]
Consultant →  [consultant    ▾]
General    →  [(not bound)]

Clique sur Save bindings.

Étape 6 — Teste

Écris n'importe quel message dans le topic Developer
Le bot répond dans le même topic au nom du worker Developer
Répète pour Consultant

Utilisation quotidienne

Travailler via les topics (recommandé)

Écris simplement le texte de la tâche dans le bon topic — aucun préfixe requis :

[Developer topic]
Fix the bug in the login form — the email field is not validated

[Consultant topic]
Analyze the architecture of the auth module — what can be improved?

Si un topic n'est pas lié à un worker, le worker par défaut répond.

Commandes dans un chat privé avec le bot

Dans un chat privé avec le bot, tu peux changer de worker manuellement via des préfixes :

Préfixe	Worker	Objet
`/c <text>`	Consultant	Analyse, stratégie, lecture seule
`/d <text>`	Developer	Code, fichiers, terminal
`/w:<worker_id> <text>`	Personnalisé	N'importe quel worker du registry
(sans préfixe)	Actif	Le dernier utilisé

Exemples :

/c Analyze the architecture of the auth module
/d Fix the bug in the login form
/w:sentinel Run a security audit of the latest changes

Un message sans préfixe va au worker actif du moment — après /d Fix the bug, les messages suivants sans préfixe vont aussi à Developer.

Boutons inline sous la réponse

Des boutons de contrôle apparaissent après chaque réponse d'un worker IA :

Contrôle du processus :

Bouton	Action
🛑 STOP	Arrêter Claude (s'il a dévié ou s'est bloqué)
⏸️ PAUSE	Mettre en pause — utile pour attendre quelque chose avant de continuer
▶️ RESUME	Reprendre un processus en pause

Contexte et feedback :

Bouton	Action
💡 BTW	Ajouter du contexte — le message suivant sera ajouté comme contexte à la prochaine requête
🛠️ Fix It	Réessayer la tâche avec des corrections automatiques
👍	Feedback positif — enregistré dans les métriques
👎	Feedback négatif — crée automatiquement une règle de correction qui sera appliquée aux requêtes futures

Navigation :

Bouton	Action
🏷️ Skills	Afficher les skills utilisés pour la réponse
📊 View Log	Ouvrir le log de session dans le CRM

Contexte et mémoire

Chaque worker a sa propre mémoire (jusqu'à 50 messages)
Réponds à un message → son texte est ajouté comme contexte à la requête
Le Context Router choisit automatiquement le top-5 des skills pertinents pour ton message
Feedback 👎 → le système mémorise l'erreur et en tient compte dans les requêtes futures

Commandes de gestion du bot

Commande	Description
`/ping`	Vérifier que le bot est en vie + uptime
`/thread`	Taille du contexte courant (nombre de messages)
`/quality`	Métriques de qualité : appels, feedback, temps de réponse moyen
`/issue list`	Lister les issues ouvertes du projet
`/issue create <title>`	Créer une nouvelle issue
`/issue switch <id>`	Changer l'issue active
`/continue`	Reprendre la session dans le conteneur Cloud
`/specs`	Lister les spécifications (draft / review / approved)
`/approve <id>`	Approuver une spécification
`/reject <id> [reason]`	Rejeter une spécification

Relation avec le dashboard CRM

Telegram topic  ──┐
                  ├──► Child Bot ──► Claude ──► Reply
CRM Dashboard   ──┘                              │
                                                 ▼
                                        Telegram + CRM (simultaneously)

Les messages du CRM sont traités toutes les 500ms
Les réponses apparaissent dans Telegram et le CRM simultanément
Les pièces jointes (images, PDF) sont supportées via le dashboard CRM
Tu peux démarrer une conversation dans Telegram et la continuer dans le CRM — le contexte est conservé

Déconnecter le bot

CRM → Paramètres du projet → Channels → Disconnect.

Cela retire le token et tous les liens de topics. Le bot reste dans le groupe — retire-le manuellement des administrateurs si nécessaire.

Dépannage

Problème	Solution
Le bot ne répond pas dans un topic	Vérifie que le bot est administrateur du groupe. Vérifie le lien du topic dans CRM → Channels. En chat privé → `/ping`
Temps de réponse long	Developer (Opus) est plus lent que Consultant (Sonnet). Pour l'analyse et les questions, utilise Consultant
La réponse est coupée	Limite de 4096 caractères de Telegram — le bot découpe automatiquement en `[1/3]`, `[2/3]`, etc.
Impossible de trouver le bot en l'ajoutant au groupe	Saisis l'username complet avec `@` : `@arc_os_project_bot`
« Invalid bot token » pendant la vérification	Vérifie le token — le format est `chiffres:lettres`, sans espaces
« Bot is not admin » pendant la vérification	Ajoute le bot via Administrateurs → Ajouter un admin → `@bot_username`
« supergroup_id must start with -100 »	L'ID doit être `-1001234567890`. Active les Topics pour convertir le groupe en Supergroupe
👎 ne crée pas de règle de correction	Appuie sur 👎 directement sous la réponse du worker, pas sous un message système