Base de conocimiento de GetMyBot

Colecciones y datos

Cómo guardar solicitudes, pedidos e inscripciones en GetMyBot: crear una tabla, añadir datos y utilizarlos en las reacciones.

En esta página

Una colección se parece a una tabla: cada fila representa una solicitud, un pedido o una inscripción. El bot puede añadir filas a partir de las respuestas de las personas. Tú puedes verlas y modificarlas en Datos → Colecciones.

Por ejemplo, para reservar consultas, crea una colección leads con los campos name, phone y topic. Después de hacer las preguntas, el bot guardará las respuestas en una fila. Más adelante, una reacción podrá buscarla y utilizarla.

¿Qué es una colección?

Los campos definen las columnas, por ejemplo «Teléfono» y «Tema». Un registro contiene los valores de una fila. La lista de campos y tipos se llama esquema. Cada registro se guarda como un documento JSON, por lo que puedes añadir un campo sin rehacer los registros existentes.

Cada colección tiene un nombre único dentro del bot. Las acciones lo usan como identificador, por ejemplo leads, orders o scores.

Tipos de campos

Al crear una colección, define una lista de campos y el tipo de cada uno:

TipoQué guardaEjemplo
textTextoNombre, correo o comentario
numberUn númeroImporte, cantidad o puntos
boolSí o no: true / falseSi el pedido está pagado
datetimeFecha y horaHora de una clase
jsonUn objeto o lista con otros valores dentroProductos de un pedido y sus propiedades

El tipo determina cómo se edita el campo y cómo se convierte el valor al guardarlo. El esquema es flexible: un campo que no figure en él también se guarda y aparece como otra columna.

Crear una colección

  1. Abre Datos → Colecciones y pulsa Añadir.
  2. Escribe un nombre con letras latinas y sin espacios, para poder usarlo fácilmente en las reacciones.
  3. Pulsa Campo para añadir las columnas y elegir sus tipos.
  4. Configura las reglas de conservación si las necesitas (más abajo) y guarda.

Registros: visualización y edición

El botón con el icono de tabla en la tarjeta de la colección abre la ventana Datos:

  • Ver: muestra los registros, empezando por los más recientes.
  • Añadir registro: abre un formulario con los campos de la colección. Cada tipo tiene su control, como un interruptor para bool o un campo JSON para json.
  • Editar (lápiz): cambia un registro existente.
  • Eliminar (papelera): borra un registro.

Las reacciones del bot también pueden añadir registros automáticamente. Las modificaciones manuales y automáticas se hacen en la misma colección.

Retención

Para que una colección no crezca sin límite, configura su limpieza automática:

  • Máximo de registros: al superar el límite, se eliminan los más antiguos.
  • Conservar durante (días): se eliminan los registros anteriores al plazo indicado.

Por ejemplo, 30 días pueden ser adecuados para un registro temporal. La limpieza se ejecuta periódicamente, no necesariamente en el momento exacto en que termina el plazo. Puedes combinar las dos reglas. No pongas un plazo corto a pedidos que aún debes tramitar.

Trabajar con datos de reacciones

El editor de reacciones puede utilizar estas acciones sobre colecciones:

  • Crear registro: añade una fila con sustituciones como {{user_id}} y {{text}}. Una clave de deduplicación evita filas repetidas: si la acción se repite con la misma clave, actualiza el registro existente. Usa el ID de la persona como clave si quieres conservar una sola solicitud actual por cliente.
  • Actualizar registros: cambia las filas que cumplan una condición.
  • Consultar registros: lee filas como lista para utilizarlas en las siguientes acciones.
  • Leer página de colección (record_page): carga registros por partes, por ejemplo dos tarjetas y un botón para ver la siguiente página.
  • Total de la colección completa (record_aggregate): cuenta o suma todos los registros coincidentes dentro del plazo de conservación. Cargar solo una página no limita este cálculo.
  • Transacción de colección (collection_transaction): comprueba condiciones y guarda varios cambios juntos, por ejemplo reservar una plaza y crear la inscripción. Si una condición falla, se deshacen también los cambios anteriores de esa transacción.
  • Eliminar registros: borra las filas que cumplan una condición.
  • Bucle (para cada elemento): recorre una lista de la ejecución actual y realiza acciones por cada elemento.

Así, el bot puede guardar solicitudes, asignar puntos y preparar informes sin una base de datos aparte.

Las lecciones prácticas explican cómo continuar un catálogo, calcular el total de todos los pedidos coincidentes y reservar la última plaza. Una lista ya cargada, una página de registros y un total de la colección completa proporcionan datos distintos al siguiente paso.

Un bucle no sirve para enviar una difusión. Una ejecución recorre como máximo 500 elementos, pero todo el evento puede enviar solo 50 mensajes. Si envías un mensaje por elemento, los siguientes a esos 50 no se entregarán. Para escribir a las personas de una colección, crea un segmento y envía una difusión, que permite controlar la velocidad, pausar y consultar las entregas. Consulta Límites de un evento.

Catálogo: buscar, elegir y mostrar una ficha

Empieza por la lección de búsqueda de clases. Explica qué colecciones preparar, en qué orden añadir acciones y cómo probar una búsqueda sin resultados, varias coincidencias y un botón antiguo.

Para un catálogo, guarda los datos por separado de las reacciones. Por ejemplo, products tiene name y aliases; variants tiene product_id, name y card. Al editar variants.product_id, activa Enlace a otra colección y elige products, la clave _record_id y name como texto visible. El enlace explica qué representa el campo; cambiar o borrar un producto no modifica automáticamente sus variantes.

  1. En una reacción para texto recibido, añade Buscar en colección (record_search). Elige products, la búsqueda {{text}}, el campo name, los sinónimos aliases y guarda el resultado como search. Los sinónimos pueden ser un texto o una lista de textos JSON. La búsqueda no distingue mayúsculas ni las letras rusas е y ё; la puntuación se sustituye por espacios.
  2. Añade Elegir siguiente paso (branch_result) con origen search. Se ejecuta la primera rama que coincida. Trata primero Resultados incompletos pidiendo una búsqueda más precisa; después Nada encontrado, Coincidencia aproximada, Un registro y Varios registros. Pide confirmación de las coincidencias aproximadas. Para considerar vacío o único un resultado, la búsqueda debe estar completa.
  3. Para varios registros, abre Botones de registros encontrados en el mensaje. Elige search, el campo name para el texto del botón y la siguiente reacción. El asistente completa buttons_from.over = search.rows, la plantilla de texto y carry.selected_id = {{item._record_id}}. Asegúrate de incluir el campo visible en los resultados. También puedes usar el editor avanzado del botón.
  4. En la siguiente reacción, añade Buscar registros relacionados (record_related): colección variants, clave product_id, valor {{ctx.selected_id}} y resultado variants. Para leer el producto elegido, usa products y la clave _record_id. Si la relación usa otra clave propia del negocio, elige la misma en el asistente de botones y en la acción de lectura.
  5. Vuelve a elegir una rama según el resultado. Muestra una variante como ficha con {{ctx.variants.first.card}}; si hay varias, muéstralas como botones. Cada botón lleva un ID y, después de pulsarlo, el bot lee los datos actuales. No guardes la ficha ni otros campos que pueden cambiar en carry.

Leer el resultado

search.rows es una lista de registros; search.count indica cuántas filas se cargaron, search.first es el primer registro y search.first.name es uno de sus campos. Cada fila también tiene _record_id, _score y _match_type, nombres reservados. Si no se encuentra nada, se borran los datos anteriores del primer registro.

search.total cuenta las coincidencias entre los candidatos examinados. total_exact = false indica que no se revisó toda la colección; truncated = true indica que se limitó el resultado. En esos casos no lo trates como completo ni supongas que contiene la mejor coincidencia de toda la colección. Una búsqueda examina hasta 10 000 registros o 16 MiB de datos. La respuesta informa de los límites aplicados. Devuelve hasta 100 filas por defecto y hasta 10 000 como máximo.

Probar y entender la búsqueda

Pulsa Probar búsqueda en el editor e introduce un texto o ID de prueba. Solo lee datos: no ejecuta las siguientes reacciones ni envía mensajes. Sustituye previamente las variables de los filtros adicionales por valores concretos. La prueba muestra las filas, el tipo de coincidencia, cuántos registros se examinaron y los límites. Si cambias de proyecto, colección, ajustes o permisos, los resultados anteriores se ocultan.

El registro de ejecución muestra los campos buscados, los tipos de coincidencia, cuántas filas se examinaron y devolvieron, los límites y la rama elegida. El diagrama de la reacción indica todas las condiciones que llevan a una misma reacción. Al revisar una ejecución anterior, abre el evento correspondiente para ver la explicación de la búsqueda, siempre que tengas permiso para consultar su contenido.

El asistente crea hasta 20 botones de forma predeterminada. Puedes cambiar Máximo de botones entre 1 y 100. Es un límite, no una paginación. Una lista vacía no crea botones. Para resultados mayores, añade una rama que pida precisar la búsqueda.

El asistente Operación sobre la lista cargada de Calcular crea fórmulas para contar registros, obtener el primero, sumar un campo o reunir sus textos. Usa solo las filas cargadas: con un resultado incompleto no puede calcular el total de toda la colección.

API y MCP

Estas operaciones también están disponibles mediante POST /api/bots/{botID}/collections/{name}/search y /related, así como con las herramientas MCP search_records y related_records con permiso collections:read. Cada llamada queda limitada al proyecto y la región actuales. Las pruebas REST usan valores concretos; las sustituciones se calculan en las acciones de las reacciones.

Procesar resultados y hacer cambios condicionales

Puedes pasar un resultado de colección a list_transform para filtrar, ordenar, quitar duplicados o seleccionar una página. list_aggregate calcula totales con nombre a partir de las filas cargadas y puede agruparlas. Las dos acciones también sirven para listas recibidas por HTTP, sin usar una colección.

Para impedir que dos ejecuciones simultáneas apliquen el mismo cambio de estado, usa record_update_if: indica el ID, los valores que esperas encontrar y los valores nuevos. La comprobación y la modificación se hacen juntas para un registro. Después, branch_value permite tratar por separado los estados guardados updated, conflict y not_found. Esto es distinto de cambiar sin comprobación previa todas las filas que cumplan un filtro.

Consulta Configuración, límites y ejemplos.

La lección sobre confirmar una reserva una sola vez explica cómo comprobar el estado y el propietario y cómo responder por separado a updated, conflict y not_found.

Acceso desde la mini aplicación

La miniaplicación de Telegram de tu bot puede leer registros de una colección por nombre, con filtros y un límite. Así puedes mostrar a cada persona sus pedidos, su historial o una clasificación dentro de Telegram.

Consejos

  • Usa nombres cortos para los campos (email, total, paid), así resultan fáciles de insertar en las reacciones.
  • Usa una clave de deduplicación si repetir una acción no debe crear otro registro. Esta propiedad también se llama idempotencia.
  • Configura la conservación para registros temporales que dejarán de hacer falta.
  • Usa json si la estructura de un valor no se conoce de antemano.