Mattermost

Client REST v4 par interrogation et WebSocket. Par défaut, le bot interroge les canaux toutes les 3 secondes pour les nouveaux posts ; définissez listen_mode = "websocket" pour une diffusion d’événements quasi en temps réel via une connexion WebSocket persistante. Les posts de réponse sont toujours envoyés via POST /api/v4/posts, quel que soit le mode d’écoute.

Qui peut parler à l’agent

Les expéditeurs entrants sont filtrés par rapport au peer set résolu pour l’agent lié, issu de la configuration peer_groups à laquelle l’agent appartient. La correspondance supprime le @ initial et est insensible à la casse par rapport à l’identifiant d’expéditeur natif du canal. Un ensemble vide refuse tout le monde ; un ensemble contenant "*" accepte n’importe qui ; sinon, seuls les pairs externes listés (et les agents pairs) sont acceptés. Ceci est distinct de l’appairage de la passerelle (gateway.require_pairing), qui authentifie les clients HTTP/WebSocket, et non les expéditeurs des canaux de discussion.

Un groupe de pairs pour mattermost définit channel à mattermost, liste les expéditeurs autorisés dans external_peers (pour mattermost, l’UUID de l’utilisateur Mattermost (et non un nom d’utilisateur) ; ["*"] accepte tout le monde), nomme éventuellement des agents pairs pour la distribution inter-agents, une liste de blocage ignore, et une output_modality (mirror, voice ou text). Consultez Peer Groups pour la référence des champs.

Où définir ce paramètre :

Pour ajouter un humain spécifique à la liste d’autorisation, copiez son ID utilisateur depuis System Console → User Management. Mattermost effectue la correspondance avec l’UUID de l’utilisateur, et non un nom d’utilisateur, et ne résout pas les noms d’utilisateur au moment de la réception du message.

Démarrage rapide

Configurez un canal Mattermost (url plus un secret bot_token, voir Authentification) via l’une des interfaces ci-dessous. Cela seul vous offre :

1. Détection automatique de chaque canal que le bot peut lire dans toutes les équipes dont il fait partie.
2. Canaux DM et DM de groupe découverts automatiquement et interrogés en même temps que les canaux d’équipe.
3. Les nouveaux MP (créés après le démarrage du bot) sont récupérés lors de la prochaine actualisation de découverte, qui a lieu toutes les 60 secondes.
4. mention_only est contourné dans les canaux de messages privés et de groupes privés (afin que les conversations en tête-à-tête ne nécessitent pas de mentionner le bot avec @).

Pour restreindre le bot, affinez avec channel_ids, team_ids ou discover_dms.

Configuration

bot_token et password sont des secrets :

channels.mattermost.<alias>.bot_token est un secret. Stocké chiffré, jamais en clair dans config.toml. Définissez-le via l’une de ces méthodes, qui chiffrent à l’écriture :

zeroclaw config set channels.mattermost.<alias>.bot_token    # demande une saisie masquée, stocke de manière chiffrée

Référence des champs

zeroclaw config set channels.mattermost.<alias>.bot_token    # entrée masquée, stockée chiffrée

export ZEROCLAW_channels__mattermost__<alias>__bot_token=

zeroclaw config set channels.mattermost.<alias>.channel_ids <value>

export ZEROCLAW_channels__mattermost__<alias>__channel_ids=

zeroclaw config set channels.mattermost.<alias>.discover_dms <value>

export ZEROCLAW_channels__mattermost__<alias>__discover_dms=

zeroclaw config set channels.mattermost.<alias>.excluded_tools <value>

export ZEROCLAW_channels__mattermost__<alias>__excluded_tools=

zeroclaw config set channels.mattermost.<alias>.interrupt_on_new_message <value>

export ZEROCLAW_channels__mattermost__<alias>__interrupt_on_new_message=

zeroclaw config set channels.mattermost.<alias>.listen_mode <value>

export ZEROCLAW_channels__mattermost__<alias>__listen_mode=

zeroclaw config set channels.mattermost.<alias>.login_id <value>

export ZEROCLAW_channels__mattermost__<alias>__login_id=

zeroclaw config set channels.mattermost.<alias>.mention_only <value>

export ZEROCLAW_channels__mattermost__<alias>__mention_only=

zeroclaw config set channels.mattermost.<alias>.password    # entrée masquée, stockée chiffrée

export ZEROCLAW_channels__mattermost__<alias>__password=

zeroclaw config set channels.mattermost.<alias>.proxy_url <value>

export ZEROCLAW_channels__mattermost__<alias>__proxy_url=

zeroclaw config set channels.mattermost.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__mattermost__<alias>__reply_min_interval_secs=

zeroclaw config set channels.mattermost.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__mattermost__<alias>__reply_queue_depth_max=

zeroclaw config set channels.mattermost.<alias>.team_ids <value>

export ZEROCLAW_channels__mattermost__<alias>__team_ids=

zeroclaw config set channels.mattermost.<alias>.thread_replies <value>

export ZEROCLAW_channels__mattermost__<alias>__thread_replies=

zeroclaw config set channels.mattermost.<alias>.url <value>

export ZEROCLAW_channels__mattermost__<alias>__url=

Découverte de canaux

Il existe deux modes de portée.

1. Découverte automatique (lorsque channel_ids est vide ou défini sur ["*"]). Au démarrage, puis toutes les 60 secondes, le bot appelle GET /api/v4/users/me/channels, filtre le résultat selon team_ids (canaux publics/privés) et discover_dms (messages directs/messages directs de groupe), puis interroge chaque canal restant. Les nouveaux messages directs créés en cours d’exécution apparaissent lors de la prochaine actualisation.
2. Explicite (lorsque channel_ids est une liste non vide d’ID autres que *). Au démarrage, le bot appelle GET /api/v4/channels/{id} pour chaque entrée afin de connaître son type (afin de savoir lesquels sont des DM pour le contournement mention_only), puis interroge exactement ces canaux indéfiniment. Aucune redécouverte périodique.

Dans les deux modes, chaque canal possède son propre curseur since : le bot suit le create_at le plus élevé qu’il a traité par canal et le transmet sous la forme since=<ms> lors de l’appel GET /api/v4/channels/{id}/posts suivant. Les curseurs ne se mélangent pas entre les canaux, de sorte qu’un canal peu actif ne supprime pas les messages d’un canal très actif.

Mode WebSocket

Définissez listen_mode = "websocket" pour passer de l’interrogation REST à une connexion WebSocket persistante (wss://<server>/api/v4/websocket). Le mode WebSocket :

• Diffuse les nouvelles publications en quasi temps réel (sans délai d’interrogation de 3 secondes).
• Réduit la charge HTTP sur le serveur Mattermost (une connexion au lieu de N requêtes toutes les 3 s).
• Renvoie les sessions ayant échoué au superviseur de canal partagé, qui se reconnecte avec un backoff exponentiel borné en utilisant les valeurs reliability.channel_initial_backoff_secs et reliability.channel_max_backoff_secs configurées.
• Nécessite Mattermost v4.0+ (l’endpoint /api/v4/websocket).

La découverte de canaux, mention_only, thread_replies, la transcription audio et l’autorisation par groupe de pairs fonctionnent de manière identique dans les deux modes.

Compromis :

• Le mode WebSocket doit maintenir une connexion TCP+TLS persistante.
• Pendant une fenêtre de reconnexion, des messages publiés dans un canal peuvent être manqués car cet écouteur ne demande pas encore la reprise/relecture de connexion Mattermost. L’interrogation rattrape le retard via les curseurs since=.
• Le mode d’interrogation est plus résistant aux interruptions réseau transitoires, au prix d’un trafic HTTP constant.

Pour revenir en arrière, définissez listen_mode = "polling" (ou supprimez le champ ; le polling est la valeur par défaut).

Messages directs

Mattermost classe les canaux par type :

G et D sont traités de manière identique par ZeroClaw : aucun ne comporte de team_id, tous deux sont contrôlés par discover_dms, et tous deux contournent implicitement mention_only (une conversation privée n’a aucun bruit ambiant à filtrer).

L’autorisation des expéditeurs de DM passe toujours par le résolveur de groupe de pairs du canal, comme pour tout autre canal. discover_dms est un paramètre de réglage, pas une frontière de sécurité ; ce sont les groupes de pairs qui décident qui est autorisé à s’adresser à l’agent.

Exécution de threads

1. La publication entrante se trouve dans un fil de discussion existant (root_id est défini) → la réponse arrive toujours dans ce fil, quel que soit thread_replies.
2. Le post entrant est de premier niveau et thread_replies = true (par défaut) → la réponse ouvre un fil de discussion ancré sur le post entrant.
3. L’envoi entrant est de premier niveau et thread_replies = false → la réponse est publiée à la racine du canal.

Gestion du contexte

Lorsqu’une conversation Mattermost se déroule dans un fil de discussion, ce fil constitue sa propre conversation. ZeroClaw dérive une clé de session distincte par fil, de sorte que chaque fil possède une fenêtre de contexte et un historique indépendants : les messages d’un fil ne débordent jamais dans un autre, et l’agent ne voit pas les échanges antérieurs d’un fil voisin. Pour Mattermost, ce comportement est contrôlé par thread_replies : lorsqu’il est activé, les messages de premier niveau ouvrent un fil et chaque fil constitue une conversation distincte ; lorsqu’il est désactivé, les réponses sont publiées à la racine du canal et l’historique est indexé par expéditeur et par cible plutôt que par fil.

• L’isolation est l’objectif. Le contexte de chaque thread est autonome : il ne fuit pas en dehors du thread, et rien de l’extérieur du thread ne s’y infiltre. Les threads parallèles conservent des états conversationnels distincts, de sorte que des tâches sans rapport ne se contaminent jamais entre elles.
• Les threads longs font croître le contexte. Un thread accumule l’historique tant qu’il reste actif, donc un thread très long finit par remplir la fenêtre de contexte du modèle comme toute autre conversation longue. Démarrez un nouveau thread pour réinitialiser.
• Le travail en cours est limité à chaque fil de discussion. Un nouveau message dans un fil n’annule pas une réponse en cours dans un autre ; la tâche de chaque fil est indépendante.

Définissez le comportement du thread sur n’importe quelle surface :

zeroclaw config set channels.mattermost.<alias>.thread_replies true     # réponses en fil de discussion activées
zeroclaw config set channels.mattermost.<alias>.thread_replies false    # réponses à la racine du canal

Authentification

Deux chemins :

1. Jeton de bot (recommandé). Créez-le dans System Console → Integrations → Bot Accounts, copiez le jeton d’accès et stockez-le dans bot_token. Les jetons restent valides après les rotations de mot de passe et sont plus faciles à révoquer.
2. Flux de connexion. Définissez login_id (email ou nom d’utilisateur) et password. Le bot appelle POST /api/v4/users/login au démarrage et met en cache le jeton de session renvoyé en mémoire. Aucune persistance sur disque.

bot_token l’emporte lorsque les deux sont définis.

Messages vocaux

Lorsque [transcription] est configuré et qu’un post entrant contient une pièce jointe audio (type MIME audio/* ou extension ogg/mp3/m4a/wav/opus/flac) sans corps de texte, le fichier audio est téléchargé via GET /api/v4/files/{file_id} et acheminé vers le fournisseur de transcription configuré. La transcription est préfixée [Voice] et devient le contenu du message. Les pièces jointes dépassant 25 Mo ou la durée limite définie par transcription.max_duration_secs sont ignorées avec un avertissement WARN.

Configuration

1. Dans Mattermost : Console système → Intégrations → Comptes de bot → Ajouter un compte de bot. Définissez un nom d’utilisateur (par ex. zeroclaw), activez les portées souhaitées.
2. Copiez le jeton d’accès. Stockez-le dans votre backend de secrets ZeroClaw.
3. Invitez le bot dans les équipes où vous souhaitez qu’il soit actif. Pour la découverte automatique des MP, aucune invitation supplémentaire n’est nécessaire : tout utilisateur peut envoyer un MP au bot.
4. Créez le canal mattermost.<alias> en référençant le jeton via la passerelle, zerocode, ou zeroclaw config set.
5. Liez le canal à un agent dans [agents.<alias>] via channels = ["mattermost.<alias>"].

Notes opérationnelles

1. La fréquence d’interrogation est de 3 secondes par canal. N canaux découverts = N appels HTTP toutes les 3 secondes vers le serveur Mattermost. Les configurations auto-hébergées par défaut gèrent cela facilement ; si vous êtes sur un tenant cloud partagé avec des limites de débit strictes, envisagez de restreindre la portée avec channel_ids ou team_ids.
2. L’identité du bot est récupérée une fois via GET /api/v4/users/me et mise en cache pour toute la durée de vie du processus. Les changements de nom d’utilisateur nécessitent un redémarrage.
3. Le jeton de session du flux de connexion par mot de passe est conservé uniquement en mémoire. Un redémarrage relance la connexion.

Voir aussi

• Vue d’ensemble des canaux
• Groupes de pairs
• Référence : schéma de configuration