Colecciones y datos

Las colecciones son las tablas de datos propias de tu bot. Son perfectas para guardar solicitudes, pedidos, respuestas de diálogos, puntuaciones de un juego, inscripciones a clases — todo lo que el bot recopila de los usuarios u obtiene de las integraciones. La sección se encuentra en el menú izquierdo: Datos → Colecciones.

Qué es una colección

Una colección se compone de campos (el esquema que describe las columnas) y registros (las filas con datos). Cada registro es un conjunto de valores por campo; internamente se almacena como un documento JSON flexible, por lo que la colección soporta sin problemas la adición de nuevos campos.

El nombre de la colección es único dentro de un bot y se usa como identificador en las acciones de las reacciones (por ejemplo, leads, orders, scores).

Tipos de campo

Al crear una colección defines la lista de campos y el tipo de cada uno:

text — cadena de texto (nombre, email, comentario).
number — número (importe, cantidad, puntos).
bool — sí/no (true / false).
datetime — fecha y hora.
json — objeto anidado o array para valores complejos.

El tipo influye en cómo se edita el campo en la interfaz y en cómo se convierte el valor al guardar. El esquema no es rígido: si un registro contiene un campo fuera del esquema, se guardará y se mostrará como columna adicional.

Creación de una colección

Abre Datos → Colecciones y pulsa Añadir.
Indica el nombre (en caracteres latinos, sin espacios — así es más fácil referenciarlo en las reacciones).
Con el botón Campo añade las columnas necesarias y elige el tipo de cada una.
Si es necesario, define las reglas de almacenamiento (ver más abajo) y guarda.

Registros: visualización y edición

En la tarjeta de la colección hay un botón con ícono de tabla — abre la ventana Datos con los registros de esa colección:

Visualización — todas las filas se muestran en lista, un campo por celda, comenzando por los más recientes.
Añadir registro — abre el formulario según el esquema de la colección; cada campo se edita según su tipo (interruptor para bool, campo de entrada JSON para json, etc.).
Editar (lápiz) — modifica una fila existente.
Eliminar (papelera) — borra una fila.

Los registros también se completan automáticamente mediante las acciones de las reacciones del bot (ver más abajo). La edición manual y la escritura automática operan sobre la misma colección.

Almacenamiento (retention)

Para que la colección no crezca indefinidamente, define reglas de limpieza automática:

Guardar máximo de registros — al superar el límite, los registros más antiguos se eliminan.
Guardar no más de (días) — los registros más antiguos que el período indicado se eliminan.

La limpieza la ejecuta un proceso en segundo plano periódicamente; las reglas pueden combinarse.

Trabajo con datos desde las reacciones

Las colecciones están directamente vinculadas al constructor de reacciones. En las acciones de una reacción están disponibles:

Crear registro — añade una fila; los valores se toman de las plantillas (por ejemplo, {{user.id}}, {{message.text}}). Puedes definir una clave de deduplicación para que una llamada repetida actualice la misma fila en lugar de crear duplicados.
Actualizar registros — modifica las filas que cumplan una condición.
Consultar registros — lee filas en el contexto de ejecución como un array para iterarlas después.
Eliminar registros — elimina filas según una condición.
Bucle (for-each) — recorre el array del contexto y ejecuta las acciones anidadas para cada elemento (por ejemplo, enviar un mensaje a cada elemento de la lista de la colección).

Así el bot puede llevar un CRM, acumular solicitudes, otorgar puntos y generar informes sin necesidad de una base de datos externa.

Acceso desde Mini App

Los registros de una colección se pueden leer desde la Telegram Mini App de tu bot: el frontend solicita los datos de la colección por nombre con filtros y límite. Esto permite mostrar al usuario sus pedidos, su historial o una tabla de clasificación directamente dentro de Telegram.

Consejos

Da a los campos nombres de máquina cortos (email, total, paid) — son más cómodos de insertar en las plantillas de las reacciones.
Para escritura idempotente (por ejemplo, «una solicitud por usuario») usa la clave de deduplicación.
Activa el retention para logs y datos temporales para que la colección no crezca demasiado.
El tipo json es ideal cuando la estructura del valor no está fijada de antemano.