Коллекции и данные

Коллекции служат таблицами данных вашего бота. В них удобно складывать заявки, заказы, ответы из диалогов, очки в игре, записи на занятия: всё, что бот собирает у пользователей или получает из интеграций. Раздел находится в меню слева: Данные → Коллекции.

Что такое коллекция

Коллекция состоит из полей (схема, описывающая столбцы) и записей (строки с данными). Каждая запись содержит набор значений по полям коллекции; внутри она хранится как гибкий JSON-документ, поэтому коллекция спокойно переживает добавление новых полей.

Имя коллекции уникально в пределах одного бота и используется как идентификатор в действиях реакций (например, leads, orders, scores).

Типы полей

При создании коллекции вы задаёте список полей и тип каждого:

• text: строка (имя, email, комментарий).
• number: число (сумма, количество, очки).
• bool: да/нет (true / false).
• datetime: дата и время.
• json: вложенный объект или массив для сложных значений.

Тип влияет на то, как поле редактируется в интерфейсе и как значение приводится при сохранении. Схема не жёсткая: если в записи окажется поле вне схемы, оно сохранится и отобразится отдельным столбцом.

Создание коллекции

1. Откройте Данные → Коллекции и нажмите Добавить.
2. Укажите название (латиницей, без пробелов: так на неё проще ссылаться в реакциях).
3. Кнопкой Поле добавьте нужные столбцы и выберите тип каждого.
4. При необходимости задайте правила хранения (см. ниже) и сохраните.

Записи: просмотр и редактирование

На карточке коллекции есть кнопка с иконкой таблицы: она открывает окно Данные с записями этой коллекции:

• Просмотр: все строки выводятся списком, по полю на ячейку, начиная с самых свежих.
• Добавить запись: открывает форму по схеме коллекции; каждое поле редактируется по своему типу (переключатель для bool, поле ввода JSON для json и т. д.).
• Изменить (карандаш): правит существующую строку.
• Удалить (корзина): удаляет строку.

Записи также наполняются автоматически: действиями реакций бота (см. ниже). Ручное редактирование и автозапись работают с одной и той же коллекцией.

Хранение (retention)

Чтобы коллекция не росла бесконечно, задайте правила автоочистки:

• Хранить максимум записей: при превышении лимита самые старые записи удаляются.
• Хранить не дольше (дней): записи старше указанного срока удаляются.

Очистка выполняется фоновым процессом периодически; правила можно комбинировать.

Работа с данными из реакций

Коллекции напрямую связаны с конструктором реакций. В действиях реакции доступны:

• Создать запись: добавляет строку; значения берутся из шаблонов (например, {{user.id}}, {{message.text}}). Можно задать ключ дедупликации, чтобы повторный вызов обновлял ту же строку, а не плодил дубли.
• Обновить записи: изменяет строки, подходящие под условие.
• Запросить записи: читает строки в контекст выполнения как массив, чтобы дальше перебрать их.
• Удалить записи: удаляет строки по условию.
• Цикл (for-each): проходит по массиву из контекста и выполняет вложенные действия для каждого элемента: обновить каждую строку, посчитать итог, отправить каждую запись во внешний сервис.

Так бот может вести CRM, копить заявки, начислять баллы и строить отчёты без внешней базы данных.

Цикл: не инструмент рассылки. За один проход он берёт не больше 500 элементов, а всё событие целиком может отправить не больше 50 сообщений: цикл с отправкой сообщения внутри доставит первые 50 и получит отказ на остальных. Чтобы написать людям из коллекции, соберите по ней сегмент и отправьте рассылку: там есть скорость, пауза и учёт отправленного. Подробнее о границах: Действия → Бюджет одного события.

Доступ из Mini App

Записи коллекции можно читать из Telegram Mini App вашего бота: фронтенд запрашивает данные коллекции по имени с фильтрами и лимитом. Это позволяет показывать пользователю его заказы, историю или таблицу лидеров прямо внутри Telegram.

Советы

• Давайте полям короткие машинные имена (email, total, paid): их удобнее подставлять в шаблоны реакций.
• Для идемпотентной записи (например, «одна заявка на пользователя») используйте ключ дедупликации.
• Включайте retention для логов и временных данных, чтобы коллекция не разрасталась.
• Тип json подойдёт, когда структура значения заранее не фиксирована.