El adapter contract de los conectores: canales y límites

Los canales donde ya están sus clientes

Un workspace AI resulta más útil donde la conversación ocurre de todos modos. Para muchas organizaciones ese lugar no es la interfaz web que ustedes despliegan; son los canales de mensajería que la gente abre sin pensarlo - los grupos de WhatsApp, los chats de Telegram, los servidores de Discord, los espacios de Slack. Simmetric Chat trata esos canales como superficies de primera clase de la misma base de conocimiento: un conector vincula un canal a un workspace y a un archivo documental, y cada pregunta que llega por ese canal la responde la misma pipeline de retrieval del chat interno.

La palabra del título - adapter contract - nombra la regla de diseño que lo vuelve seguro. Cada plataforma habla un protocolo distinto con semánticas de credenciales distintas, así que cada una corre detrás de un adapter dedicado; todo lo que el adapter comparte es un vocabulario fijo de campos y límites. El resultado se lee como una política de seguridad: un conector por canal, un binding por conector, un corpus por binding.

Este artículo recorre el contract desde el lado del operador: qué se configura al crear un conector, qué superficies cambian en la era v0.28 (el brazo de edición), cómo los límites protegen el workspace del tráfico externo y qué pasa cuando el corpus no tiene respuesta citable.

Solo edición Enterprise: connectors_enabled es false en la licencia Community, la registry de adapters está vacía ahí y el panel admin muestra el aviso de upgrade en lugar del formulario. El dato: FACT-CENSUS.md F-CONN-1.

Qué se configura al crear

El formulario de creación vive en Settings → Conversations → Connectors y pide dos clases de campos. Los campos de binding nombran la integración: un name que identifica la instancia, la platform (una entre telegram, discord, slack, whatsapp), el token secreto del canal y el workspace que atiende. Los campos de comportamiento dan forma a la conversación: el binding del archivo documental que determina el corpus, el mensaje de bienvenida para quien abre la conversación, el mensaje de fallback con su fallbackLocale cuando la búsqueda no produce fuentes citables, y los dos límites - rate limit y sesiones diarias, donde 0 significa ilimitado.

Tres de esos campos son inmutables tras la creación, y esa inmutabilidad no es un detalle de implementación - es el modelo de confianza. La plataforma y el token secreto definen quién puede hablar con el corpus; el workspace define qué puede alcanzar. Si cualquiera cambia, la identidad de la integración cambia, y el contract responde con un conector nuevo en vez de una mutación. El esquema de la serie v0.28 lleva esas reglas al pie de la letra: los mensajes de bienvenida y fallback se topean en 4000 caracteres, la plataforma y el token son create-only, y la PUT jamás los toca.

Las credenciales quedan del lado del servidor por diseño. La app llama a las APIs del canal con las credenciales que el administrador ingresó; el token secreto no vuelve a aparecer en la interfaz después de la creación, y el routing del conector vive en su propia infraestructura - el canal habla con su servidor, su servidor habla con su propia base de conocimiento.

La capa de adapters

Cada plataforma corre detrás de un adapter dedicado, y el registro de cada uno coincide con lo que la plataforma exige de verdad:

• Telegram - un bot token de @BotFather, con soporte de polling y de webhook (la tarjeta lleva los botones del modo).
• Discord - un bot token del Developer Portal más los intents de mensaje; el adapter lee los canales donde el bot está autorizado.
• Slack - un bot token y el signing secret de la app de Slack; los eventos de mensaje llegan por el webhook configurado.
• WhatsApp - el token secreto de la Business API del proveedor; el adapter llama a la API del proveedor.

La capa de adapters es donde mueren las diferencias entre plataformas. Verificación del webhook, alcance de los intents, bucles de polling, normalización del formato de mensajes - todo vive detrás del adapter de su plataforma, y el resto del producto ve una sola forma de registro de conector. La registry de adapters está gated: en Community está vacía por construcción, así que una instancia Community falla cerrada antes de que un tráfico externo alcance el workspace.

Edición: la superficie mutable de v0.28.1

Antes de v0.28.1, ajustar un conector significaba borrarlo y volver a crearlo. Los cambios de la serie v0.28 agregan un brazo de edición: el menú de la tarjeta lleva la entrada Edit que abre un diálogo pre-cargado sobre exactamente la superficie mutable - vía PUT /api/connectors/:id:

• Mutable - el nombre, el binding del archivo, los mensajes de bienvenida y fallback, el fallback locale y los dos límites (vacío = null; 0 = ilimitado).
• Inmutable - la plataforma, el bot token, el workspace.

El interruptor isEnabled sigue en la tarjeta (suspende el routing sin borrar la configuración), y la mutación queda auditada como toda acción admin: el endpoint registra el evento chat_connector.updated, en paridad con el brazo DELETE y su chat_connector.deleted. El brazo de edición importa para la historia del operador por una razón concreta: enlazar el canal a un archivo reconstruido, o apretar un límite tras un incidente, ya no cuesta la identidad del conector.

El camino de la respuesta y el fallback

Cada pregunta que llega de un canal atraviesa la misma pipeline de un chat interno: búsqueda híbrida sobre el archivo enlazado, citación de fuentes, síntesis - y la respuesta citada regresa por el canal de origen. El binding del archivo es el núcleo silencioso del contract: lo que hace fundada a una conversación externa.

Cuando la búsqueda no produce elementos citables válidos, la respuesta del contract es el mensaje de fallback - una respuesta configurada en la fallbackLocale configurada. Un canal externo nunca recibe una generación sin fundamento cuando el fallback está en pie; el visitante lee el fallback en vez de una afirmación segura sin nada detrás.

Los límites como esclusa del workspace

El rate limit y el daily session limit son la protección del contract contra el tráfico externo:

• 0 = ilimitado (el valor centinela del router).
• N = el máximo por conector para las solicitudes, y para las sesiones por día.

Junto con isEnabled, dejan exponer la base de conocimiento a un canal público manteniendo el radio de acción acotado: un bot desbocado, un canal scrapeado o una audiencia inesperada consuma a lo sumo la parte configurada del workspace. Desactivar, apretar o reenlazar - cada uno es ahora una edición única (el brazo v0.28.1), sin recreación.

Para seguir

La guía lleva el procedimiento completo del operador - el formulario campo por campo, la tabla de adapters por plataforma, el comportamiento de audit - en /es/docs/connectors:

• Conectores - la guía
• Datos de este post: filas FACT-CENSUS.md F-CONN-1 (la barrera de edición), F-CONN-2 (el brazo de edición v0.28.1), F-LIC-1 (la activación pegando la clave - sin tocar el servidor)

Provenance: paquetes Simmetric Chat connector.schema.ts (formas de campos + límites), routes/connectors.ts (el router + el limiter), CHANGELOG.md v0.28.1, license.ts (connectors_enabled) en el estado documental fijado por el census v0.28.1 (SHA aca5b8ff).