Колекції та дані

Колекції — це власні таблиці даних вашого бота. У них зручно зберігати заявки, замовлення, відповіді з діалогів, очки у грі, записи на заняття — все, що бот збирає у користувачів або отримує з інтеграцій. Розділ знаходиться в меню ліворуч: Дані → Колекції.

Що таке колекція

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

Ім'я колекції унікальне в межах одного бота і використовується як ідентифікатор у діях реакцій (наприклад, leads, orders, scores).

Типи полів

При створенні колекції ви задаєте список полів і тип кожного:

text — рядок (ім'я, email, коментар).
number — число (сума, кількість, очки).
bool — так/ні (true / false).
datetime — дата і час.
json — вкладений об'єкт або масив для складних значень.

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

Створення колекції

Відкрийте Дані → Колекції і натисніть Додати.
Вкажіть назву (латиницею, без пробілів — так на неї простіше посилатися в реакціях).
Кнопкою Поле додайте потрібні стовпці й оберіть тип кожного.
За потреби задайте правила зберігання (див. нижче) і збережіть.

Записи: перегляд і редагування

На картці колекції є кнопка з іконкою таблиці — вона відкриває вікно Дані з записами цієї колекції:

Перегляд — всі рядки виводяться списком, по полю на клітинку, починаючи з найновіших.
Додати запис — відкриває форму за схемою колекції; кожне поле редагується за своїм типом (перемикач для bool, поле вводу JSON для json тощо).
Змінити (олівець) — редагує наявний рядок.
Видалити (кошик) — видаляє рядок.

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

Зберігання (retention)

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

Зберігати максимум записів — при перевищенні ліміту найстаріші записи видаляються.
Зберігати не довше (днів) — записи, старші за вказаний термін, видаляються.

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

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

Колекції безпосередньо пов'язані з конструктором реакцій. У діях реакції доступні:

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

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

Доступ з Mini App

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

Поради

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