Перейти к основному содержимому

Списки

Список — это таблица для хранения данных бота. Каждый список состоит из полей (колонок) и строк (записей). Списки нужны там, где переменной мало: каталог товаров, база клиентов, заявки, бронирования, история заказов, FAQ.

Списки хранятся на сервере Квесча и доступны из любого сценария бота. В отличие от переменной, список переживает перезапуск сценария и хранит сразу много записей.

Когда использовать список вместо переменной​

ЗадачаЧто выбрать
Сохранить имя клиентаПеременная
Сохранить корзину из нескольких товаровСписок
Счётчик заходовГлобальная переменная
База подписчиков с фильтрамиСписок
Один ID последнего заказаПеременная
История всех заказов клиентаСписок

Часть 1. Создание списка​

Шаг 1. Откройте раздел «Списки»​

В конструкторе перейдите на страницу «Списки».

Вкладка «Списки» в автоворонке Скриншот 1. Раздел «Списки / Переменные» в автоворонке.

Шаг 2. Создайте новый список​

Нажмите кнопку «Список». Откроется форма создания.

Заполните:

  • Название списка — латиницей или кириллицей, до 256 символов. По этому имени список выбирается в сценариях.
  • Поля — добавьте нужные колонки по одной через кнопку «Добавить».

Форма создания списка Скриншот 2. Создание нового списка и добавление полей.

Автоматические поля — «след» подписчика

К каждому списку Квесча автоматически добавляет четыре служебных поля:

  • ClientID — ID подписчика, оставившего запись;
  • Messenger — мессенджер, в котором он пришёл (telegram, max, wa, vk, viber, lp, jivo);
  • BotID — ID бота, в котором сделана запись;
  • CreationDate — дата и время создания записи.

Эти поля заполняются автоматически при добавлении строки из сценария — заполнять их вручную не нужно.

Зачем они нужны. Это «след», который связывает запись с конкретным подписчиком. Без него список — это просто общая таблица; с ним — персонализированная база. Благодаря автоматическому ClientID вы можете:

  • Найти все записи конкретного подписчика — фильтр ClientID равно [ClientID] вернёт только его строки (корзину, заказы, ответы на анкету).
  • Разделить данные клиентов — записи разных подписчиков не смешиваются: каждый видит только свою корзину/историю.
  • Очистить данные одного клиента — удалить только его строки, не трогая остальных.
  • Сравнивать клиентов — отобрать всех, у кого, например, поле статус = VIP, и пройтись по ним перебором.
  • Различать мессенджеры — фильтр по Messenger, если бот работает сразу в нескольких каналах.
  • Сортировать по времени — CreationDate даёт хронологию записей (последний заказ, первая заявка).
  • Анализировать активность — по CreationDate посчитать, сколько записей сделано за период.

Пример: в списке «Заказы» поле ClientID позволяет одной операцией чтения с фильтром ClientID равно [ClientID] показать клиенту его историю заказов, а не всех клиентов сразу.

Шаг 3. (опционально) Загрузка из Excel​

Чтобы импортировать готовую таблицу:

  1. Отметьте галочку «Загрузить из Excel».
  2. Выберите файл .xls или .xlsx (до 20 МБ).
  3. Названия полей будут взяты из первой строки таблицы.
  4. Нажмите «Сохранить».

Загрузка списка из Excel Скриншот 3. Импорт списка из файла Excel.

Шаг 4. Сохраните список​

Нажмите «Сохранить». Список появится в общем перечне. Чтобы посмотреть или отредактировать содержимое — кликните по списку.

Часть 2. Ручное редактирование данных​

Открыв список, вы попадаете в табличный редактор.

Редактор содержимого списка Скриншот 4. Редактор записей списка.

Возможности:

  • Добавить строку — кнопка + «Строку» сверху. Заполните поля и нажмите +.
  • Изменить строку — иконка «карандаш» → отредактируйте → «стрелка вниз» для сохранения.
  • Удалить строку — иконка «корзина».
  • Постраничный вывод — навигация снизу/сверху для длинных списков.

Часть 3. Работа со списком из сценария​

Все операции со списком происходят в Сценарии действий → действие «Операции с данными (Переменные, Списки)» → операция типа «Список».

Выбор операции «Список» Скриншот 5. Добавление операции типа «Список» в сценарии.

После выбора типа «Список»:

  1. В поле «Выберите список» укажите нужный список.
  2. В поле «Действие над списком» выберите одно из:
    • Добавить новую запись (addrow);
    • Чтение записей (readrow);
    • Изменить запись (editrow);
    • Удалить запись (delrow).

3.1. Добавление записи​

Выберите действие «Добавить новую запись». Конструктор покажет все поля списка — заполните нужные.

В значение можно подставить любой шаблон замен:

  • статический текст: Иван Иванов;
  • ответ из блока №1: [Answer1] (или [Ответ1], [A1]);
  • последний ответ подписчика: [Answer];
  • имя подписчика: [Name], полное имя: [FullName];
  • ID клиента: [ClientID], мессенджер: [Messenger], ID бота: [BotID];
  • текущая дата/время: [CurrentDate], [CurrentTime];
  • переменную сценария: #{phone};
  • N-й элемент массива-переменной: #{items|2}, последний: #{items|last};
  • данные сценария: [Data1], [DataN];
  • вычисление выражения: {{ #{price} * #{count} }}.

Добавление записи в список

Скриншот 6. Добавление новой строки в список из сценария.

Массив в одну запись

Если значение — массив (например, после операции «Перебор»), включите галочку «Сохранить массив в одну запись», чтобы он не разбивался построчно.

3.2. Чтение записей (отбор)​

Выберите действие «Чтение записей». Это самая частая операция: выборка строк по условию.

Условия отбора​

Каждое условие состоит из:

  • Поле — какую колонку проверяем;
  • Условие сравнения — равно, не равно, содержит, больше, меньше и т.д.;
  • Значение — с чем сравниваем (строка, переменная или поле из другого списка).

Дополнительные галочки:

  • Обратное сравнение — ищет поле в строке сравнения (а не строку в поле);
  • По основе слова — без учёта склонений и падежей;
  • Сравнить с полем — значением выступает поле этого же списка;
  • Поле из списка — значение берётся из другой таблицы.

Несколько условий объединяются через И / ИЛИ.

Условия отбора при чтении списка

Скриншот 7. Настройка условий отбора.

Сортировка и уникальность​

При чтении доступны:

  • Сортировка — по любому полю, по возрастанию или убыванию;
  • Уникальные строки — оставить только уникальные значения по выбранному полю.

Уточнить отбор (диапазон)​

Опция «Уточнить отбор» позволяет ограничить результат:

  • Старт / Конец — номера строк диапазона;
  • Последний элемент — взять последнюю запись;
  • Только последний — оставить только её.

Результат отбора​

После операции автоматически создаются переменные:

  • listlength — количество найденных записей;
  • Поле «Наличие отбора» внизу — сохраняет факт наличия отбора: 0 (пусто) или 1 (есть результат). Удобно для условий перехода.

Дальше результат обычно прогоняется через «Перебор» массива и сохраняется построчно в переменные, в строку или в другой список.

3.3. Изменение записи​

Выберите действие «Изменить запись».

  1. Задать отбор — те же условия, что при чтении (см. п. 3.2). Изменятся все строки, попавшие в отбор.
  2. Задать изменение:
    • Изменить поле — какое поле меняем;
    • Способ изменения — Установить значение (заменить) или Добавить (дописать к существующему);
    • Значение — новое содержимое (текст, переменная, поле другого списка).

Изменение записи в списке

Скриншот 8. Условия отбора и параметры изменения.

Можно добавить несколько изменений одной операцией: они применятся ко всем строкам отбора.

3.4. Удаление записи​

Выберите действие «Удалить запись». Настройте условия отбора — все попавшие строки будут удалены.

Удаление необратимо

Удалённые строки восстановить нельзя. Перед удалением рекомендуем сначала использовать чтение с теми же условиями и убедиться, что под отбор попадают только нужные строки.

Часть 4. Перебор массива записей​

После чтения списка вы получаете массив. Чтобы обработать его построчно — добавьте операцию «Перебор» (iterate) над массивом.

В переборе для каждой строки можно:

ДействиеЧто делает
Сохранить в переменнуюЗаписать поле текущей строки в локальную переменную
Сохранить в глобальную переменнуюТо же, но в глобальную
Сформировать строкуСклеить значения в одну текстовую строку (например, для отправки клиенту)
Добавить в списокПеренести строки в другой список
Изменить списокОбновить связанный список на каждой итерации

Перебор записей списка

Скриншот 9. Перебор результата отбора и сохранение значений.

Часть 5. Примеры использования​

Пример 1. База клиентов​

Задача: при первом обращении клиента сохранить его в список «Клиенты», при повторном — узнать по имени.

  1. Создайте список «Клиенты» с полем name (поля ClientID, Messenger, BotID, CreationDate добавятся автоматически).
  2. В сценарии добавьте операцию «Чтение записей» со списком «Клиенты»:
    • условие отбора: поле ClientID равно [ClientID];
    • в поле «Наличие отбора» (внизу отбора) укажите найден — туда сохранится 0 или 1.
  3. Добавьте операцию «Переменная» с проверкой выражения #{найден} = 0 → присвоение в новый блок «Добавить запись» в список (поля ClientID = [ClientID], name = [Answer1]).
  4. Если #{найден} = 1 — операцией «Перебор» прочитайте поле name в переменную клиент_имя и отправьте сообщение: С возвращением, #{клиент_имя}!.

Пример 2. Корзина товаров​

  1. Создайте список «Корзина» с полями товар, цена, количество.
  2. При нажатии «Добавить в корзину» — операция «Добавить новую запись»:
    • товар = [Answer1] (ответ из блока выбора товара);
    • цена = #{выбранная_цена} (переменная из каталога);
    • количество = [Answer2] (ответ на вопрос «Сколько штук»).
  3. При просмотре корзины — «Чтение записей» с фильтром поле ClientID равно [ClientID], далее «Перебор» с действием «Сформировать строку» и отправка клиенту: Ваш заказ: #{строка_корзины}. Сумма: #{итого}.
  4. При оплате — «Удалить запись» по фильтру ClientID равно [ClientID].

Пример 3. Импорт прайса из Excel​

  1. Создайте список «Прайс».
  2. Включите «Загрузить из Excel», выберите файл — заголовки и строки заполнятся автоматически из таблицы.
  3. В сценарии бота добавьте «Чтение записей» с фильтром на поле категория равно [Answer1] (категория, которую выбрал клиент). Через «Перебор» → «Сформировать строку» соберите найденные товары и отправьте подписчику.

Частые ошибки​

  • Список не найден в выпадающем списке сценария — проверьте, что вы в той же автоворонке, где список создан.
  • Запись добавляется без ClientID — поле заполняется автоматически только при выполнении сценария от имени клиента. В тестовых запусках может быть пусто.
  • listlength равно 0 хотя записи есть — проверьте условия отбора, регистр значений, галочки «Обратное сравнение» и «По основе слова».
  • Изменение/удаление затронуло лишние строки — слишком широкий отбор. Добавьте условие по ClientID (через шаблон [ClientID]) или другому уникальному полю.
  • Подставили #{ClientID} вместо [ClientID] — ClientID это не переменная сценария, а системный шаблон в квадратных скобках. Полный список — в разделе Шаблоны замен.

Что дальше​

  • Подставляйте значения из списка в сообщения и кнопки через переменные.
  • Используйте listlength в условиях перехода между блоками.
  • Экспортируйте список обратно в Excel через раздел «Списки» (кнопка экспорта рядом со списком).