Conectar un canal con un agente de Cortex

En dos pasos por la UI, haz que los mensajes de un canal los atienda un agente de Cortex y que sus respuestas vuelvan al usuario.

Un canal de Channels recibe los mensajes de tus usuarios; un agente de Cortex los responde con IA. Conectarlos es un flujo de dos pasos por la interfaz, sin API keys ni código: generas una conexión en Cortex (que te da una URL y un secreto) y la pegas en tu canal.

Qué necesitas

Un canal ya creado en Channels (WhatsApp, Telegram o API).
Un agente ya creado en Cortex.

1. Crea la conexión en Cortex

En el portal de Cortex, ve a Conexiones → Nueva conexión. Ponle un nombre (p. ej. «WhatsApp ventas») y elige el agente por defecto que atenderá los mensajes de este canal.

Al crearla, Cortex te muestra una sola vez dos valores:

Valor	Qué es
URL del handler	El endpoint de ingesta de esta conexión, único por conexión.
Secret del handler	El secreto compartido con el que se firma cada mensaje.

El secreto no se vuelve a mostrar

Cópialos ahora. El secreto se guarda cifrado y no vuelve a mostrarse. Si lo pierdes, usa Rotar secreto en el detalle de la conexión para generar uno nuevo (el anterior deja de funcionar al instante).

2. Pega la URL y el secreto en el canal

En el portal de Channels, abre el canal y busca la tarjeta «Enrutamiento entrante → handler»:

Pega la URL del handler en el campo URL del handler.
Pega el Secret del handler en el campo Secret del handler.
Activa el switch «Enviar mensajes entrantes al handler» y guarda.

Desde ese momento, cada mensaje que entre al canal se firma y se envía a tu conexión de Cortex.

3. Pruébalo

Escríbele al canal (al número de WhatsApp, al bot de Telegram, o por la API del canal). Si todo está bien:

Channels normaliza el mensaje y lo firma con el secreto de la conexión.
Cortex verifica la firma, resuelve el agente y crea una sesión.
El agente razona y, si responde, la respuesta vuelve al usuario por el mismo canal.

¿Qué agente atiende?

Por defecto, el agente de la conexión. Si defines reglas de enrutamiento en Cortex (por inbox, tipo de canal, etc.), esas mandan y el agente por defecto queda como respaldo para lo que ninguna regla cubra.

Cómo funciona por dentro

Channels y Cortex son dos servicios independientes que se comunican solo por API — no comparten base de datos. La conexión establece un canal seguro en cada sentido:

Usuario ─▶ Proveedor ─▶ Channels
                          │  firma HMAC (x-channels-signature)
                          ▼
              POST {URL de la conexión}   ◀── entrante, autenticado por firma
                          │  Cortex verifica la firma con el secreto de la conexión
                          │  el tenant y el agente salen de la conexión (no del mensaje)
                          ▼
                   Agente (razona, usa tools)
                          │  cuando produce respuesta
                          ▼
              POST /v1/messages ─▶ Channels ─▶ Proveedor ─▶ Usuario   ◀── saliente

Entrante (Channels → Cortex): cada webhook va firmado con HMAC-SHA256 usando el secreto de la conexión, con protección anti-replay. Cortex autentica por la firma, no por API key. El tenant y el agente por defecto salen de la conexión: un mensaje no puede suplantar a otra organización.
Saliente (Cortex → Channels): la respuesta no es inmediata ni viaja en la respuesta del webhook (el agente puede tardar, encadenar herramientas o esperar una aprobación). Cuando el agente termina, Cortex hace una llamada aparte a la API de envío de Channels (POST /v1/messages), que entrega el mensaje por el canal original.

Para operadores: habilitar el camino de respuesta

El envío de respuestas requiere que el despliegue de Cortex tenga configuradas CHANNELS_API_URL y CHANNELS_API_KEY (una API key de Channels con scope messages:send). Es un paso de configuración una sola vez por entorno, no por conexión. Sin ellas, el agente razona pero la respuesta no se entrega.

Solución de problemas

Síntoma	Causa probable
El mensaje no llega a Cortex	El switch del handler está apagado, o la URL no es la de la conexión.
Cortex responde 404	La conexión fue eliminada o está deshabilitada, o el secreto pegado en Channels no coincide — rótalo y vuelve a pegarlo. (Todo fallo de autenticación responde el mismo 404; el motivo exacto queda en el log de Cortex.)
El agente procesa pero el usuario no recibe respuesta	Falta `CHANNELS_API_URL`/`CHANNELS_API_KEY` en el despliegue de Cortex.
No pasa nada y no hay error	Ninguna regla de enrutamiento coincide y la conexión no tiene agente por defecto.