Nexus de Integración: Cuando el mundo llama a Cotalker (A y B)

En la entrada anterior abrimos el grimorio y revelamos el secreto mejor guardado de los bots: cada uno de ellos es, por definición, un endpoint HTTP listo para ser invocado desde el exterior. Ahora que sabes eso, la pregunta natural es: ¿cómo lo uso en la práctica?

La respuesta corta: depende. La respuesta larga es este artículo.

Crea endpoints en Cotalker usando bots

Cada bot de Cotalker genera un endpoint invocable desde cualquier sistema externo. Aprende a usarlos como puerta de entrada para integraciones.

Esteban Tejeda DevEsteban Tejeda

Hoy veremos las dos primeras conexiones del mapa de Nexus de Integración: la Conexión A, donde un sistema externo llama directamente al bot, y la Conexión B, donde una integración intermedia se encarga del trabajo pesado antes de tocar Cotalker. A primera vista parecen lo mismo, pero la diferencia entre ambas es la diferencia entre dejar la puerta de tu casa abierta y poner un guardia en la entrada.

Capítulo 1: Cómo funciona la cola del bot

Antes de hablar de conexiones, necesitamos entender un detalle técnico que cambia todo: cuando llamas al endpoint de un bot, la rutina no se ejecuta inmediatamente.

Cotalker recibe la petición, la encola en su worker interno, y te responde con un mensaje confirmando que la solicitud fue recibida. Eso es todo. No te devuelve el resultado de la rutina, no te dice si las etapas se ejecutaron correctamente, no te notifica si algo falló. Solo te dice: "Recibido, lo puse en la cola".

En la mayoría de los casos, la cola se procesa en segundos y la rutina se ejecuta casi al instante. Pero cuando hay muchas llamadas simultáneas, la cola se acumula y la ejecución puede demorarse. Si necesitas confirmar que la rutina se ejecutó correctamente, tienes que revisar los logs de automatización dentro de Cotalker.

Esto tiene implicaciones directas:

• No puedes usar el bot como una API síncrona. Si tu sistema externo necesita una respuesta inmediata con datos procesados, el bot no es el mecanismo adecuado para eso (ahí necesitas una integración que haga el trabajo y responda directamente, pero eso lo veremos en la Conexión C).
• No hay garantía de orden. Si envías diez llamadas simultáneas, no puedes asumir que se procesarán en el orden en que las enviaste.
• Sí hay garantía de ejecución. La cola es persistente. Si Cotalker recibe la petición, la rutina se va a ejecutar eventualmente.

Con esto claro, veamos las conexiones.

Capítulo 2: Conexión A - Externo llama al bot directamente

La conexión más simple que existe. Un sistema externo hace un POST al endpoint del bot, el bot encola la rutina y la ejecuta.

Cómo funciona

1. El sistema externo construye la URL del bot:
   POST https://<BASE_URL>/api/v1/bots/run/<BOT_ID>
2. Incluye el header de autenticación: Authorization: Bearer <API_TOKEN>
3. Envía un JSON con la data que la rutina necesita.
4. Cotalker responde confirmando que la solicitud fue encolada.
5. La rutina del bot se ejecuta en segundo plano.

Ejemplo de caso

Un webhook de un sistema externo (por ejemplo SAP) que al recibir una respuesta, notifica a Cotalker para cambiar el estado de una tarea automáticamente. El formulario externo no necesita una respuesta con datos, solo necesita que Cotalker ejecute algo.

Por qué existe pero casi no se usa en producción

La Conexión A es perfecta como ejercicio didáctico. Es la forma más rápida de demostrar que el bot funciona como endpoint. Pero en la práctica tiene limitaciones serias que la hacen inadecuada para la mayoría de escenarios reales:

Sin validación de entrada. Como vimos en el post anterior, Cotalker acepta cualquier body sin quejarse. Si el sistema externo envía un campo mal nombrado, con un tipo incorrecto o con datos faltantes, la rutina fallará en silencio. No hay schema validation, no hay error handling estructurado, no hay nada que te proteja de un payload mal formado.

Hasta ahora, la única opción para ejecutar lógica dentro de la rutina era CCJS (Custom Code JavaScript), que es código vanilla de JavaScript sin acceso a librerías externas. Recientemente apareció ESM Code, una nueva etapa que sí permite importar librerías como Zod. En teoría, esto abriría la puerta a validar el body directamente dentro de la rutina, pero al momento de escribir este artículo aún no ha sido probado en producción para este caso de uso.

Sin rate limiting. Cualquier sistema que conozca la URL del bot puede hacer tantas llamadas como quiera. Y cada una de esas llamadas se encola en el worker de Cotalker. Si un sistema externo enloquece y dispara cientos de requests por minuto, vas a sobrecargar la cola del worker. Me pasó una vez: el worker se saturó y las rutinas de otros flujos que no tenían nada que ver empezaron a demorarse. No fue divertido para el equipo de ingeniería. Como curiosidad, gracias a este incidente salió un update para los bots.

Sin seguridad para lógica compleja. Si necesitas consultar otra API, cruzar datos con otra fuente o aplicar reglas de negocio complejas, se pueden lograr, pero estarías provocando una falla de seguridad (para esto requieres otro tipo de conexión que veremos más adelante).

El BOT_ID queda expuesto. El sistema externo conoce directamente el ID del bot. Si ese ID se filtra, cualquiera con un token válido puede invocar la rutina.

Cuándo sí tiene sentido

Dicho todo lo anterior, hay un escenario donde la Conexión A empieza a tener sentido real: Si tu caso de uso es simple (cambiar el estado de una tarea, actualizar un par de campos del asset, enviar una notificación), y una etapa de código (CCJS o ESM Code) valida el body antes de que la rutina continúe, entonces tienes un endpoint funcional sin necesidad de levantar infraestructura externa. Pero esto aplica solo para operaciones cortas y puntuales. Si la lógica crece, necesitas la Conexión B.

Capítulo 3: Conexión B - Externo llama a una integración que llama al bot

La Conexión B es la evolución natural de la A. Aquí agregamos una capa intermedia: una integración que recibe la data, la procesa y luego invoca al bot.

Cómo funciona

1. El sistema externo hace una request al endpoint de tu integración (un Lambda, Cloud Function, o lo que uses). A diferencia de la Conexión A donde siempre es un POST al bot, aquí el verbo HTTP lo defines tú: puede ser un POST para crear, un PUT para actualizar, un DELETE para desactivar, o el que tenga más sentido para tu caso. La integración es tu territorio.
2. La integración valida la data (schema validation con Zod, por ejemplo).
3. Si la validación falla, responde con un error estructurado al sistema externo. La rutina nunca se ejecuta.
4. Si la data es válida, la integración la transforma al formato que la rutina espera (mappers).
5. Opcionalmente, la integración consulta APIs externas para enriquecer la data.
6. La integración hace el POST al bot de Cotalker con la data ya procesada, incluyendo el Authorization: Bearer <API_TOKEN> en el header.
7. Cotalker encola la rutina y la ejecuta en segundo plano.

Por qué resuelve todo lo que la Conexión A no puede

Validación real. Tu integración valida el body con un schema estricto antes de que la data llegue a Cotalker. Si algo no cuadra, el request muere en la integración y el sistema externo recibe un error descriptivo. Cotalker ni se entera de que algo pasó.

Rate limiting. Puedes implementar rate limiting en tu integración para controlar cuántas llamadas por minuto acepta tu endpoint. Si el sistema externo se descontrola, tu integración lo frena antes de que el worker de Cotalker sufra las consecuencias.

Transformación y enriquecimiento. Si la data del sistema externo viene en XML, en un formato legacy, o simplemente con nombres de campos distintos a los que tu rutina espera, la integración se encarga de la conversión. También puede consultar otras APIs (obtener datos de un CRM, verificar existencia de un registro, calcular valores derivados) antes de enviar el payload final al bot.

Autenticación en capas. El sistema externo se autentica contra tu integración (con su propio mecanismo: API key, OAuth, JWT). La integración es la única que conoce el BOT_ID y el API_TOKEN de Cotalker. Si el endpoint de tu integración se filtra, el atacante aún necesitaría pasar tu validación y autenticación para llegar al bot. Y si tu integración se compromete, puedes rotar el token de Cotalker sin afectar al sistema externo.

Logging y observabilidad. Tu integración puede loggear cada request que recibe, cada transformación que aplica y cada llamada que hace al bot. Si algo falla, tienes trazabilidad completa sin depender de los logs de Cotalker.

Separación de responsabilidades. El desarrollador mantiene la integración (validación, transformación, rate limiting). El partner o admin mantiene la rutina del bot (lógica de negocio dentro de Cotalker). Cada quien en lo suyo.

Ejemplo de caso

Un ERP envía un payload con datos de una orden de compra cada vez que se aprueba una nueva orden. El payload viene con campos en español, fechas en formato DD/MM/YYYY, montos como strings y algunos campos opcionales que a veces vienen y a veces no.

Tu integración:

1. Valida que el body tenga los campos obligatorios y los tipos correctos.
2. Transforma las fechas a ISO 8601.
3. Convierte los montos de string a número.
4. Consulta la API del CRM para obtener el nombre del proveedor asociado.
5. Construye el payload limpio y se lo envía al bot.

La rutina del bot recibe un JSON impecable y solo se preocupa por crear la tarea en el flujo de aprobación, asignarla al usuario correcto y enviar la notificación. Sin transformaciones, sin validaciones conplejas, sin sorpresas.

Otro ejemplo: sincronización de inventario

Un sistema de bodega notifica cada vez que el stock de un producto baja de cierto umbral. Tu integración recibe la alerta, verifica contra la base de datos de proveedores cuál tiene mejor precio para ese producto, calcula la cantidad óptima de reposición según el historial de consumo, y envía al bot un payload con toda la información lista para que la rutina cree la orden de reposición automáticamente.

Otro ejemplo: onboarding de clientes

Un formulario web externo recoge los datos de un nuevo cliente. Tu integración valida el RUT (o el identificador fiscal que corresponda), verifica que no exista ya en el sistema, normaliza la dirección usando una API de geocodificación, y envía al bot la data limpia para que cree el registro en Cotalker y dispare el flujo de bienvenida.

Capítulo 4: Conexión A vs Conexión B

La regla práctica: si puedes explicar todo el flujo de datos en una oración sin usar la palabra "pero", probablemente la Conexión A es suficiente. Si necesitas un "pero" (la data viene en otro formato pero la rutina espera JSON, el sistema externo envía muchos requests pero no queremos saturar el worker), entonces necesitas la B.

Capítulo 5: Lo que ambas conexiones comparten

Más allá de sus diferencias, hay características que aplican tanto para la A como para la B y que conviene tener presentes:

La rutina siempre se encola. No importa si la llamada viene directo del sistema externo o pasa por una integración: cuando el bot recibe el POST, la rutina entra en la cola del worker. No hay forma de ejecutarla de manera síncrona ni de obtener el resultado de la ejecución en la misma respuesta HTTP.

No hay callback nativo. Cotalker no ofrece un mecanismo built-in para notificarte cuando la rutina terminó de ejecutarse. Si necesitas confirmación de ejecución, tienes dos opciones: revisar los logs de automatización manualmente, o diseñar la rutina para que ella misma notifique (por ejemplo, una etapa NWRequest al final que haga un POST de vuelta a tu integración confirmando el resultado). Este segundo enfoque es más robusto pero requiere trabajo adicional y lo recomendaría solo para notificaciones simples, más adelante veremos el por qué.

El orden no está garantizado. Si envías múltiples llamadas rápidamente, las rutinas se encolarán pero no necesariamente se ejecutarán en el orden en que llegaron. Si tu lógica depende del orden, vas a necesitar el caso C.

Capítulo 6: Cerrando el portal (por ahora)

La Conexión A es el primer hechizo que todo mago aprende: simple, directo, útil para entender cómo funciona la magia. Pero nadie la usaría para proteger un castillo.

La Conexión B es lo que realmente usamos en producción. Agrega validación, transformación, rate limiting y seguridad sin complicar la rutina del bot. El partner sigue manteniendo su lógica de negocio en Cotalker; el desarrollador se encarga de que la data llegue limpia y segura.

Lo que ambas tienen en común es que el flujo de datos siempre va en una dirección: desde el exterior hacia Cotalker. El mundo llama, Cotalker ejecuta. Simple.

Pero hay escenarios donde el flujo se invierte: Cotalker es quien necesita llamar al mundo exterior. Y ahí las reglas cambian completamente. En la próxima entrega de Nexus de Integración veremos las conexiones donde Cotalker inicia la conversación, incluyendo una que funciona perfectamente pero que nadie debería usar sin pensarlo dos veces.

Referencias:

Routine Stage Types | Cotalker Technical Documentation

Overview

Cotalker

Bots Section | Cotalker Technical Documentation

Cotalker has two different types of bots: predefined and customized. In this section, we deal with customized bots. For information on all the predefined bots available for use in routines, please consult the Routine Stage Types section.

Cotalker

Bots | Cotalker Technical Documentation

Overview

Cotalker