Редактор меню

Обзор

Редактор меню позволяет администраторам полностью настраивать структуру навигации Cabinet: расположение кнопок, количество кнопок в ряду, стили, иконки, локализованные подписи и добавление кастомных URL-кнопок. Все изменения применяются мгновенно без перезапуска.

Возможности

Drag-and-drop сортировка рядов
Перемещение кнопок внутри ряда (вверх/вниз)
Настройка 1–3 кнопок на ряд
8 встроенных секций (home, subscription, balance, referral, support, info, admin, language)
Кастомные URL-кнопки с выбором режима открытия
Цветовые стили: primary, success, danger, default
Кастомные emoji-иконки (Telegram Custom Emoji ID)
Мультиязычные подписи (ru, en, ua, zh, fa)
Включение/отключение отдельных кнопок
Сброс к настройкам по умолчанию

Для работы редактора меню необходимо:

CABINET_ENABLED=true
MENU_LAYOUT_ENABLED=true в настройках бота
RBAC-разрешение settings:edit для редактирования, settings:read для просмотра

Включение

MENU_LAYOUT_ENABLED=true

При включении структура меню управляется через редактор, а не задаётся статически в коде. Подробнее о режимах меню: Интерфейс и брендирование → Динамическое меню.

Использование

Открытие редактора

Cabinet → Админ-панель → Настройки → вкладка Редактор меню

Работа с рядами

Перетаскивание

Захватите ряд за ручку и перетащите для изменения порядка

Кнопок в ряду

Выберите 1, 2 или 3 кнопки на ряд через селектор в заголовке

Удаление ряда

Ряды, содержащие только кастомные кнопки, можно удалить целиком

Настройка кнопки

Нажмите на кнопку для раскрытия настроек:

Параметр	Описание	Доступно для
Стиль	Цвет кнопки: primary (синий), success (зелёный), danger (красный), default	Все кнопки
Emoji ID	Telegram Custom Emoji ID для иконки	Все кнопки
Вкл/Выкл	Показывать или скрыть кнопку	Все кнопки
Подписи	Локализованные названия (ru, en, ua, zh, fa), макс. 100 символов	Все кнопки
URL	Ссылка для перехода (http:// или https://)	Только кастомные
Режим открытия	`external` (браузер) или `webapp` (Telegram WebApp)	Только кастомные

Встроенные кнопки нельзя удалить — только отключить или переместить. Кастомные кнопки можно удалить через иконку корзины.

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

В нужном ряду нажмите Добавить кнопку
Выберите из списка:
- Встроенную секцию — доступны только ещё не использованные
- URL-кнопку — создаёт кастомную кнопку с настраиваемой ссылкой

Сохранение и сброс

Сохранить — применяет все изменения атомарно (один запрос)
Отменить — возвращает к последнему сохранённому состоянию
Сбросить — восстанавливает расположение по умолчанию (с подтверждением)

Кастомные URL-кнопки

Кастомные кнопки позволяют добавлять внешние ссылки в меню Cabinet.

Режим открытия (`open_in`)

Значение	Описание	Требования
`external`	Открывает URL в браузере	http:// или https://
`webapp`	Открывает URL как Telegram WebApp внутри бота	Только https://

При выборе webapp URL обязательно должен начинаться с https://. HTTP-ссылки будут отклонены при сохранении.

Примеры использования

Ссылка на сайт проекта (external)
Ссылка на FAQ или документацию (external)
Встроенная веб-форма обратной связи (webapp)
Внешний сервис мониторинга (webapp)

Расположение по умолчанию

Ряд	Кнопки	Кнопок в ряду
1	home	1
2	subscription, balance	2
3	referral, support	2
4	info, language	2
5	admin	1

Встроенные секции:

ID	Описание
`home`	Главная страница
`subscription`	Управление подпиской
`balance`	Баланс и пополнение
`referral`	Реферальная программа
`support`	Тикеты поддержки
`info`	Информация (FAQ, правила)
`admin`	Админ-панель (видна только администраторам)
`language`	Выбор языка

Ограничения

Параметр	Лимит
Максимум рядов	20
Кнопок в ряду	1–3
Длина подписи	100 символов
Длина Emoji ID	100 символов
URL кнопки	http:// или https://
ID кастомной кнопки	Должен начинаться с `custom_`

API эндпоинты

Возвращает текущую конфигурацию меню (объединяет layout и стили). Ответ:

{
  "rows": [
    {
      "id": "row_1",
      "max_per_row": 1,
      "buttons": [
        {
          "id": "home",
          "type": "builtin",
          "style": "primary",
          "icon_custom_emoji_id": "5368324343330516923",
          "enabled": true,
          "labels": {"ru": "Главная", "en": "Home"},
          "url": null,
          "open_in": "external"
        }
      ]
    },
    {
      "id": "row_custom_1",
      "max_per_row": 2,
      "buttons": [
        {
          "id": "custom_12345",
          "type": "custom",
          "style": "success",
          "icon_custom_emoji_id": "",
          "enabled": true,
          "labels": {"ru": "Наш сайт", "en": "Our Website"},
          "url": "https://example.com",
          "open_in": "external"
        }
      ]
    }
  ]
}

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

CABINET_MENU_LAYOUT — расположение рядов и кастомные кнопки
CABINET_BUTTON_STYLES — стили встроенных секций

Сброс к расположению по умолчанию. Требует подтверждения на фронтенде.

Кэширование

Конфигурация меню кэшируется в памяти для быстрого доступа:

Загрузка — при старте бота (load_menu_layout_cache(), load_button_styles_cache())
Обновление — автоматически после каждого сохранения через API
Формат — deep copy из кэша для защиты от мутаций

Если кэш не загружен, используются значения по умолчанию.

Устранение проблем

Вкладка редактора не отображается

MENU_LAYOUT_ENABLED=true?
У пользователя есть RBAC-разрешение settings:read?
Пользователь является администратором (ADMIN_IDS или ADMIN_EMAILS)?

Кнопка webapp не работает

URL начинается с https://? HTTP не поддерживается для webapp-режима
Сайт по URL доступен и не блокирует iframe?
Telegram WebApp поддерживает URL? (некоторые домены могут быть заблокированы)

Изменения не применяются

Нажали Сохранить после внесения изменений?
Проверьте логи бота на ошибки валидации:
docker logs <bot_container> 2>&1 | grep -i "menu_layout"
Попробуйте Сбросить и настроить заново

Редактор меню

Обзор

Возможности

Включение

Использование

Открытие редактора

Работа с рядами

Перетаскивание

Кнопок в ряду

Удаление ряда

Настройка кнопки

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

Сохранение и сброс

Кастомные URL-кнопки

Режим открытия (`open_in`)

Примеры использования

Расположение по умолчанию

Ограничения

API эндпоинты

GET /cabinet/admin/menu-layout

PUT /cabinet/admin/menu-layout

POST /cabinet/admin/menu-layout/reset

Кэширование

Устранение проблем

Вкладка редактора не отображается

Кнопка webapp не работает

Изменения не применяются

​Обзор

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

​Включение

​Использование

​Открытие редактора

​Работа с рядами

Перетаскивание

Кнопок в ряду

Удаление ряда

​Настройка кнопки

​Добавление кнопки

​Сохранение и сброс

​Кастомные URL-кнопки

​Режим открытия (open_in)

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

​Расположение по умолчанию

​Ограничения

​API эндпоинты

​GET /cabinet/admin/menu-layout

​PUT /cabinet/admin/menu-layout

​POST /cabinet/admin/menu-layout/reset

​Кэширование

​Устранение проблем

​Вкладка редактора не отображается

​Кнопка webapp не работает

​Изменения не применяются

Обзор

Возможности

Включение

Использование

Открытие редактора

Работа с рядами

Настройка кнопки

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

Сохранение и сброс

Кастомные URL-кнопки

Режим открытия (`open_in`)

Примеры использования

Расположение по умолчанию

Ограничения

API эндпоинты

GET /cabinet/admin/menu-layout

PUT /cabinet/admin/menu-layout

POST /cabinet/admin/menu-layout/reset

Кэширование

Устранение проблем

Вкладка редактора не отображается

Кнопка webapp не работает

Изменения не применяются