Démarrage rapide : de zéro à opérationnel, sans sauter d'étape

Le parcours par défaut est hébergé dans le cloud : juste un téléphone et ~10 minutes — sans serveur, sans code. Chaque étape vous indique quel écran ouvrir et où appuyer, ainsi que les pièges que les gens rencontrent vraiment.

Sommaire Liste de contrôle Étape 1 · Créez votre bot dans BotFather (deux interrupteurs cruciaux) Étape 2 · Liez le bot dans Telegram Business Étape 3 · Créez votre groupe forum console Étape 4 · Choisissez : ☁️ Hébergé dans le cloud (recommandé) / 💻 Auto-hébergé Étape 5 · Testez la discussion Dépannage

🧾 Liste de contrôle

1Créez votre bot dans BotFather

Dans Telegram, cherchez @BotFather (repérez le badge de vérification bleu) et tenez cette conversation :

🤖 BotFather
/newbot
BotFatherAlright, a new bot. How are we going to call it? Please choose a name for your bot.
LingoDesk Assistant
BotFatherGood. Now let's choose a username for your bot. It must end in bot.
my_lingodesk_bot
BotFatherDone! Use this token to access the HTTP API:
8123456789:AAHfK3xxxxxxxxxxxxxxxxxxxxxxxxx
Keep your token secure and store it safely…

1a. Activez le mode Secretary Mode (requis ; anciennement « Business Mode »)

⚠️ En mai 2026, Telegram a renommé cet interrupteur en Secretary Mode ; les clients plus anciens peuvent encore l'appeler Business Mode — c'est la même chose. Faites cela à l'intérieur du chat @BotFather (pas la page de profil de votre bot, ni les réglages Telegram de votre téléphone). Deux interfaces — les deux fonctionnent :

Interface ① Commandes classiques — envoyez simplement des messages :

/mybots→ @my_lingodesk_bot→ Bot Settings→ Secretary Mode→ Turn on

Interface ② Nouveau panneau de gestion — appuyez sur le bouton bleu Open à côté de la zone de saisie de BotFather :

Open (panneau)→ choisissez votre bot→ Settings→ Mode Settings→ activez Secretary Mode
Vous ne le trouvez pas ? ① Il porte deux noms : Secretary Mode dans les nouveaux clients, Business Mode dans les plus anciens — cherchez l'un ou l'autre ; ② assurez-vous d'être bien dans @BotFather, pas dans les réglages de votre propre bot ; ③ cet interrupteur n'a rien à voir avec Telegram Premium — Premium ne compte que pour la liaison côté votre compte à l'étape 2 ; n'importe qui peut basculer cet interrupteur.
Sans Secretary Mode, Telegram affiche une fenêtre contextuelle — « This bot doesn't support Telegram Business yet » — lorsque vous tentez de l'ajouter à l'étape 2. C'est le blocage le plus courant de tous. Basculez l'interrupteur : il prend effet immédiatement, inutile de recréer le bot ; réessayez simplement de l'ajouter.

1b. Désactivez la confidentialité de groupe (Group Privacy) (requis)

/mybots→ @my_lingodesk_bot→ Bot Settings→ Group Privacy→ Turn off
La confidentialité est activée par défaut, et tant qu'elle l'est, le bot ne peut pas voir les réponses que vous saisissez dans votre groupe console — le symptôme est « je tape dans le sujet et rien ne se passe ». Désactivez-la (BotFather doit indiquer Privacy mode is disabled).

2Liez le bot dans Telegram Business

Sur l'application Telegram mobile (ce réglage n'existe actuellement que sur mobile) :

⚙️ Réglages→ 💼 Telegram Business→ 🤖 Chatbots

Dans les clients plus récents, cet élément s'appelle « Chat Automation » — libellé différent, même entrée.

  1. Tapez le nom d'utilisateur de votre bot (p. ex. my_lingodesk_bot) dans la zone de recherche et sélectionnez-le.
  2. Autorisations : activez « Reply to messages » — sans cela le bot peut lire mais ne pourra jamais envoyer en votre nom.
  3. Pour « quelles discussions », choisissez All 1:1 Chats ; ajoutez à la liste Excluded Chats tous les contacts privés que vous voulez tenir à l'écart du relais.
Une fois liée, chaque message privé que vous recevez est silencieusement transmis en copie au bot — l'autre partie ne remarque rien, et votre propre expérience de discussion ne change absolument pas.

3Créez votre groupe forum console

Ce groupe est votre plan de travail : un sujet par contact, avec les cartes de message bilingues qui s'affichent à l'intérieur.

  1. Créez un groupe : Nouveau → Nouveau groupe, ajoutez votre bot comme seul membre (cherchez son nom d'utilisateur). Nommez-le comme vous voulez, p. ex. « LingoDesk Console ».
  2. Activez les sujets (Topics) : ouvrez le groupe → appuyez sur le nom pour son profil → Modifier → activez Topics. Le groupe passe en supergroupe et obtient une liste de sujets.
  3. Promouvez le bot administrateur : profil → Administrateurs → Ajouter un administrateur → votre bot → cochez « Manage Topics » (laissez le reste par défaut) → enregistrez.
Le bot crée automatiquement un sujet pour chaque contact. Sans les droits d'administrateur + « Manage Topics », cela échoue — le symptôme est « un client m'a écrit mais rien n'apparaît dans le groupe ».
Le groupe n'a besoin que de vous et du bot — aucun autre humain. Si vous ajoutez un collaborateur, ses réponses dans un sujet déclenchent la traduction et l'envoi tout comme les vôtres.

4Choisissez : ☁️ Hébergé dans le cloud ou 💻 Auto-hébergé

Tout ce qui concerne le téléphone est terminé. Choisissez maintenant votre parcours — pas de serveur ? Prenez l'option A : rien à installer.

☁️ Option A · Hébergé dans le cloud (recommandé : sans serveur, sans code, instantané)

  1. Envoyez un message privé au bot d'activation officiel @LingoDeskbot, envoyez /start, puis collez le BOT_TOKEN de l'étape 1 directement dans la discussion.
  2. Activation automatique instantanée : dès que le jeton est validé, il répond « 🎉 Activated » (et supprime votre message contenant le jeton). La formule gratuite couvre 300 réponses traduites/mois ; passez au Pro (500 ⭐/mois) à tout moment pour un usage illimité. Le moteur de traduction est offert — aucune clé API à créer.
  3. Suivez sa réponse pour terminer la liaison, puis envoyez /bind dans votre groupe console — le bot répond « ✅ bound » et c'est terminé. Passez à l'étape 5 pour tester. Envoyez-lui /status en message privé à tout moment, ou /native en pour définir votre propre langue.
Inquiet à l'idée de confier le jeton ? Il est stocké chiffré et sert uniquement à relayer les discussions que vous avez autorisées dans Telegram Business — et vous gardez le contrôle : révoquez-le à tout moment dans BotFather (/mybots → API Token → Revoke) et l'ancien jeton meurt instantanément.

💻 Option B · Auto-hébergé (votre propre machine, vos propres données)

Récupérez d'abord une clé de traduction sur console.anthropic.com → API Keys → Create Key (sk-ant-… ; quelques dollars de crédit durent longtemps à ~$0.001 par message). Ensuite :

git clone https://github.com/sanxiaozi/lingodesk.git cd lingodesk npm install cp .env.example .env # open .env — only BOT_TOKEN and ANTHROPIC_API_KEY are required npm run db:push # initialize the database (first run only) npm run dev 🚀 LingoDesk is up, bot = @my_lingodesk_bot

Une fois la bannière affichée, envoyez /bind dans votre groupe console pour le lier (l'ID du groupe et votre ID utilisateur sont détectés automatiquement — aucun numéro à rechercher). Sur un serveur, Docker tient en une commande : docker compose up -d — voir le README GitHub.

Un jeton de bot = une seule instance en cours, à l'échelle mondiale (409 Conflict = un ancien processus le détient encore). Si nous vous hébergeons, ne faites pas tourner aussi une instance locale.

5Testez la discussion

Depuis un autre compte Telegram (un second compte ou un ami), envoyez un message privé en langue étrangère à votre compte personnel (pas au bot !) — par exemple « Hola, ¿cuánto cuesta? » en espagnol. En quelques secondes, un nouveau sujet portant le nom de l'expéditeur devrait apparaître dans votre groupe console :

📋 Console LingoDesk · sujet : @amigo_es
my_lingodesk_bot🆕 Nouveau contact @amigo_es (es)
Original : Hola, ¿cuánto cuesta?
🌐 Bonjour, combien ça coûte ?
─────
↳ Écrivez ici dans votre langue — cela part en es, envoyé en votre nom
Le forfait A est à $100 et comprend toutes les fonctionnalités.
my_lingodesk_bot📤 Aperçu de la traduction (→es), envoyé seulement après votre confirmation :

El paquete A cuesta 100 dólares e incluye todas las funciones.

(Votre message : Le forfait A est à $100…)

[ ✅ Envoyer au client ] [ ✏️ Annuler ]

Appuyez sur « ✅ Envoyer au client » — l'autre partie voit votre compte personnel répondre dans un espagnol parfaitement fluide. Toute la boucle est désormais active 🎉

🔧 Dépannage

Un client m'a écrit mais rien n'apparaît dans le groupe console

Vérifiez dans l'ordre : ① BotFather → Business Mode est activé (étape 1a) ; ② Telegram Business → Chatbots comporte bien votre bot lié et cette discussion est dans le périmètre (étape 2) ; ③ le bot est administrateur du groupe avec « Manage Topics » (étape 3) ; ④ le groupe console est lié — envoyez-y /bind ; ⑤ auto-hébergeurs : le processus du bot tourne toujours sans erreurs.

Fenêtre contextuelle lors de l'ajout du bot : « This bot doesn't support Telegram Business yet »

Le Business Mode n'est pas activé dans BotFather (étape 1a). Allez dans @BotFather → /mybots → votre bot → Bot Settings → Business Mode → Turn on. Il prend effet immédiatement — inutile de recréer le bot ou de resoumettre le jeton ; retournez simplement dans Telegram Business → Chatbots et ajoutez-le à nouveau. Les utilisateurs hébergés dans le cloud peuvent envoyer /status en message privé à @LingoDeskbot pour revérifier ce point.

J'envoie /bind dans le groupe et rien ne se passe

① La confidentialité de groupe (Group Privacy) est encore activée (étape 1b) — désactivez-la, puis retirez et rajoutez le bot ; ② les sujets (Topics) ne sont pas activés sur le groupe ; ③ utilisateurs hébergés dans le cloud : assurez-vous que @LingoDeskbot a répondu « Activated » (envoyez-lui /status pour vérifier) ; ④ auto-hébergeurs : assurez-vous que le processus tourne.

Est-il sûr de confier mon BOT_TOKEN pour l'hébergement cloud ?

Le jeton est stocké chiffré et sert uniquement à relayer les discussions dans le périmètre que vous avez autorisé dans Telegram Business — et vous pouvez exclure des contacts privés (étape 2). Vous gardez le contrôle : révoquez-le à tout moment via BotFather → /mybots → API Token → Revoke ; l'ancien jeton meurt instantanément et le service s'arrête. Pour reprendre, envoyez simplement le nouveau jeton à @LingoDeskbot.

Je tape dans un sujet et le bot ne fait rien

Neuf fois sur dix, c'est la confidentialité de groupe (Group Privacy) encore activée (étape 1b). BotFather → Bot Settings → Group Privacy → Turn off, puis retirez le bot du groupe et rajoutez-le (le changement ne s'applique qu'après réintégration), et promouvez-le à nouveau administrateur.

Le démarrage échoue avec 409 Conflict

Deux instances tournent sur le même jeton. Trouvez et arrêtez l'ancien processus (Ctrl+C ou pkill -f "tsx.*main.ts"), attendez dix secondes, redémarrez.

« Envoyer au client » échoue avec une erreur générique

Vérifiez par ordre de probabilité : ① l'autorisation « Reply to messages » est désactivée (le plus fréquent) — Réglages → Telegram Business → Chat Automation (Chatbots) → votre bot → activez « Reply to messages » ; sans elle le bot peut lire mais jamais envoyer ; ② la discussion du client n'est pas dans le périmètre des discussions accessibles au bot (même page) ; ③ le contact ne vous a pas écrit depuis plus de 24 heures — Telegram bloque les envois initiés par un bot ; demandez-lui d'envoyer quelque chose d'abord. Utilisateurs hébergés dans le cloud : envoyez /status en message privé à @LingoDeskbot — la ligne « reply permission » vous donne directement la réponse.

« Envoyer au client » échoue : contact inactif depuis trop longtemps

Une restriction de Telegram : si une conversation est restée inactive trop longtemps, le bot ne peut pas prendre l'initiative en votre nom (BUSINESS_PEER_USAGE_MISSING). Demandez-lui d'envoyer quelque chose pour la réactiver, ou répondez manuellement depuis votre téléphone cette fois-ci.

L'envoi échoue : connexion business invalide

Allez dans Réglages → Telegram Business → Chatbots, retirez et rajoutez le bot — ou attendez simplement le prochain message du client, qui permet au bot de capturer automatiquement une nouvelle connexion.

Mauvaise langue détectée / envie d'une autre langue cible

La langue se verrouille au premier message du contact (pour éviter de basculer sans cesse sur des textes courts). Envoyez /lang code dans le sujet de ce contact pour la corriger, p. ex. /lang pt (portugais) ou /lang ar (arabe).

Après un redémarrage, les anciens boutons « Envoyer / Annuler » ne fonctionnent plus

Les aperçus en attente vivent en mémoire et expirent au redémarrage (le bouton vous le dira). Retapez simplement votre réponse dans le sujet. Les contacts et l'historique des discussions vivent dans la base de données — rien n'est perdu.

🎉 Tout fonctionne ?

Désormais, vos clients écrivent dans la langue qu'ils veulent — vous n'avez qu'à taper dans la vôtre. Si quelque chose se casse, parcourez d'abord la liste de dépannage ci-dessus ; toujours bloqué, écrivez-nous avec une capture d'écran de l'erreur du terminal.

✉️ [email protected]