Nextcloud Talk

Intégration de Nextcloud Talk via le protocole de webhook Talk Bot. Auto-hébergé, fédéré et compatible E2E : une autre option de communication souveraine aux côtés de Matrix et Mattermost.

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 nextcloud définit channel à nextcloud, liste les expéditeurs autorisés dans external_peers (pour nextcloud, l’ID d’acteur Nextcloud ; ["*"] accepte tout le monde), nomme éventuellement des agents pairs pour la distribution inter-agents, une liste de blocage ignore, et un output_modality (mirror, voice ou text). Consultez Peer Groups pour la référence des champs.

Où définir ce paramètre :

Ce que fait cette intégration

• Reçoit les événements Talk entrants via POST /nextcloud-talk/<alias> sur la passerelle (/nextcloud-talk seul fonctionne toujours comme solution de repli dépréciée)
• Requiert et vérifie les signatures de webhook (HMAC-SHA256) avec le secret du bot installé
• Envoie des réponses dans les salons Talk via l’API signée Nextcloud Talk Bot

Prérequis

• Serveur Nextcloud 27.1 ou version ultérieure avec Talk 17.1 ou version ultérieure. Il s’agit d’un minimum strict, pas d’une recommandation : l’API signée Talk Bot que cette intégration utilise pour envoyer des réponses a été introduite dans Talk 17.1, et occ talk:bot:install ci-dessous n’est pas disponible dans les versions antérieures.

• Bot installé avec les fonctionnalités webhook et response, qui permettent à Nextcloud de transmettre les messages de la salle à ZeroClaw et à ZeroClaw d’envoyer des réponses :

  sudo -u www-data php occ talk:bot:install \
    -f webhook -f response \
    zeroclaw-bot '<shared-secret>' \
    'https://<your-public-url>/nextcloud-talk/<alias>'
  

• Secret du bot de cette installation. Nextcloud émet un secret partagé par bot, utilisé à la fois pour vérifier les signatures des webhooks entrants et pour signer les réponses sortantes de l’API du bot. Définissez-le avec webhook_secret, qui est le nom canonique. bot_token est un alias obsolète pour la même valeur : si les deux sont définis, ils doivent être identiques. Il ne peut pas contenir un secret sortant différent. Les valeurs non vides en conflit ne sont pas résolues silencieusement en faveur de l’une d’elles ; le conflit est consigné et l’alias ne se résout vers aucun secret, si bien que le canal se comporte alors exactement comme s’il n’était pas configuré : 401 en entrée, aucun envoi sortant.

• Passerelle accessible publiquement : voir Configuration → Conteneur pour les options de tunnel en cas d’auto-hébergement

Les deux sens échouent en mode fermé en cas de secret manquant, et il n’existe aucun mode non authentifié :

• Entrant : la vérification de signature est obligatoire. Sans secret résolu, le point de terminaison webhook renvoie 401 et n’atteint jamais l’agent. Il n’existe pas de mode « public » acceptant les webhooks non vérifiés.
• Sortant : aucune requête n’est envoyée, de sorte qu’une mauvaise configuration ne transmet jamais sur le réseau une requête non signée ou incorrectement signée.

La mise à niveau est une modification non rétrocompatible. Un déploiement qui fonctionnait auparavant sans secret acceptait les webhooks ; il les rejette désormais tous avec 401. Installez le bot avec occ talk:bot:install, puis définissez ce secret comme valeur de webhook_secret avant la mise à niveau, sinon les messages entrants cesseront d’être traités.

Configuration

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

export ZEROCLAW_channels__nextcloud_talk__<alias>__app_token=

zeroclaw config set channels.nextcloud_talk.<alias>.base_url <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__base_url=

zeroclaw config set channels.nextcloud_talk.<alias>.bot_name <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__bot_name=

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

export ZEROCLAW_channels__nextcloud_talk__<alias>__bot_token=

zeroclaw config set channels.nextcloud_talk.<alias>.draft_update_interval_ms <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__draft_update_interval_ms=

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

export ZEROCLAW_channels__nextcloud_talk__<alias>__excluded_tools=

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

export ZEROCLAW_channels__nextcloud_talk__<alias>__proxy_url=

zeroclaw config set channels.nextcloud_talk.<alias>.stream_mode <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__stream_mode=

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

export ZEROCLAW_channels__nextcloud_talk__<alias>__webhook_secret=

Le canal est lu depuis l’alias default. Définissez-le via n’importe quelle surface de configuration :

webhook_secret peut également être fourni à l’exécution via la surcharge d’environnement générique ZEROCLAW_channels__nextcloud_talk__default__webhook_secret, utile pour le renouveler sans modifier la configuration.

app_token est déprécié et inutilisé (les réponses ne passent plus par l’authentification OCS bearer) ; il est uniquement encore accepté pour que les anciennes configurations qui le définissent ne provoquent pas d’erreur d’analyse.

Point de terminaison de passerelle

zeroclaw daemon

Configurez l’URL du webhook de votre bot Talk pour qu’elle pointe vers l’alias de l’instance [channels.nextcloud_talk.<alias>] qui doit le recevoir :

https://<your-public-url>/nextcloud-talk/<alias>

Par exemple, [channels.nextcloud_talk.work] reçoit POST /nextcloud-talk/work. Ce routage par alias (#6312) vous permet d’exécuter plusieurs bots Talk côte à côte et de transmettre les webhooks de chacun à la bonne instance.

Le chemin simple https://<your-public-url>/nextcloud-talk fonctionne toujours mais est déprécié : il pointe vers le premier alias dans l’ordre lexicographique (déterministe entre les redémarrages) et renvoie un en-tête de réponse X-Zeroclaw-Deprecation. Les déploiements à instance unique peuvent continuer à l’utiliser sans modification. Un alias inconnu renvoie 404.

Développement local ? Configurez [tunnel] dans votre configuration (ngrok, Cloudflare ou Tailscale) et la passerelle s’expose automatiquement au démarrage : voir Operations → Network deployment.

Vérification de la signature

Les requêtes entrantes doivent comporter :

• En-tête X-Nextcloud-Talk-Random
• En-tête X-Nextcloud-Talk-Signature

ZeroClaw vérifie :

expected_sig = hex(hmac_sha256(secret, random + raw_request_body))
if X-Nextcloud-Talk-Signature != expected_sig:
    return 401

Sans secret résolu, ZeroClaw renvoie 401 avant d’analyser ou de distribuer le webhook. Il n’existe aucun mode qui accepte une requête non vérifiée.

Routage des messages

• Les événements provenant de bots (actorType = "bots") sont ignorés : évite les boucles de rétroaction
• Les événements système (entrées, sorties, modifications d’appartenance) sont ignorés
• Les événements non liés à un message sont ignorés
• Les messages utilisateur sont envoyés à la boucle de l’agent.
• Les réponses sont renvoyées à la salle d’origine via le token présent dans la charge utile du webhook.

Validation rapide

1. Définissez external_peers = ["*"] dans le groupe de pairs pour les premiers tests
2. Envoyer un message de test dans la salle Talk configurée
3. Confirmez que ZeroClaw reçoit et répond dans la même salle.
4. Restreindre le groupe de pairs à des identifiants d’acteurs explicites (par ex. ["alice", "bob"])

Dépannage

• 404 Nextcloud Talk not configured : section [channels.nextcloud_talk.default] manquante ou enabled = false
• 401 Invalid signature : secret non concordant, en-tête aléatoire incorrect, ou bug de signature du corps. Vérifiez que c’est bien le corps brut qui est signé (et non le JSON analysé)
• Aucune réponse, webhook 200 : l’événement a été filtré. Vérifiez les journaux pour “actorType = bots” ou un expéditeur absent de l’ensemble de pairs
• Réponses livrées mais semblant incorrectes : vérifiez le contexte du fil de discussion ; les réponses Talk sont actuellement limitées au niveau racine

Diffusion en continu

Nextcloud Talk ne prend pas en charge les modifications de messages via l’API Bot, donc les mises à jour de brouillons en continu sont désactivées pour ce canal. Les réponses sont envoyées uniquement à la fin du flux.

Notes d’auto-hébergement

• TLS : terminaison au niveau de votre proxy inverse ; la vérification de la signature du webhook fonctionne sur la boucle de bouclage HTTP-vers-conteneur
• Les réponses sortantes s’authentifient via la signature HMAC de la Bot API (webhook_secret/bot_token), et non via un jeton porteur ; il n’existe pas d’informations d’authentification OCS distinctes à gérer
• Les limites de taux dépendent du serveur Nextcloud ; le bot par défaut ne les atteint pas dans des cadences de conversation normales.
• Proxy par canal : définissez proxy_url pour remplacer le paramètre global [proxy] uniquement pour Nextcloud Talk (http://, https://, socks5://, socks5h://)

Voir aussi

• Matrix : E2EE plus riche mais complexité opérationnelle accrue
• Mattermost : posture auto-hébergée similaire, protocole différent
• Chaînes → Vue d’ensemble