Développer sur Antimatter

Ce guide s'adresse aux développeurs. Il couvre les scripts et les bots utilisant l'API, les intégrations basées sur les webhooks et les commandes slash, les applications (plugins) qui ajoutent des fonctionnalités au serveur et à l'application web, ainsi que la compilation d'Antimatter depuis le code source pour y contribuer.

Les façons d'étendre Antimatter

Choisissez l'outil le plus léger qui fait le travail. Les quatre premiers n'exigent aucun accès au serveur lui-même ; les applications s'exécutent à l'intérieur.

Outil	Fonction	Idéal pour
API REST	Tout ce que les applications font : messages, canaux, utilisateurs, fichiers, paramètres. Un WebSocket transmet les événements au fur et à mesure.	Scripts, synchronisation avec d'autres systèmes, clients personnalisés.
Webhooks entrants	Une URL secrète qui publie un message dans un canal lorsqu'un système lui envoie du JSON.	Alertes, résultats de CI, supervision, notifications provenant d'autres outils.
Webhooks sortants	Antimatter appelle votre URL lorsqu'un message dans un canal public commence par un mot déclencheur, ou lorsque quelqu'un sélectionne votre action dans le menu d'un message, puis publie votre réponse.	Des automatisations simples pilotées par la discussion, envoyant un message à un autre outil.
Commandes slash	Les personnes saisissent `/something` ; Antimatter appelle votre URL et affiche votre réponse à la personne ou au canal.	Recherches, actions initiées depuis la discussion.
Bots	Comptes créés pour des programmes, avec leurs propres jetons, une étiquette BOT, et des messages et dialogues interactifs.	Assistants, notificateurs, tout ce qui communique avec les utilisateurs.
Applications (plugins)	Code qui s'exécute à l'intérieur du serveur (Go) et de l'application web (React) : crochets sur chaque message, nouveaux menus, panneaux, types de messages, pages.	Fonctionnalités : sondages, notes, calendriers, intégrations nécessitant l'interface utilisateur.

Dans l'interface, les utilisateurs appellent les plugins « applications ». Ce guide utilise « applications (plugins) » lorsque les deux termes sont utiles, car le code, l'API et la configuration utilisent toujours le terme « plugin ».

Compatibilité avec Mattermost

Antimatter est une fourche de Mattermost. La plupart des fonctionnalités qui fonctionnent avec un serveur Mattermost fonctionnent avec Antimatter.

Ce qui est identique

L'API REST sous /api/v4, son authentification, son WebSocket et son format d'erreurs. Le serveur signale la version 12.0.0, de sorte que les clients et les applications qui vérifient la version du serveur voient une version récente de Mattermost.
Webhooks et commandes slash, y compris leurs charges utiles compatibles Slack.
L'API et les hooks du serveur : Antimatter les conserve tels quels. Le code serveur est construit sur le même module Go, github.com/mattermost/mattermost/server/public. Antimatter n'ajoute que des méthodes, pour son service IA (voir Le service IA).
Le registre de plugins de l'application web : chaque méthode register… du registre de Mattermost est présente dans les deux interfaces web d'Antimatter.
Bibliothèques client : le client Go model.Client4 et le client TypeScript @mattermost/client (voir Bibliothèques client).
Paquets de plugins : un fichier .tar.gz contenant un manifeste plugin.json. Les plugins signés avec la clé de Mattermost s'installent, tout comme ceux signés avec la clé d'Antimatter.

Ce qui est différent

Deux interfaces web. La nouvelle interface, Fusion, est celle par défaut ; l'interface classique de Mattermost reste disponible. Fusion affiche la plupart des composants des plugins, mais en place certains différemment et en omet quelques-uns. Une application peut déterminer quelle interface est en cours d'exécution. Voir Prise en charge de l'interface Fusion.
API supplémentaire. Antimatter ajoute des points de terminaison pour ses propres fonctionnalités : attributs de la communauté, délais d'attente, messages en tête, demandes de message, substitutions de canal et de catégorie, export de canal, déplacement de fils de discussion, connexions de modèles, actions de message, et nouveaux champs sur les communautés. Voir Ce qu'Antimatter ajoute à l'API.
Fonctionnalités de message supplémentaires. Les pièces jointes des messages peuvent afficher des étapes de pipeline et un petit graphique ; les publications peuvent être des réponses en ligne ou des spoilers.
Webhooks supplémentaires pour l'application web destinés aux applications : un élément de menu « + » dans la zone de composition, des onglets dans le sélecteur d'emojis, un panneau dans la vue du canal, un pied de page sous les canaux de la barre latérale, une entrée sur les pages d'intégrations, les vues d'ajout et de gestion du sélecteur d'emojis, et un panneau latéral qui se rouvre à l'endroit où il se trouvait dans une nouvelle fenêtre. Voir Hooks propres à Antimatter.
Aucune licence. Toutes les fonctionnalités sont disponibles sans clé de licence. Les points de terminaison de licence, d'essai et de mise à niveau entreprise ont été supprimés ; GET /api/v4/license/client reste disponible pour les clients qui en font la demande. Certaines applications conçues pour les éditions payantes de Mattermost vérifient elles-mêmes la présence d'une licence et refusent de s'exécuter.
Noms. Les équipes sont appelées « communautés » dans l'interface, mais l'API et le code continuent d'utiliser le terme team. Les variables d'environnement utilisent le préfixe AM_, l'outil en ligne de commande est amctl et le binaire du serveur est antimatter.

Où se trouve le code

Tout est open source, dans l’organisation AntimatterChat sur GitHub. Chaque dépôt fonctionne sur sa branche main.

Dépôt	Contenu
antimatter	Le serveur (Go, dans `server/`), les deux interfaces web (`webapp/fusion` et `webapp/channels`), le client TypeScript et `amctl`.
antimatter-docker	Les images Docker, avec les applications intégrées, et les fichiers compose.
`antimatter-plugin-*`	Un dépôt par application intégrée : polls, todo, notes, whiteboard, calendar, mail, gifs, memes, voice-channels, calls, boards (Kanban), playbooks, agents et metrics.
gifs-server	Le service auto-hébergé de GIF et de stickers utilisé par l’application GIFs.
desktop-app, mobile-app, push-proxy	Les applications de bureau et mobiles, ainsi que le service qui relaie les notifications push vers les téléphones.
antimatter.chat	Ce site web et sa documentation.
community	Problèmes et discussions pour chaque partie d’Antimatter.

Avant de commencer

Obtenez un serveur de test. La méthode la plus rapide est l'image Docker : voir Installer Antimatter. Pour travailler sur Antimatter lui-même, voir Compiler à partir du code source.
Vérifiez ce que le serveur autorise. Plusieurs fonctionnalités d'intégration sont désactivées par défaut et nécessitent un administrateur système : jetons d'accès personnels, comptes de bot, personnalisation des noms d'utilisateur et des icônes, et envoi d'applications. Chaque page indique le paramètre requis.
Connaisssez l'URL de votre site. Les exemples utilisent https://chat.example.com. Remplacez-la par l'adresse de votre serveur.

Dans ce guide

L'API REST : authentification, ressources principales, pagination, erreurs, limites de débit, WebSocket, bibliothèques clientes et ajouts d'Antimatter.
Webhooks : webhooks entrants et sortants, charges utiles, pièces jointes et cartes.
Commandes slash : commandes personnalisées, leurs requêtes et réponses, autocomplétion.
Bots et messages interactifs : comptes de bot, boutons, menus et dialogues.
Écrire des applications : structure des plugins, hooks serveur, registre de l'application web, Fusion, paramètres, stockage, traductions et packaging.
Compiler à partir du code source : le serveur, les interfaces web, l'image Docker et les applications.
Contribuer : problèmes, demandes de tirage, style, traductions, sécurité et licences.

Les questions sont les bienvenues dans les discussions de la communauté. Signalez les bogues dans les problèmes de la communauté.