База знаний GetMyBot

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

Как хранить заявки, заказы и записи на занятия прямо в GetMyBot: создать таблицу, добавить данные и использовать их в реакциях.

На этой странице

Коллекция похожа на таблицу: одна строка содержит одну заявку, один заказ или одну запись на занятие. Бот может добавлять строки из ответов пользователей, а вы можете просматривать и редактировать их в разделе Данные → Коллекции.

Например, для записи на консультацию создайте коллекцию leads с полями name, phone, topic. После вопросов бот сохранит имя, телефон и тему в одну строку. Позже эти записи можно найти и использовать в реакции.

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

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

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

Типы полей

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

ТипЧто хранитПример применения
textТекстовую строкуИмя, email или комментарий
numberЧислоСумму, количество или баллы
boolДа или нет: true / falseОплачен ли заказ
datetimeДату и времяВремя записи на занятие
jsonВложенный объект или списокСостав заказа со свойствами товаров

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

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

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

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

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

  • Просмотр: все строки выводятся списком, по полю на ячейку, начиная с самых свежих.
  • Добавить запись: открывает форму по схеме коллекции; каждое поле редактируется по своему типу (переключатель для 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. Связь описывает назначение поля; каскадного изменения или удаления записей нет.

  1. В реакции на входящий текст добавьте Поиск по коллекции (record_search). Выберите products, запрос {{text}}, поле поиска name, поле синонимов aliases и сохранение в search. Синонимы могут быть строкой или массивом строк JSON. Поиск не различает регистр, е и ё; знаки препинания заменяются пробелами.
  2. Добавьте Выбрать следующий шаг (branch_result) с источником search. Первая совпавшая ветка выполняется. Сначала обработайте Неполную выдачу предложением уточнить запрос, затем Ничего не найдено, Неточное совпадение, Одну запись и Несколько записей. Для неточного совпадения покажите подтверждение. Пустой и единственный результат требуют полной выдачи.
  3. Для нескольких результатов в сообщении откройте Кнопки из найденных записей. Выберите источник search, подпись name и следующую реакцию. Помощник заполнит buttons_from.over = search.rows, шаблон подписи и carry.selected_id = {{item._record_id}}. Убедитесь, что поле подписи входит в поля результата. Расширенный редактор кнопки остаётся доступен.
  4. В следующей реакции добавьте Найти связанные записи (record_related): коллекция variants, ключ product_id, значение {{ctx.selected_id}}, результат variants. Для чтения самой выбранной записи используйте products и ключ _record_id. Если нужные связи хранятся по бизнес-ключу, выберите этот ключ в помощнике кнопок и в действии чтения.
  5. Снова выберите ветку по результату. Единственную запись покажите как карточку через {{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 подойдёт, когда структура значения заранее не фиксирована.