База знань 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 користувача дає змогу зберігати одну актуальну заявку на людину.
  • Оновити записи: змінює рядки, що відповідають умові.
  • Запитати записи: читає рядки в контекст виконання як масив, щоб далі перебрати їх.
  • Read collection page (record_page): читає записи частинами, наприклад по дві картки з кнопкою наступної сторінки.
  • Aggregate whole collection (record_aggregate): рахує кількість і суми за всіма відповідними записами в межах правил зберігання. Завантаження лише першої сторінки не обмежує цей підрахунок.
  • Atomic collection transaction (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 підходить, коли структура значення заздалегідь не відома.