Skip to main content

​
Обзор

Редактор меню позволяет администраторам полностью настраивать структуру навигации 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)
  • Включение/отключение отдельных кнопок
  • Сброс к настройкам по умолчанию
Для работы редактора меню необходимо:
  1. CABINET_ENABLED=true
  2. MENU_LAYOUT_ENABLED=true в настройках бота
  3. RBAC-разрешение settings:edit для редактирования, settings:read для просмотра

​
Включение

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

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

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

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

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

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

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

Кнопок в ряду

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

РядКнопкиКнопок в ряду
1home1
2subscription, balance2
3referral, support2
4info, language2
5admin1
Встроенные секции:
IDОписание
homeГлавная страница
subscriptionУправление подпиской
balanceБаланс и пополнение
referralРеферальная программа
supportТикеты поддержки
infoИнформация (FAQ, правила)
adminАдмин-панель (видна только администраторам)
languageВыбор языка

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

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

​
API эндпоинты

​
GET /cabinet/admin/menu-layout

Возвращает текущую конфигурацию меню (объединяет 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"
        }
      ]
    }
  ]
}

​
PUT /cabinet/admin/menu-layout

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

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

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

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

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

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

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

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

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

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

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

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