Nexus de Integración: El bot como puerta de entrada
Llega un momento en el que todo mago de Cotalker domina todos los secretos de los flujos, los formularios ya no intimidan, las etapas se encadenan casi de memoria y las rutinas se configuran en piloto automático. Hasta que surge la pregunta que cambia todo:
"¿Y cómo hago para que un sistema externo pueda comunicarse con Cotalker de forma simple?"
La búsqueda lleva inevitablemente a la sección de "Bots". La documentación dice que un bot es una automatización disparada por un slash command o un survey. Técnicamente correcto, pero es como decir que una varita es "un palo que lanza chispas": no te dice nada sobre los conjuros que puede invocar, ni por qué algunos hechiceros la usan para cosas que el fabricante jamás imaginó. La verdad es que el bot esconde un secreto que la mayoría de partners desconoce, y que incluso implementadores con años en la plataforma pasan por alto. Ese secreto es la base sobre la que se construyen al menos doce formas distintas de conectar Cotalker con el mundo exterior.
Esta es la primera entrada de Nexus de Integración, una serie nacida de la trinchera de las implementaciones. Hoy empezamos por lo fundamental: qué es realmente un bot, qué secreto esconde, y por qué entenderlo cambia completamente la forma en que piensas las integraciones en Cotalker.
Capítulo 1: Lo que todo el mundo sabe (o cree saber)
Vamos con lo básico para alinear conceptos.
A nivel técnico, un bot en Cotalker es un objeto que contiene dos cosas:
- Un trigger: la forma en que se activa (slash command o comando encuesta).
- Una rutina: la secuencia de etapas (stages) que se ejecutan una vez activado.
Cuando creas un bot (Panel de Administrador → Bots), defines su nombre, su code, su descripción y le configuras una rutina usando el Routine Builder. Hasta aquí, nada nuevo. Es lo que aparece en la documentación y lo que cualquier partner aprende en su primer mes.
La rutina del bot funciona exactamente igual que una rutina de trigger de formulario o rutina de startfom: puede contener etapas de todo tipo como enviar correos (PBEmail), enviar mensajes (PBMessage), hacer llamadas de red (NWRequest), ejecutar código JavaScript (CCJS), entre muchas otras cosas.
Pero si esto es todo lo que sabes sobre los bots, te falta la pieza más importante del rompecabezas.
Capítulo 2: El secreto que nadie te cuenta
Aquí es donde la historia se pone interesante.
Cada bot que creas en Cotalker genera automáticamente un endpoint HTTP si seleccionas la opción "Global" en Funciones. Sí, un endpoint real, accesible desde cualquier lugar del mundo vía POST. Esto no es una funcionalidad experimental, ni un hack, ni un workaround. Está ahí desde siempre, escondido a plena vista como un hechizo que nadie se molestó en enseñar.
El endpoint se construye así:
POST https://<BASE_URL>/api/v1/bots/run/<BOT_ID>
Y el body que recibe es un JSON que la rutina del bot podrá consumir:
{
"campo_1": "ejemplo_1",
"campo_2": "ejemplo_2"
}
Eso es todo. No hay configuración adicional, no hay panel oculto, no hay feature flag. Cada bot que creas es, por definición, un endpoint listo para ser invocado desde afuera.
Hace poco hablé con un colega que lleva muchos años trabajando con Cotalker. Cuando le conté esto, su reacción fue: "¿En serio? ¿Y eso dónde está documentado?". Está documentado, sí, pero enterrado entre ejemplos de slash commands y tutoriales de cómo enviar correos automáticos. Nadie te lo presenta como lo que realmente es: la puerta de entrada para que cualquier sistema externo ejecute lógica dentro de Cotalker.
Y este secreto, este pequeño conjuro escondido, es la piedra angular de todo lo que veremos en Nexus de Integración. Las doce conexiones que existen entre Cotalker y el mundo exterior (que cubriré en las próximas entregas) nacen, directa o indirectamente, de esta capacidad del bot de ser invocado como endpoint.
Capítulo 3: La autenticación del portal
Ahora que sabes que el bot es un endpoint, la siguiente pregunta es obvia: ¿quién puede llamarlo?
Cotalker añade seguridad a la invocación de los bots, y es que solo puede ser llamado con una API Token.
El API Token se genera desde el Panel de Administrador → API Tokens. Un consejo que no aparece en ningún grimorio oficial pero que vale su peso en oro: asígnale al token un access role con los permisos mínimos necesarios. No uses tokens con full admin para integraciones externas. Si un token se filtra y tiene permisos de administrador, vas a tener una conversación muy incómoda con el equipo de seguridad del cliente. Y créeme, no es una conversación que quieras tener.
Para obtener el BOT_ID que necesitas para construir la URL, simplemente basta con guardar el bot, y luego al abrirlo verás su BOT_ID dentro de su url. Algo como esto:
https://<BASE_URL>/admin/bots/edit/<BOT_ID>
Capítulo 4: Lo que entra y cómo se lee
Una vez que el sistema externo (o el mismo Cotalker, como veremos más adelante) hace el POST al endpoint del bot, la data queda disponible dentro de la rutina. La forma de acceder a ella es siempre con $VALUE.
Un ejemplo práctico. Supongamos que un sistema externo envía esto:
{
"orderId": "OC-2026-0451",
"amount": 15000,
"currency": "CLP",
"meta": {
"date": "2026-04-20T16:53:37.775Z",
"userId": "69cd4daf23f8df0fbeaf8332"
}
}
Para que tengas la referencia completa, así se ve la llamada al bot con todo junto: endpoint, autenticación y body. Te dejo el cURL:
curl --request POST \
--url https://{{BASE_URL}}/api/v1/bots/run/{{BOT_ID}} \
--header 'Authorization: Bearer {{TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
"orderId": "OC-2026-0451",
"amount": 15000,
"currency": "CLP",
"meta": {
"date": "2026-04-20T16:53:37.775Z",
"userId": "69cd4daf23f8df0fbeaf8332"
}
}'En una etapa de Cotlang podrías obtener el orderId así:
$VALUE#orderId
O si quisieras obtener el userId que está dentro de meta podrías hacerlo así:
$VALUE#meta|userIdorderId y el sistema externo manda order_id, la rutina fallará en silencio y nadie te va a notificar.Esto es un arma de doble filo. Por un lado, te da flexibilidad total. Por otro, te obliga a ser responsable con lo que recibes. Como mínimo, agrega una etapa de CCJS al inicio de la rutina que verifique los campos esperados antes de continuar.
Capítulo 5: Los bots también se invocan desde adentro
Hasta aquí hemos hablado de sistemas externos llamando al bot. Pero hay un uso que pocos conocen y que cambia la dinámica de cómo diseñas tus flujos: invocar un bot desde el mismo Cotalker.
¿Por qué querrías hacer esto? Por una limitación que cualquier implementador con algo de experiencia conoce: Cotalker no permite reutilizar un mismo formulario (survey) en múltiples estados de un flujo de trabajo de forma nativa. Si tienes un formulario de actualización de datos y necesitas que esté disponible en tres estados distintos, la solución "oficial" es duplicarlo tres veces. Sí, tres formularios idénticos que hay que mantener sincronizados manualmente. Un ritual de mantenimiento que no le deseo a ningún hechicero.
Pero si usas un bot como intermediario, puedes tener un solo formulario que invoque al bot, y el bot ejecuta la lógica independientemente del estado en el que se encuentre la tarea. Un formulario, un bot, múltiples estados. Sin duplicación, sin dolor de cabeza de mantenimiento.
Este patrón es tan útil que merece su propia entrada dedicada. En un futuro Códice Cotalker expandiré este caso con ejemplos concretos y la arquitectura recomendada para implementarlo. Por ahora, quédate con la idea: el bot no es solo una puerta de entrada desde el exterior, también es un puente interno entre las partes de tu propio flujo.
Capítulo 6: Un vistazo al nuevo grimorio ESM Code
Hace poco Cotalker añadió una nueva etapa de rutina llamada ESM Code. Es, esencialmente, una versión vitaminada del CCJS clásico, pero con acceso a librerías que antes eran impensables dentro de una rutina nativa. Entre ellas, una que quienes leen este blog reconocerán de inmediato: Zod.
¿Qué significa esto en la práctica? Que ahora puedes validar el body que llega al bot directamente dentro de la rutina, sin necesidad de una integración serverless intermedia. Para ciertos casos puntuales (y subrayo: puntuales), donde la lógica es simple y la transformación es mínima, podrías construir un endpoint funcional usando exclusivamente el bot y sus etapas nativas. Piensa en escenarios donde un cliente necesita actualizar unos pocos campos del asset de una tarea y nada más: no necesitas levantar una integración para eso.
No voy a profundizar aquí porque la combinación de ESM Code con todo lo que permite merece un artículo dedicado en Códice Cotalker (ya está en el grimorio de los pendientes). Pero quiero que sepas que existe, porque cambia el umbral de cuándo necesitas una integración externa y cuándo puedes resolver todo desde dentro de Cotalker.
Capítulo 7: El mapa de las doce conexiones
Ahora que entiendes qué es un bot, y que puede ser utilizado como un endpoint para ser invocado desde fuera con capacidades que van más allá de lo que la documentación sugiere, estás listo para ver el panorama completo.
A lo largo de mi trabajo con integraciones en Cotalker, he identificado doce patrones de conexión distintos entre la plataforma y el mundo exterior. Los llamo Conexiones A a L, y cada una combina bots, integraciones serverless, schedulers y llamadas directas de formas diferentes según el escenario. No dejes que la cantidad te abrume, no hay necesidad de saberlas de memoria.
Algunas son simples: un sistema externo llama al bot y listo. Otras involucran capas intermedias de transformación. También hay algunas bastante similares que son simplemente leves variaciones de otras. Hay una en particular que funciona perfectamente, pero que si un auditor la encuentra vas a tener que explicar por qué hay credenciales viviendo donde no deberían vivir.
No voy a detallar las doce conexiones aquí porque cada una merece su propia entrada con diagramas, casos de uso y advertencias. Pero para que tengas el mapa completo de lo que viene:
| Conexión | Flujo |
|---|---|
| A | Externo → Bot |
| B | Externo → Integración → Bot |
| C | Externo → Integración |
| D | Externo → Integración → Scheduler |
| E | Cotalker → Bot |
| F | Cotalker → Bot → Endpoint Externo |
| G | Cotalker → Externo |
| H | Cotalker → Integración → Externo |
| I | Cotalker → Integración → Externo → Integración |
| J | Cotalker → Integración → Externo → Integración → Scheduler |
| K | Cotalker → Integración → Externo → Integración → Cotalker |
| L | Cotalker → Integración → Externo → Bot |
Cada conexión tiene su momento y su razón de ser. El bot que aprendiste hoy es la pieza que aparece en la mayoría de ellas, y por eso era fundamental empezar por aquí.
Capítulo 8: Cerrando el portal (por ahora)
El bot en Cotalker no es simplemente una automatización que responde a un slash command o a un comando encuesta. Es un endpoint. Es una puerta de entrada desde el exterior. Es un puente interno entre estados de un flujo. Y con las capacidades nuevas como ESM Code, es cada vez más un pequeño servidor viviendo dentro de tu rutina.
Que nadie te lo haya contado antes no significa que no existiera. Solo significa que ahora tienes una ventaja que la mayoría no tiene. Un pequeño secreto arcano que, como buen conjuro, solo necesitaba que alguien lo pronunciara en voz alta.
En la próxima entrega abriremos las Conexiones A y B: cuando el mundo exterior llama a Cotalker. Veremos por qué la opción más obvia no siempre es la mejor, y cuál es el patrón que realmente uso en producción
Referencias:
Member discussion