Comment connecter HappyCapy à Telegram : un agent IA complet dans n'importe quel chat
Votre agent HappyCapy — avec tous ses outils, compétences et capacités — accessible directement depuis Telegram.
La plupart des bots Telegram répondent à des questions. Le pont Telegram de HappyCapy exécute claude --print — chaque message que vous envoyez déclenche une session Claude Code complète avec accès à Bash, opérations sur les fichiers, recherche web, génération d'images, et plus de 300 000 Skills. Demandez-lui de scraper un site web, d'écrire un script Python et de l'exécuter, ou de générer une vidéo. Il le fera. Ce n'est pas un chatbot. C'est un agent qui vit dans votre chat Telegram.
Pourquoi c'est différent d'un bot Telegram
Créer un bot Telegram est un projet de week-end. Vous vous enregistrez auprès de BotFather, obtenez un token, appelez l'API Bot Telegram, transmettez les messages entrants à une API LLM, renvoyez la réponse. Le résultat est une machine d'autocomplétion sophistiquée. Elle n'a pas de système de fichiers. Elle ne peut pas exécuter de code. Elle ne peut pas déclencher de workflows. Elle ne peut rien faire que l'API LLM ne puisse faire en une seule réponse sans état.
L'architecture de HappyCapy est différente à chaque niveau. HappyCapy fonctionne comme un sandbox Linux toujours actif sur Fly.io — accès root, Python 3.11, Node.js v24, stockage de fichiers persistant. Lorsque votre message Telegram arrive, le pont appelle claude --print avec votre message en entrée. Cette invocation dispose d'un accès complet aux outils : exécution Bash, lecture/écriture de fichiers, recherche web, génération d'images, génération de vidéos, et l'ensemble de la bibliothèque de plus de 300 000 Skills. L'agent peut ouvrir un nouveau shell, exécuter un script, lire la sortie, et vous la renvoyer — le tout dans le même tour de conversation.
L'écart pratique entre ces deux approches n'est pas incrémental. Un bot Telegram générique peut vous donner la météo. Le bot Telegram de HappyCapy peut écrire du code pour extraire des données météo de trois API, les comparer, tracer un graphique, l'enregistrer en PNG, et vous l'envoyer sous forme d'image — en un seul message, sans quitter Telegram.
| Fonctionnalité | Bot Telegram générique | Bot Telegram HappyCapy |
|---|---|---|
| Répond aux questions | Oui | Oui |
| Exécute des commandes Bash | Non | Oui |
| Écrit et exécute du code | Non | Oui |
| Accède à des fichiers persistants | Non | Oui |
| Génère des images IA | Non (nécessite une intégration séparée) | Oui, nativement |
| Génère de la vidéo | Non | Oui |
| Web scraping | Non | Oui |
| Accès à plus de 300 000 Skills | Non | Oui |
| Fonctionne 24h/24 sans votre ordinateur | Non | Oui (Fly.io toujours actif) |
| Historique de conversation par utilisateur | Limité | Complet, persistant |
Ce que vous pouvez réellement faire
La liste des capacités n'est pas théorique. Voici des choses que les utilisateurs font aujourd'hui :
- Demander au bot de scraper un site web et de renvoyer des données structurées sous forme de tableau ou de JSON
- Lui faire écrire un script Python, l'exécuter dans le sandbox, et renvoyer la sortie stdout — sans avoir besoin d'IDE
- Générer une image IA à partir d'un prompt et la recevoir directement dans le chat Telegram
- Déclencher n'importe lequel des plus de 300 000 Skills de HappyCapy en pleine conversation — génération de PDF, création de tableurs, diapositives PPTX, synthèse audio
- Rechercher sur le web, lire plusieurs sources, et renvoyer un résumé synthétisé avec citations
- Créer et enregistrer des fichiers dans un stockage persistant, puis les récupérer ou les mettre à jour dans des messages ultérieurs
- Exécuter des tâches planifiées : l'agent peut lancer un script chaque matin et vous envoyer le résultat
- Surveiller une URL ou un point de terminaison d'API et vous alerter en cas de changement
- Traiter des documents téléchargés — collez un lien CSV, obtenez une analyse en retour
- Enchaîner des workflows multi-étapes qui nécessiteraient autrement de passer entre cinq outils différents
Avantages
- Toujours actif, aucun ordinateur portable requis. Le sandbox fonctionne sur l'infrastructure Fly.io. Vous pouvez envoyer un message au bot depuis votre téléphone à 2h du matin et il exécutera du code sur un serveur que vous n'aurez jamais à toucher.
- Interface unique pour tout. Au lieu d'ouvrir Claude, puis un éditeur de code, puis un navigateur, puis un outil d'image — un seul message Telegram déclenche tout cela.
- Le contexte persiste. L'historique de conversation est stocké par utilisateur. Vous pouvez faire référence à quelque chose que vous avez demandé il y a trois jours sans avoir à réexpliquer le contexte.
- Accès root complet dans le sandbox. L'agent peut installer des paquets, écrire des fichiers, et exécuter n'importe quelle commande Unix. Aucune restriction qu'un chatbot grand public imposerait.
- Plus de 300 000 Skills disponibles instantanément. Tout workflow qui a été packagé comme un Skill HappyCapy est à une phrase de distance.
- Partageable. Donnez le nom d'utilisateur du bot à un collègue ou un client. Plusieurs utilisateurs peuvent interagir simultanément, chacun avec un historique de conversation isolé.
- Niveau gratuit disponible. Le pont Telegram lui-même n'ajoute aucun coût en plus de votre plan HappyCapy existant.
Cas d'usage réels
Le développeur freelance qui a laissé son ordinateur portable au bureau. Vous avez poussé un commit, repéré un bug dans les journaux de déploiement, et vous êtes déjà sur le point de partir. Depuis votre téléphone, vous envoyez un message au bot : « Récupère les derniers journaux de déploiement du serveur et dis-moi ce qui pose problème à la ligne 847. » Trente secondes plus tard, vous avez la réponse. Vous répondez : « Écris un correctif et ouvre une PR. » C'est fait. Aucun ordinateur portable ouvert.
Le propriétaire de petite entreprise qui surveille des métriques quotidiennement. Au lieu de se connecter à cinq tableaux de bord chaque matin, le bot exécute un résumé planifié. Chaque jour à 8h : il récupère les données de revenus depuis Stripe, le nombre de visiteurs depuis une API d'analytics, et les niveaux de stock depuis Shopify. Il formate le résumé et l'envoie sous forme de message Telegram avant que le premier café ne soit terminé. La configuration a pris une seule conversation avec le bot.
Le chercheur qui a besoin d'une extraction rapide de données. Vous lisez un article et voulez recouper un jeu de données provenant de trois autres sources. Passer à un navigateur, naviguer vers chaque source, télécharger des CSV, et exécuter une comparaison prend 20 minutes. Envoyer un message au bot avec les URL et une description de ce dont vous avez besoin prend deux minutes. Le bot scrape, analyse, compare, et renvoie un tableau.
Le parent qui a mis en place une aide aux devoirs. Les enfants ont déjà un compte Telegram. Le bot HappyCapy a été ajouté à un groupe familial. Il peut expliquer des problèmes de mathématiques étape par étape, générer des diagrammes, écrire des questions d'entraînement, et vérifier les réponses — sans publicités, sans création de compte, et sans la boucle de distraction d'un chatbot grand public. Le parent conserve le token administrateur ; les enfants obtiennent un outil ciblé.
Comment le configurer
La configuration prend moins de cinq minutes si vous avez un compte HappyCapy. Le processus commence avec BotFather de Telegram : envoyez un message à @BotFather, exécutez /newbot, choisissez un nom, et recevez un token de bot — une chaîne qui ressemble à 7384920156:AAF.... Ce token est tout ce dont HappyCapy a besoin pour savoir où router les conversations.
À l'intérieur de HappyCapy, le Skill Telegram s'occupe du reste. Exécutez le Skill, collez votre token de bot lorsque demandé, et le pont est actif. Le Skill démarre une boucle de polling dans le sandbox qui écoute les messages Telegram entrants et les route via claude --print avec un accès complet aux outils. L'historique de conversation est stocké par ID d'utilisateur Telegram, de sorte que chaque personne qui envoie un message à votre bot obtient sa propre session persistante.
Le Skill complet avec les scripts de configuration, la documentation des variables d'environnement, et les options de configuration pour la limitation de débit et les listes d'autorisation d'utilisateurs est disponible sur github.com/ndpvt-web/happycapy-telegram. Si vous souhaitez comprendre plus en profondeur pourquoi l'architecture d'agent de HappyCapy diffère d'une configuration de chatbot typique avant de commencer, AI Agent vs Chatbot couvre cette distinction en détail. Et si vous envisagez de faire fonctionner votre propre infrastructure IA persistante au lieu de dépendre de Fly.io, l'analyse Mac Mini as AI Server 2026 vaut la peine d'être lue d'abord.
Questions fréquemment posées
Le bot fonctionne-t-il 24h/24 ou seulement lorsque mon ordinateur est allumé ? Il fonctionne 24h/24. Le sandbox vit sur l'infrastructure de Fly.io, pas sur votre machine locale. Une fois que vous déployez le Skill Telegram, il reste actif sans que votre ordinateur soit allumé ou même connecté à internet.
Le bot peut-il accéder à mes fichiers et outils HappyCapy ? Oui. Le bot fonctionne à l'intérieur de votre sandbox HappyCapy, ce qui signifie qu'il a accès à tout ce qui se trouve dans cet environnement : les fichiers que vous avez stockés, les skills que vous avez installés, les variables d'environnement que vous avez définies, et toutes les intégrations que vous avez connectées. C'est votre agent, accessible via une interface différente.
Est-ce gratuit à utiliser ? Le Skill du pont Telegram lui-même est gratuit. Vos coûts sont déterminés par votre plan HappyCapy, qui couvre le calcul du sandbox et l'utilisation du modèle IA. Il n'y a pas de frais supplémentaires pour la couche d'intégration Telegram.
Comment fonctionne l'historique de conversation par utilisateur ? Chaque ID d'utilisateur Telegram obtient son propre fil de conversation stocké dans le sandbox. Lorsque l'utilisateur A envoie un message, le bot charge l'historique de l'utilisateur A et y ajoute le nouveau tour. Les messages de l'utilisateur B sont complètement isolés. L'historique est persistant entre les sessions — une conversation que vous avez eue il y a une semaine reste accessible dans le contexte, sauf si vous l'effacez explicitement.
Puis-je restreindre qui peut utiliser le bot ? Oui. Le Skill prend en charge une configuration de liste d'autorisation. Vous pouvez spécifier une liste d'ID utilisateur Telegram ou de noms d'utilisateur autorisés à interagir avec le bot. Les messages des utilisateurs qui ne sont pas sur la liste d'autorisation sont ignorés silencieusement ou renvoient un message de rejet personnalisé — à votre choix.
Que se passe-t-il si Telegram limite le débit de mon bot ? Le Skill gère la limitation de débit avec un backoff exponentiel. Si Telegram renvoie une réponse 429, le pont fait une pause, attend la période de nouvelle tentative requise, et reprend automatiquement. Vous ne perdrez aucun message. En pratique, les limitations de débit ne se déclenchent que sous une charge simultanée élevée, ce qui est configurable dans les paramètres du Skill.
Plusieurs personnes peuvent-elles utiliser le bot simultanément ? Oui. La boucle de polling traite les messages de manière asynchrone, et chaque session utilisateur est indépendante. Il n'y a pas de file d'attente qui bloque un utilisateur pendant qu'un autre est servi. Sous une charge très élevée, vous pouvez faire évoluer l'instance du sandbox sur Fly.io pour gérer davantage de sessions simultanées — la documentation du Skill couvre cette configuration.
Réflexions finales
L'intégration Telegram n'est pas une fonctionnalité pour elle-même — elle supprime le dernier point de friction entre vous et un agent IA pleinement capable. Votre sandbox HappyCapy exécute déjà du code, génère des médias, et orchestre plus de 300 000 Skills. Le pont Telegram signifie que vous accédez à tout cela depuis où que vous soyez déjà, sans changement de contexte. Que ce soit utile à 2h du matin lorsque vous déboguez à distance ou utile chaque matin lorsque vous voulez un briefing structuré avant d'ouvrir votre ordinateur portable — c'est le même agent, désormais disponible dans chaque poche.
