⚙️ Documentation technique - Bot et Integrations Tchap
Les projets de la communauté Tech x Tchap communiquent dans le salon Tchap suivant : https://tchap.gouv.fr/#/room/#BotsetIntgrationsTchapU2tHdMEN80D:agent.dinum.tchap.gouv.fr
Des webinaires sont organisés régulièrement. Les notes partagées se trouvent ici
Les besoins remontés lors des webinaires Tech x Tchap se regroupent dans deux cas d'usage principaux :
- les webhooks
Exemple : dans un salon Tchap, un service de monitoring envoient des messages lorsqu'un serveur informatique rencontre des problèmes.
- les bots
Exemple : un programme informatique automatise des actions dans un salon comme répondre à des messages, inviter des nouveaux membres, exécuter des commandes.
Plus d'information sur le chiffrement ici :
⚙️ Documentation technique - Le chiffrement dans Tchap
Maubot (python) : https://docs.mau.fi/
Matrix Nio (python) : https://github.com/poljar/matrix-nio
Matrix-Bot-sdk (typescript) : https://turt2live.github.io/matrix-bot-sdk/index.html
Tout le personnel qui possède une adresse mail en *.gouv.fr peut créer un compte sur les serveurs de développement Tchap https://www.tchap.incubateur.net. Comme ce sont des serveurs de développement, ils sont considérés instables et peuvent être réinitialisés sans préavis par l'équipe Tchap.
De manière à bien identifier qu'un compte Tchap est associé à un bot, nous vous recommandons de préfixer l'email associé par "bot-" (exemple : "bot-veille-web@culture.gouv.fr").
Le compte utilisateur utilisé par le bot doit être créé manuellement (via Tchap web par exemple) comme un compte utilisateur classique (avec un email dédié et autorisé donc).
C'est un compte utilisateur classique (associé à une adresse email), soumis aux mêmes possibilités et contraintes que tout autre compte utilisateur :
ce qui peut être fait ou configuré sur un compte utilisateur classique peut donc être fait sur un compte bot
ce qui ne peut pas être fait avec un compte utilisateur classique ne peut pas être fait par un compte bot non plus
Un compte pour bot est donc soumis à la procédure de renouvellement périodique de compte via email. La notion de "compte de service" n'existe pas actuellement sur Tchap .
Il est dangereux de se reconnecter à chaque appel API car cela créé des dizaines voir des centaines de sessions et un grand volume de données.
Il faut partager le access token à chaque appel.
Lors de l'invitation en masse d'utilisateur dans un salon, il faut respecter un certain délai entre deux invitations pour ne pas déclencher les rate-limit sur le serveur Synapse ou sur les serveurs frontaux web.
Une bonne pratique est de respecter un rythme d'un appel API par seconde.
Des webinaires sont organisés régulièrement. Les notes partagées se trouvent ici
Projets communautaires
Les besoins remontés lors des webinaires Tech x Tchap se regroupent dans deux cas d'usage principaux :
- les webhooks
Exemple : dans un salon Tchap, un service de monitoring envoient des messages lorsqu'un serveur informatique rencontre des problèmes.
| Projets | Library utilisé | Language | Encryption |
|---|---|---|---|
| https://github.com/numerique-gouv/tchap-bot-webhook | matrix-bot-sdk | js | no |
- les bots
Exemple : un programme informatique automatise des actions dans un salon comme répondre à des messages, inviter des nouveaux membres, exécuter des commandes.
| Projets | Library utilisé | Language | Encryption |
|---|---|---|---|
| https://github.com/etalab-ia/albert-tchapbot | https://github.com/imbev/simplematrixbotlib | Python | NA |
| https://github.com/tchapgouv/tchap-bot-mte/tree/master/backend | matrix-js-sdk +pantalaimon | NodeJs | oui par pantalaimon |
| https://forge.dgfip.finances.rie.gouv.fr/dgfip/esi-strasbourg/devops/maubot/maubot-compose | https://github.com/maubot/gitlab | python | NA |
| https://code.peren.fr/open-source/tchapbot | https://github.com/imbev/simplematrixbotlib | python | Oui via le paramètre ENCRYPTION_ENABLED dans matrix_bot/config.py |
Plus d'information sur le chiffrement ici :
⚙️ Documentation technique - Le chiffrement dans Tchap
Clients officiels de Matrix
Maubot (python) : https://docs.mau.fi/
Matrix Nio (python) : https://github.com/poljar/matrix-nio
Matrix-Bot-sdk (typescript) : https://turt2live.github.io/matrix-bot-sdk/index.html
Attentions particulières
Tester votre intégration sur nos serveurs de test
Tout le personnel qui possède une adresse mail en *.gouv.fr peut créer un compte sur les serveurs de développement Tchap https://www.tchap.incubateur.net. Comme ce sont des serveurs de développement, ils sont considérés instables et peuvent être réinitialisés sans préavis par l'équipe Tchap.
De manière à bien identifier qu'un compte Tchap est associé à un bot, nous vous recommandons de préfixer l'email associé par "bot-" (exemple : "bot-veille-web@culture.gouv.fr").
Le compte utilisateur du bot
Le compte utilisateur utilisé par le bot doit être créé manuellement (via Tchap web par exemple) comme un compte utilisateur classique (avec un email dédié et autorisé donc).
C'est un compte utilisateur classique (associé à une adresse email), soumis aux mêmes possibilités et contraintes que tout autre compte utilisateur :
ce qui peut être fait ou configuré sur un compte utilisateur classique peut donc être fait sur un compte bot
ce qui ne peut pas être fait avec un compte utilisateur classique ne peut pas être fait par un compte bot non plus
Un compte pour bot est donc soumis à la procédure de renouvellement périodique de compte via email. La notion de "compte de service" n'existe pas actuellement sur Tchap .
Se reconnecter à chaque appel
Il est dangereux de se reconnecter à chaque appel API car cela créé des dizaines voir des centaines de sessions et un grand volume de données.
Il faut partager le access token à chaque appel.
Respecter les rate-limit des serveurs
Lors de l'invitation en masse d'utilisateur dans un salon, il faut respecter un certain délai entre deux invitations pour ne pas déclencher les rate-limit sur le serveur Synapse ou sur les serveurs frontaux web.
Une bonne pratique est de respecter un rythme d'un appel API par seconde.
Mis à jour le : 24/04/2025
Merci !