Nextcloud Talk

Integración de Nextcloud Talk a través del protocolo de webhooks de Talk Bot. Autoalojado, federado y con capacidad E2E: otra opción de comunicación soberana junto a Matrix y Mattermost.

Quién puede hablar con el agente

Los remitentes entrantes se filtran contra el conjunto de pares resuelto para el agente vinculado, obtenido de la configuración peer_groups a la que pertenece el agente. La coincidencia elimina el @ inicial y no distingue mayúsculas de minúsculas frente al identificador nativo de remitente del canal. Un conjunto vacío deniega a todos; un conjunto que contiene "*" acepta a cualquiera; en caso contrario, solo se aceptan los pares externos listados (y los agentes pares). Esto es independiente del emparejamiento de la puerta de enlace (gateway.require_pairing), que autentica clientes HTTP/WebSocket, no remitentes de canales de chat.

Un grupo de pares para nextcloud establece channel en nextcloud, enumera los remitentes permitidos en external_peers (para nextcloud, el ID de actor de Nextcloud; ["*"] acepta a cualquiera), opcionalmente nombra agents pares para el despacho entre agentes, una lista de bloqueo ignore y un output_modality (mirror, voice o text). Consulta Peer Groups para la referencia de campos.

Dónde configurar esto:

Qué hace esta integración

• Recibe eventos entrantes de Talk a través de POST /nextcloud-talk/<alias> en la pasarela (/nextcloud-talk sin parámetros aún funciona como alternativa obsoleta)
• Requiere y verifica las firmas de webhook (HMAC-SHA256) con el secreto del bot instalado
• Envía respuestas a las salas de Talk mediante la API firmada de Nextcloud Talk Bot

Requisitos previos

• Servidor Nextcloud 27.1 o posterior con Talk 17.1 o posterior. Este es un mínimo estricto, no una recomendación: la API de Talk Bot firmada que esta integración utiliza para enviar respuestas se introdujo en Talk 17.1, y occ talk:bot:install a continuación no está disponible en versiones anteriores.

• Bot instalado con las funciones webhook y response, que permiten que Nextcloud envíe mensajes de sala a ZeroClaw y que ZeroClaw envíe respuestas:

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

• Secreto del bot de esa instalación. Nextcloud emite un secreto compartido por bot, que se utiliza tanto para verificar las firmas de los webhooks entrantes como para firmar las respuestas salientes de la API del bot. Establézcalo como webhook_secret, que es el nombre canónico. bot_token es un alias obsoleto para el mismo valor: si ambos están definidos, deben ser idénticos. No puede contener un secreto saliente diferente. Los valores no vacíos en conflicto no se resuelven silenciosamente a favor de uno de ellos; el conflicto se registra y el alias se resuelve sin ningún secreto, por lo que el canal se comporta exactamente como si no estuviera configurado: 401 entrante, sin envíos salientes.

• Gateway accesible públicamente: consulta Configuración → Contenedor para conocer las opciones de túnel si es autoalojado

Ambas direcciones fallan de forma cerrada ante un secreto faltante, y no hay modo no autenticado:

• Entrante: la verificación de la firma es obligatoria. Si no hay un secreto resuelto, el endpoint de webhook devuelve 401 y nunca llega al agente. No hay modo “público” que acepte webhooks no verificados.
• Salida: no se envía ninguna solicitud en absoluto, por lo que una configuración incorrecta nunca coloca una solicitud sin firmar o firmada incorrectamente en la red.

La actualización es un cambio incompatible. Un despliegue que anteriormente se ejecutaba sin un secreto aceptaba webhooks; ahora rechaza cada uno de ellos con 401. Instala el bot con occ talk:bot:install y, a continuación, establece ese secreto como webhook_secret antes de actualizar, o los mensajes entrantes dejarán de procesarse.

Configuración

zeroclaw config set channels.nextcloud_talk.<alias>.app_token    # entrada enmascarada, almacenada cifrada

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    # entrada enmascarada, almacenada cifrada

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    # entrada enmascarada, almacenada cifrada

export ZEROCLAW_channels__nextcloud_talk__<alias>__webhook_secret=

El canal se lee desde el alias default. Configúrelo a través de cualquier superficie de configuración:

webhook_secret también puede proporcionarse en tiempo de ejecución mediante la sustitución genérica de variables de entorno ZEROCLAW_channels__nextcloud_talk__default__webhook_secret, útil para rotarlo sin editar la configuración.

app_token está obsoleto y no se utiliza (las respuestas ya no pasan por autenticación OCS bearer); solo se sigue aceptando para que las configuraciones antiguas que lo definen no fallen al analizarse.

Punto de conexión de puerta de enlace

zeroclaw daemon

Configura la URL del webhook de tu bot de Talk para que apunte al alias de la instancia [channels.nextcloud_talk.<alias>] que debe recibirlo:

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

Por ejemplo, [channels.nextcloud_talk.work] recibe POST /nextcloud-talk/work. Este enrutamiento por alias (#6312) te permite ejecutar varios bots de Talk en paralelo y entregar los webhooks de cada uno a la instancia correcta.

La ruta simple https://<your-public-url>/nextcloud-talk aún funciona, pero está obsoleta: se resuelve al primer alias en orden lexicográfico (determinista entre reinicios) y devuelve un encabezado de respuesta X-Zeroclaw-Deprecation. Las implementaciones de instancia única pueden seguir usándola sin cambios. Un alias desconocido devuelve 404.

¿Desarrollo local? Configura [tunnel] en tu configuración (ngrok, Cloudflare o Tailscale) y el gateway se expone automáticamente al iniciarse: consulta Operations → Network deployment.

Verificación de firma

Las solicitudes entrantes deben incluir:

• X-Nextcloud-Talk-Random cabecera
• X-Nextcloud-Talk-Signature cabecera

ZeroClaw verifica:

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

Sin un secreto resuelto, ZeroClaw devuelve 401 antes de analizar o despachar el webhook. No existe ningún modo que acepte una solicitud no verificada.

Enrutamiento de mensajes

• Los eventos originados por bots (actorType = "bots") se ignoran: evita bucles de retroalimentación
• Eventos del sistema (uniones, salidas, cambios de membresía) se ignoran
• Los eventos no relacionados con mensajes se ignoran
• Los mensajes de usuario se envían al bucle del agente
• Las respuestas se envían de vuelta a la sala de origen a través del token en la carga útil del webhook.

Validación rápida

1. Establece external_peers = ["*"] en el grupo de pares para las pruebas iniciales
2. Enviar un mensaje de prueba en la sala de Talk configurada
3. Confirmar que ZeroClaw recibe y responde en la misma sala
4. Restringe el grupo de pares a IDs de actor explícitos (p. ej. ["alice", "bob"])

Solución de problemas

• 404 Nextcloud Talk not configured: falta la sección [channels.nextcloud_talk.default] o enabled = false
• 401 Invalid signature: discrepancia en el secreto, encabezado aleatorio incorrecto o error al firmar el cuerpo. Verifique que se esté firmando el cuerpo sin procesar (no el JSON analizado)
• Sin respuesta, webhook 200: el evento fue filtrado. Revisa los registros en busca de “actorType = bots” o un remitente que no esté en el conjunto de pares
• Las respuestas se entregan pero se ven mal: verifica el contexto del hilo; las respuestas de Talk actualmente son solo de nivel raíz

Transmisión

Nextcloud Talk no admite la edición de mensajes a través de la API de Bot, por lo que las actualizaciones de borradores en tiempo real están desactivadas para este canal. Las respuestas se envían únicamente al finalizar el flujo.

Notas de autoalojamiento

• TLS: finaliza en tu proxy inverso; la verificación de la firma del webhook funciona a través del bucle de bucleback HTTP al contenedor
• Las respuestas salientes se autentican mediante la firma HMAC de la Bot API (webhook_secret/bot_token), no un token de portador; no hay una credencial de portador OCS independiente que gestionar
• Los límites de tasa dependen de Nextcloud-server; el bot predeterminado no los alcanza en cadencias de conversación normales.
• Proxy por canal: establece proxy_url para anular la configuración global de [proxy] solo para Nextcloud Talk (http://, https://, socks5://, socks5h://)

Ver también

• Matrix: E2EE más completo pero mayor complejidad operativa
• Mattermost: postura autoalojada similar, protocolo diferente
• Canal → Descripción general