Les interfaces de chat dominent le lieu de travail moderne : les équipes de production coordonnent leurs actions dans des conversations, les validations se font par e-mail, et les assistants basés sur des LLM deviennent une partie des opérations quotidiennes.
Le vrai problème, c’est l’intégration correcte. Un message qui dit « Shot prêt à être revu » devrait permettre à un superviseur d’approuver ce shot et de mettre à jour le statut dans Kitsu pour le bon utilisateur, mais, dans un monde idéal, cela nécessiterait un petit service backend, une connexion API sécurisée à Kitsu et un mappage fiable entre les utilisateurs du chat et les utilisateurs de Kitsu. Bonne nouvelle : vous pouvez déjà le faire avec Kitsu !
Un point de départ simple consiste à utiliser un bot Telegram avec une commande comme /hello. Le bot associe l’utilisateur du chat à son compte Kitsu une seule fois, puis répond via l’API et l’affiche dans le chat. À chaque fois qu’un événement survient dans Kitsu, le bot vous notifie. Cette petite intégration prouve le concept, et c’est exactement ce que nous allons construire dans cet article.
Pourquoi créer des intégrations de messagerie sur mesure
Les intégrations de messagerie sur mesure centralisent la communication autour d’une source unique de vérité. Au lieu que les superviseurs transfèrent des e-mails concernant un changement d’état d’une tâche, la mise à jour peut être envoyée automatiquement au canal de l’équipe concernée. Par exemple, lorsqu’une tâche d’éclairage passe sur « retake » dans Kitsu, le groupe Telegram de l’éclairage reçoit immédiatement un message structuré avec le nom du shot, l’assigné et la date limite. Le suivi de production devient proactif.
L’expérience utilisateur s’améliore lorsque des événements bruts de base de données sont transformés en résumés lisibles. Les artistes ne devraient pas avoir besoin de parcourir les journaux d’activité pour comprendre ce qui a changé. Un récapitulatif quotidien envoyé dans un canal Telegram peut résumer les validations, les nouvelles attributions et les dates limites à venir en langage clair. Ce récapitulatif peut être généré directement depuis l’API de Kitsu et livré automatiquement chaque soir afin de transformer les données de production en quelque chose que les gens consultent réellement.
Cette approche est là où l’automatisation prend vraiment tout son sens. Les plateformes de messagerie peuvent agir comme des interfaces de commande légères. Un coordinateur qui tape « /late_shots » sur Telegram peut déclencher une requête contre Kitsu et recevoir instantanément un rapport des tâches en retard. Un lead qui tape « /assign SH010 alice » peut déclencher un appel backend qui met à jour l’attribution dans Kitsu. Le chat devient une surface opérationnelle pour la base de données de production.
Mais comme nous l’avons dit, commençons simplement avec un bot Telegram qui interagit avec Kitsu.
1. Créer un nouveau bot Telegram
Commencez par créer un bot dédié dans Telegram. La séparation permet de garder les identifiants propres et d’éviter les futurs problèmes de sécurité lorsque l’intégration est confiée à l’IT de production.
Ouvrez Telegram et recherchez BotFather, qui est le bot officiel pour gérer d’autres bots.
Démarrez une conversation et envoyez /newbot. Le déroulement est simple : fournissez un nom lisible par des humains comme « Kitsu Notifications », puis un nom d’utilisateur unique, par exemple kitsu_pipeline_bot. Le nom d’utilisateur doit se terminer par « bot » et il doit être globalement unique : attendez-vous à tester plusieurs variantes dans un environnement de studio.
BotFather renvoie un jeton API. Traitez ce jeton comme un secret de production, pas comme une simple chaîne à coller dans Slack ou à valider sur Git. Enregistrez-le dans votre système de configuration d’environnement. Si ce jeton fuit, n’importe qui peut envoyer des messages comme votre bot de production, ce qui peut rapidement passer du divertissement au désastre lorsque des producteurs commencent à recevoir du spam.
Avant de l’intégrer au système d’événements de Kitsu, validons le jeton manuellement.
Recherchez votre bot nouvellement créé par son nom d’utilisateur dans Telegram et lancez une conversation avec lui. Envoyez un simple « /start » pour que Telegram enregistre votre chat.
Pour récupérer votre identifiant client (chat), appelez l’endpoint getUpdates avec curl en utilisant le jeton. Par exemple :
curl https://api.telegram.org/bot<TOKEN>/getUpdates
La réponse contiendra une charge utile JSON avec un objet chat et un champ id. Cet identifiant numérique est celui sur lequel votre intégration se basera. Dans un scénario de pipeline réel, il peut s’agir de l’ID de chat d’un groupe de superviseurs plutôt que d’un utilisateur individuel.
Testez maintenant l’envoi de messages sortants directement. Utilisez curl pour vous envoyer un message à vous-même :
curl -X POST https://api.telegram.org/bot<TOKEN>/sendMessage -d chat_id=<CHAT_ID> -d text="Kitsu integration test"
Si le message apparaît dans Telegram, le jeton et l’ID de chat sont valides. Cette étape de vérification manuelle permet de gagner des heures de débogage plus tard, lorsque vous branchez le même appel dans un hook d’événement Kitsu et que quelque chose échoue silencieusement.
Une fois le bot validé, l’étape suivante consiste à le connecter au système d’événements de Kitsu pour que, par exemple, lorsqu’un nouvel asset est créé, un message soit automatiquement envoyé au groupe Telegram des superviseurs.
Le même endpoint sendMessage que vous avez testé avec curl devient une partie d’un petit service ou d’une fonction sans serveur déclenchée par Kitsu.
2. Configurer un écouteur d’événements Kitsu
Ensuite, nous devons nous abonner aux événements en temps réel provenant de Kitsu. L’objectif est simple : réagir dès que les données de production changent.
Nous pouvons utiliser le SDK Python zou de Kitsu pour ouvrir une connexion websocket et écouter les événements de mise à jour des tâches.
Par exemple, connectez-vous au flux d’événements Kitsu et filtrez les événements de création d’assets :
import gazugazu.set_host("http://localhost:80/api") gazu.set_event_host("http://localhost:80/api") gazu.log_in("admin@example.com", "mysecretpassword")
def my_callback(data): print("Asset created %s" % data"asset_id")
event_client = gazu.events.init() gazu.events.add_listener(event_client, "asset:new", my_callback) gazu.events.run_client(event_client)
Nous utilisons la bibliothèque gazu pour nous connecter à un serveur API Kitsu hébergé localement à http://localhost:80/api, pour nous authentifier avec les identifiants admin fournis, puis pour écouter les événements en temps réel.
Le snippet définit une fonction de rappel my_callback qui affiche l’ID d’un nouvel asset créé, chaque fois qu’elle est déclenchée.
Après avoir initialisé un client d’événements avec gazu.events.init(), le script enregistre le rappel pour écouter l’événement "asset:new" (qui se déclenche chaque fois qu’un nouvel asset est créé dans le système).
gazu.events.run_client(event_client) démarre la boucle d’événements qui maintient le script en exécution afin que, chaque fois qu’un nouvel asset est ajouté dans Kitsu, le rappel s’exécute et affiche son asset_id.
3. Utiliser l’API Telegram pour envoyer un message
Pendant que les événements arrivent, envoyez des messages via l’endpoint sendMessage de Telegram comme nous l’avons fait plus tôt pour les tests. L’API n’est qu’un HTTP POST qui inclut le jeton du bot, l’ID du chat et la charge utile de texte.
Encapsulez cela dans une petite fonction utilitaire :
import requests import osTELEGRAM_BOT_TOKEN = os.getenv('TELEGRAM_BOT_TOKEN') TELEGRAM_CHAT_ID = os.getenv('TELEGRAM_CHAT_ID')
def send_telegram_message(text): url = f"https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/sendMessage" payload = { "chat_id": TELEGRAM_CHAT_ID, "text": text, "parse_mode": "Markdown" }
response = requests.post(url, json=payload, timeout=5) if not response.ok: raise RuntimeError( f"Telegram API error {response.status_code}: {response.text}" )
Notez que nous avons défini des variables d’environnement secrètes pour éviter de les conserver dans un dépôt Git.
Puis appelez-la depuis le callback d’événement :
from your_telegram_module import send_telegram_message
def my_callback(data): send_telegram_message("Asset created %s" % data"asset_id")
Pour tester notre écouteur d’événements :
TELEGRAM_BOT_TOKEN=<TELEGRAM_BOT_TOKEN> TELEGRAM_CHAT_ID=<CHAT_ID> python server.py
4. Recevoir des messages avec un endpoint API Kitsu personnalisé
Les notifications sont utiles, mais la communication bidirectionnelle est là où l’intégration devient vraiment intéressante.
Pour cela, nous devons étendre le backend de Kitsu avec un plugin personnalisé qui enregistre une nouvelle route comme /plugins/telegram/webhook. Veuillez consulter notre guide officiel sur le développement de plugins Kitsu pour les étapes détaillées.
Le manifeste ressemblera à ceci :
id = "telegram"
name = "Telegram Bot"
description = "Telegram Bot"
version = "0.1.0"
maintainer = "Frank Rousseau <frank@cg-wire.com>"
website = "kitsu.cloud"
license = "AGPL-3.0-only"
maintainer_name = "Frank Rousseau"
maintainer_email = "frank@cg-wire.com"
frontend_project_enabled = true
frontend_studio_enabled = true
icon = "telegram"
Et notre route personnalisée analysera les commandes entrantes et les associera à des actions backend explicites :
from flask_restful import Resourceclass WebhookResource(Resource): def post(self): args = self.get_args( ("message", {}, True), ("chat", {}, True), )
message = args['message'] chat_id = args['chat'].get("id") text = message.get("text", "") if text == "/hello": send_telegram_message("it works") return jsonify({"status": "ok"})
Par souci de simplicité, nous définissons une seule commande /hello, mais vous pouvez en créer bien d’autres et utiliser des services Kitsu pour interroger des données de production.
Les commandes déterministes sont plus faciles à tester, journaliser et sécuriser. Vous pouvez aller plus loin en appelant un LLM pour mapper une demande en langage naturel vers une commande.
Il suffit d’enregistrer la route dans l’entrée principale init.py :
from . import resources
routes = (f"/telegram/webhook", resources.WebhookResource)
Après avoir empaqueté et installé votre plugin sur votre instance de serveur Kitsu, il est temps d’indiquer à votre bot Telegram comment l’atteindre.
Si vous utilisez un environnement de développement local, vous pouvez exposer le serveur via un tunnel. Par exemple, avec ngrok, si votre serveur tourne sur le port 5000 :
ngrok http 5000
Vous devez ensuite configurer le webhook de votre bot Telegram pour pointer vers cette URL :
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook"
-H "Content-Type: application/json"
-d '{"url": "https://<random>.ngrok-free.app/plugin/telegram/webhook"}'
Envoyez maintenant /hello à votre bot dans votre conversation Telegram et observez le résultat :
Conclusion
Une intégration de messagerie sur mesure avec Kitsu suit toujours un schéma similaire : créer un bot sur une plateforme de messagerie, s’abonner aux événements de Kitsu, envoyer des notifications structurées et exposer des routes backend pour gérer les messages entrants.
Mais ce n’est pas tout : pensez aussi à étendre votre plugin Kitsu avec des vues !
Par exemple, pour afficher l’activité du bot ou les interactions récentes directement dans le tableau de bord. Les superviseurs travaillant à l’intérieur de Kitsu pourront voir quelles alertes ont été envoyées et quelles commandes ont été déclenchées. Les possibilités sont infinies !
