# Массивы: создание, формат и использование

Source: https://docs.botman.pro/a/192-massivy-sozdanie-format-i-ispolzovanie

Массив — это поле, в котором хранится не одно значение, а список значений одного типа. Например, в массиве можно хранить товары в корзине, выбранные города, даты занятий или каталог объектов с названием и ценой.

Простой массив товаров выглядит так:

`["Онлайн-курс", "Консультация", "Чек-лист"]`

В этом массиве три элемента. Порядок важен: «Онлайн-курс» — первый элемент, «Консультация» — второй.

## Пользовательский или глобальный массив

В BotMan можно создать массив двух видов.

| Вид массива | Где хранится значение | Когда использовать |
| --- | --- | --- |
| Пользовательское поле | Отдельно у каждого подписчика | Корзина, избранное, ответы конкретного человека, выбранные даты |
| Глобальная переменная | Одно общее значение для всех подписчиков | Общий список городов, каталог, расписание, разрешённые значения |

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

> Не храните персональные данные подписчика в глобальном массиве: его значение общее.

## Какие элементы можно хранить

При создании массива выберите тип его элементов. Все элементы одного массива должны соответствовать выбранному типу.

| Тип элементов | Пример |
| --- | --- |
| Текст | `["Москва", "Казань", "Сочи"]` |
| Число | `[100, 250, 399.9]` |
| Дата | `["2026-09-01", "2026-09-15"]` |
| Дата и время | `["2026-09-01T09:30:00Z", "2026-09-01T12:00:00Z"]` |
| Объект | `[{"name": "Онлайн-курс", "price": 2990}]` |

Тип элементов задаётся при создании поля. Если позже понадобится другой тип, создайте новый массив и перенесите в него данные.

## Как создать пользовательский массив

1. Откройте «Настройки» → «Пользовательские поля».
2. Нажмите «Добавить поле».
3. Укажите понятное название — например, «Товары в корзине».
4. В поле «Тип поля» выберите «Массив».
5. Выберите тип элементов массива.
6. При необходимости добавьте описание и сохраните поле.

![Создание пользовательского поля типа «Массив»](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/0c4b28f3b23f6844b80f3014b5f0649959cfee6926802578f0e4790766214cab.png)

*Создание пользовательского поля типа «Массив»*

У нового пользовательского поля ещё нет значения. Заполнить массив можно в сценарии с помощью шага «Действия».

## Как создать глобальный массив

1. Откройте «Настройки» → «Глобальные переменные».
2. Нажмите «Добавить переменную».
3. Укажите название — например, «Доступные города».
4. Выберите тип «Массив» и тип элементов.
5. Введите начальное значение в формате JSON, например `["Москва", "Казань", "Сочи"]`.
6. Сохраните переменную.

![Создание глобальной переменной типа «Массив»](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/58a54e5f57ba6b4a9b17e059afb98acce42a7b90b21f10b6f17773c188f6f255.png)

*Создание глобальной переменной типа «Массив»*

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

## Формат JSON без ошибок

Значение массива записывается в формате JSON.

- Весь список находится в квадратных скобках: `[]`.
- Элементы разделяются запятыми.
- Текст, дата и дата со временем заключаются в двойные кавычки.
- Числа записываются без кавычек.
- Объект находится в фигурных скобках и содержит пары «ключ — значение».
- Пустой массив записывается как `[]`.

Правильно:

`["Москва", "Казань"]`

Неправильно:

`['Москва', 'Казань']`

В JSON используются двойные кавычки, а не одинарные.

## Как изменить массив

В шаге «Действия» доступны пять операций:

- установить весь массив;
- добавить один элемент в конец;
- удалить элемент по индексу;
- удалить первое совпадение по значению;
- очистить поле.

Подробная инструкция и примеры для каждого типа находятся в статье [«Действия с массивами»](https://docs.botman.pro/a/245-deystviya-s-massivami).

## Как вывести массив в сообщении

Добавьте массив в текст через меню переменных и функций в редакторе сообщения.

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

`1. Онлайн-курс`\
`2. Консультация`\
`3. Чек-лист`

Для массива объектов BotMan использует поля `name`, `quantity` и `price`, если они есть. Например, объект

`{"name": "Онлайн-курс", "quantity": 2, "price": 2990}`

будет показан так:

`1. Онлайн-курс x2 - 2990`

Глобальный массив при прямой подстановке выводится компактным списком, например `[Москва, Казань, Сочи]`. Перед публикацией сценария воспользуйтесь кнопкой «Тестировать» и проверьте, подходит ли такой вид для вашего сообщения.

## Как проверить массив

В шаге «Условие» массив можно проверить напрямую:

- пустой он или нет;
- содержит ли значение;
- равно ли количество элементов заданному числу;
- больше или меньше ли количество элементов заданного числа.

Для обычной развилки отдельное числовое поле не требуется. Например, чтобы продолжить сценарий только при наличии товаров, выберите «Товары в корзине» → «Не пустой».

Подробнее: [«Проверка массива»](https://docs.botman.pro/a/182-proverka-massiva).

## Как получить количество элементов

Если количество нужно сохранить, показать пользователю, использовать повторно или включить в расчёт, примените функцию «Количество элементов массива».

1. Создайте числовое поле — например, «Количество товаров».
2. В шаге «Действия» выберите это поле.
3. Выберите «Математические операции со значением».
4. Откройте меню переменных и функций.
5. В разделе «Системные функции» выберите «Количество элементов массива».
6. Выберите пользовательский или глобальный массив и сохраните действие.

![Функция «Количество элементов массива»](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/ad55463590443cc316a0c6cfd832c03c2ff7d717ab03c1dfafa91a26ad7dbd8f.png)

*Функция «Количество элементов массива»*

Функция `array_length` возвращает число. Для пустого массива или массива без значения результат равен `0`.

## Что читать дальше

- [Действия с массивами](https://docs.botman.pro/a/245-deystviya-s-massivami) — добавить, удалить, заменить или очистить элементы.
- [Проверка массива](https://docs.botman.pro/a/182-proverka-massiva) — построить развилку по содержимому и количеству элементов.
- [Пользовательские поля](https://docs.botman.pro/a/180-polzovatelskie-polya) — общие правила работы с данными подписчика.
- [Глобальные переменные](https://docs.botman.pro/a/183-globalnye-peremennye) — общие значения для сценариев аккаунта.