Коллекции и данные
Как хранить заявки, заказы и записи на занятия прямо в GetMyBot: создать таблицу, добавить данные и использовать их в реакциях.
На этой странице
Коллекция похожа на таблицу: одна строка содержит одну заявку, один заказ или одну запись на занятие. Бот может добавлять строки из ответов пользователей, а вы можете просматривать и редактировать их в разделе Данные → Коллекции.
Например, для записи на консультацию создайте коллекцию leads с полями name, phone, topic. После вопросов бот сохранит имя, телефон и тему в одну строку. Позже эти записи можно найти и использовать в реакции.
Что такое коллекция
Поля задают столбцы, например «Телефон» и «Тема». Запись содержит значения одной строки. Список полей и их типов называется схемой. Технически запись хранится как JSON-документ: добавление нового поля не требует пересоздавать уже сохранённые строки.
Имя коллекции уникально в пределах одного бота и используется как идентификатор в действиях реакций (например, leads, orders, scores).
Типы полей
При создании коллекции вы задаёте список полей и тип каждого:
| Тип | Что хранит | Пример применения |
|---|---|---|
text | Текстовую строку | Имя, email или комментарий |
number | Число | Сумму, количество или баллы |
bool | Да или нет: true / false | Оплачен ли заказ |
datetime | Дату и время | Время записи на занятие |
json | Вложенный объект или список | Состав заказа со свойствами товаров |
Тип влияет на то, как поле редактируется в интерфейсе и как значение приводится при сохранении. Схема не жёсткая: если в записи окажется поле вне схемы, оно сохранится и отобразится отдельным столбцом.
Создание коллекции
- Откройте Данные → Коллекции и нажмите Добавить.
- Укажите название (латиницей, без пробелов: так на неё проще ссылаться в реакциях).
- Кнопкой Поле добавьте нужные столбцы и выберите тип каждого.
- При необходимости задайте правила хранения (см. ниже) и сохраните.
Записи: просмотр и редактирование
На карточке коллекции есть кнопка с иконкой таблицы: она открывает окно Данные с записями этой коллекции:
- Просмотр: все строки выводятся списком, по полю на ячейку, начиная с самых свежих.
- Добавить запись: открывает форму по схеме коллекции; каждое поле редактируется по своему типу (переключатель для
bool, поле ввода JSON дляjsonи т. д.). - Изменить (карандаш): правит существующую строку.
- Удалить (корзина): удаляет строку.
Записи также наполняются автоматически: действиями реакций бота (см. ниже). Ручное редактирование и автозапись работают с одной и той же коллекцией.
Хранение (retention)
Чтобы коллекция не росла бесконечно, задайте правила автоочистки:
- Хранить максимум записей: при превышении лимита самые старые записи удаляются.
- Хранить не дольше (дней): записи старше указанного срока удаляются.
Например, срок 30 дней подходит для временного журнала: более старые строки будут удаляться автоматически. Очистка выполняется периодически, а не точно в момент окончания срока. Оба ограничения можно включить одновременно. Не задавайте срок хранения для заказов, которые ещё нужны в работе.
Работа с данными из реакций
Коллекции напрямую связаны с конструктором реакций. В действиях реакции доступны:
- Создать запись: добавляет строку; значения берутся из подстановок, например
{{user_id}}и{{text}}. Ключ дедупликации помогает не создавать дубли: при том же ключе повторный вызов обновит уже существующую строку. Например, ключ по ID пользователя позволяет хранить одну актуальную заявку на человека. - Обновить записи: изменяет строки, подходящие под условие.
- Запросить записи: читает строки в контекст выполнения как массив, чтобы дальше перебрать их.
- Прочитать страницу коллекции (
record_page): читает записи порциями, например по две карточки с кнопкой следующей страницы. - Итоги всей коллекции (
record_aggregate): считает количество и суммы по всем подходящим записям в пределах правил хранения. Загрузка только первой страницы не ограничивает этот расчёт. - Атомарная транзакция коллекций (
collection_transaction): проверяет условия и сохраняет несколько изменений вместе, например занимает место и создаёт заявку. При конфликте ранние изменения тоже откатываются. - Удалить записи: удаляет строки по условию.
- Цикл (for-each): проходит по массиву из контекста и выполняет вложенные действия для каждого элемента: обновить каждую строку, посчитать итог, отправить каждую запись во внешний сервис.
Так бот может вести CRM, копить заявки, начислять баллы и строить отчёты без внешней базы данных.
Практические уроки показывают продолжение каталога, итог по всем подходящим заказам и бронирование последнего места. Страница загруженного списка, страница коллекции и итог по коллекции решают разные задачи; в уроках показано, какие данные получает следующий шаг.
Цикл: не инструмент рассылки. За один проход он берёт не больше 500 элементов, а всё событие целиком может отправить не больше 50 сообщений: цикл с отправкой сообщения внутри доставит первые 50 и получит отказ на остальных. Чтобы написать людям из коллекции, соберите по ней сегмент и отправьте рассылку: там есть скорость, пауза и учёт отправленного. Подробнее о границах: Действия → Бюджет одного события.
Каталог: поиск, выбор и карточка
Для первого знакомства пройдите урок поиска занятия. Он объясняет, какие коллекции подготовить, в каком порядке добавить действия и как проверить пустой результат, несколько совпадений и нажатие старой кнопки.
Для каталога достаточно хранить данные отдельно от реакций. Например, коллекция products содержит name и aliases, а variants содержит product_id, name и card. В редакторе поля variants.product_id включите Связь с другой коллекцией, выберите products, ключ _record_id и поле подписи name. Связь описывает назначение поля; каскадного изменения или удаления записей нет.
- В реакции на входящий текст добавьте Поиск по коллекции (
record_search). Выберитеproducts, запрос{{text}}, поле поискаname, поле синонимовaliasesи сохранение вsearch. Синонимы могут быть строкой или массивом строк JSON. Поиск не различает регистр, е и ё; знаки препинания заменяются пробелами. - Добавьте Выбрать следующий шаг (
branch_result) с источникомsearch. Первая совпавшая ветка выполняется. Сначала обработайте Неполную выдачу предложением уточнить запрос, затем Ничего не найдено, Неточное совпадение, Одну запись и Несколько записей. Для неточного совпадения покажите подтверждение. Пустой и единственный результат требуют полной выдачи. - Для нескольких результатов в сообщении откройте Кнопки из найденных записей. Выберите источник
search, подписьnameи следующую реакцию. Помощник заполнитbuttons_from.over = search.rows, шаблон подписи иcarry.selected_id = {{item._record_id}}. Убедитесь, что поле подписи входит в поля результата. Расширенный редактор кнопки остаётся доступен. - В следующей реакции добавьте Найти связанные записи (
record_related): коллекцияvariants, ключproduct_id, значение{{ctx.selected_id}}, результатvariants. Для чтения самой выбранной записи используйтеproductsи ключ_record_id. Если нужные связи хранятся по бизнес-ключу, выберите этот ключ в помощнике кнопок и в действии чтения. - Снова выберите ветку по результату. Единственную запись покажите как карточку через
{{ctx.variants.first.card}}; несколько вариантов покажите кнопками. Каждая кнопка передаёт ID, а актуальные данные читаются после нажатия. Не храните карточку или другие изменяемые поля вcarry.
Результат чтения
search.rows содержит плоский список записей, search.count – число загруженных строк, search.first – первую запись, а search.first.name – конкретное поле. Каждая строка дополнена _record_id, _score и _match_type; эти три имени зарезервированы. Если записей нет, предыдущая первая запись и её поля очищаются.
search.total считает совпадения среди проверенных кандидатов. total_exact = false означает, что полная коллекция не проверена; truncated = true предупреждает об ограничении выдачи. Нельзя считать такой результат полным или гарантировать лучший тип совпадения во всей коллекции. За один запрос проверяются до 10 000 записей и 16 МиБ данных; ответ содержит фактические ограничения. По умолчанию возвращаются до 100 строк, максимум 10 000.
Проверка и объяснение
В редакторе поиска откройте Проверить поиск и введите конкретную тестовую строку или ID. Это только чтение: следующие реакции, сообщения и другие действия не выполняются. Подстановки в дополнительных фильтрах предварительно замените значениями. Проверка показывает строки, тип совпадения, число просмотренных записей и ограничения. При смене проекта, коллекции, настроек или прав доступа старые результаты скрываются.
В журнале выполнения показаны поля поиска, тип совпадения, количество проверенных и возвращённых строк, ограничение выдачи и выбранная ветка. На схеме реакции подписаны все условия, ведущие к одной реакции. При повторном просмотре записи выполнения объяснение поиска доступно после открытия соответствующего события, если у вас есть право на его содержимое.
Помощник кнопок по умолчанию создаёт до 20 кнопок. Максимум кнопок можно изменить от 1 до 100; это ограничение, а не пагинация. Пустой список не создаёт кнопок. Для большей выдачи добавьте ветку уточнения запроса.
В действии Вычисление помощник Операция над загруженным списком создаёт формулы количества записей, первой записи, суммы поля и списка подписей. Расчёт выполняется по загруженным строкам, а при неполной выдаче не является итогом всей коллекции.
API и MCP
Те же операции доступны через POST /api/bots/{botID}/collections/{name}/search и /related, а также MCP-инструменты search_records и related_records с правом collections:read. Вызовы ограничены текущим проектом и регионом. REST-проверка принимает конкретные значения, а шаблонные подстановки выполняются в действиях реакций.
Обработка результата и условные изменения
Результат коллекции можно передать в list_transform: отобрать строки,
упорядочить, убрать повторы или взять страницу. list_aggregate считает
именованные итоги по загруженным строкам, при необходимости с группировкой.
Те же действия работают и с обычным списком из HTTP-ответа, без коллекции.
Чтобы два одновременных запуска не применили один переход состояния повторно,
используйте record_update_if: укажите ID, ожидаемые поля и новые значения.
Проверка и изменение выполняются атомарно для одной записи. Сохранённый статус
updated, conflict или not_found можно обработать через branch_value.
Это отличается от безусловного изменения всех строк, подходящих под фильтр.
Настройка, ограничения и примеры.
Практика: подтверждение заявки без повторной записи разбирает проверку статуса и владельца, а также отдельные ответы для updated, conflict и not_found.
Доступ из Mini App
Записи коллекции можно читать из Telegram Mini App вашего бота: фронтенд запрашивает данные коллекции по имени с фильтрами и лимитом. Это позволяет показывать пользователю его заказы, историю или таблицу лидеров прямо внутри Telegram.
Советы
- Давайте полям короткие машинные имена (
email,total,paid): их удобнее подставлять в шаблоны реакций. - Чтобы повтор одного действия не создавал новую строку, используйте ключ дедупликации. Это свойство называется идемпотентностью.
- Задавайте срок хранения (
retention) для журналов и временных данных, которые больше не нужны. - Тип
jsonподойдёт, когда структура значения заранее не фиксирована.