Меню команд Telegram-бота помогает пользователю найти доступные действия без чтения длинной инструкции. Но список, который человек видит после ввода косой черты, не является системой разрешений. Скрытая команда может быть отправлена вручную, а старая команда — сохраниться в переписке после изменения роли сотрудника.
Поэтому команды проектируют в двух слоях. Первый отвечает за удобное отображение: какой список виден в нужном языке и контексте. Второй проверяет право выполнять операцию на сервере. Ошибка возникает, когда настройку меню принимают за достаточное ограничение доступа к данным и служебным действиям.
Опишите задачи каждой роли
У обычного клиента могут быть команды начала работы, справки, просмотра своих заявок и связи с оператором. У сотрудника — поиск назначенных обращений и внутренние действия. У администратора — отдельные операции управления. Набор зависит от приложения, а не от обязательного стандарта Telegram.
Для каждой команды запишите результат и возможные изменения данных. Чтение справки и закрытие обращения требуют разных проверок. Если команда принимает идентификатор заявки, сервер должен дополнительно проверить доступ к конкретной записи. Одного факта, что пользователь является оператором, не всегда достаточно для просмотра любого клиента.
Не создавайте команды для всех внутренних функций только ради полноты. Часто достаточно понятного входа в нужный раздел, а дальше пользователь выбирает действие кнопкой. Большой список ухудшает поиск и усложняет перевод. Команда должна сокращать путь к задаче, а не повторять структуру всей административной панели.
Что определяют области видимости
Bot API позволяет настраивать команды с учётом поддерживаемых областей и языка. Это помогает показывать подходящий список в разных контекстах. Перед реализацией проверьте текущие типы BotCommandScope и порядок выбора списка. Не составляйте собственную модель приоритетов по памяти из старого примера.
Область отображения может зависеть от типа чата и других документированных условий. Но бизнес-роль в вашей CRM не возникает автоматически из области Telegram. Например, сотрудник компании может быть обычным участником определённого чата. Соответствие внутренней роли и доступного меню нужно реализовать осознанно.
Сохраните конфигурацию команд в управляемом виде. Если один разработчик меняет список через API, другой вручную через интерфейс настройки, результат станет трудно воспроизводимым. Назначьте владельца конфигурации и порядок обновления, чтобы выпуск новой версии не возвращал устаревшие команды.
Серверная проверка команды
При получении команды определите пользователя, контекст и текущее действие. Затем проверьте, существует ли команда в этой версии приложения и какие права нужны для её выполнения. Если прав нет, ответ должен быть понятным, но не раскрывать закрытые сведения о чужих объектах.
Проверка выполняется при каждом важном действии, а не только при открытии меню. Сотрудник мог потерять роль после того, как открыл Telegram. Старая команда всё ещё находится у него в истории, но сервер уже должен учитывать новое состояние доступа. Иначе интерфейс обновится, а реальная возможность останется.
Для опасных операций полезно отдельное подтверждение с ясным описанием последствия. Но подтверждение также не заменяет проверку полномочий. Нажатие «да» лишь фиксирует намерение пользователя, который должен иметь право на операцию и доступ к конкретному ресурсу в текущий момент.
Условный пример: клиент и дежурный оператор
Предположим, бот сервисной команды позволяет клиенту открыть свои обращения. Дежурный оператор дополнительно видит команду рабочей очереди. Меню отличается, но сервер всё равно проверяет роль перед выдачей списка задач. Клиент, отправивший служебную команду вручную, не получает внутренние обращения.
В конце смены сотрудника переводят на другую роль. Его старое меню может обновиться не в тот момент, когда он ожидает, поэтому попытка выполнить прежнюю команду проверяется сервером. Приложение сообщает, что действие недоступно, и предлагает обычную справку либо предусмотренный путь уточнения доступа.
Когда оператор возвращается на смену, назначение роли восстанавливается в основной системе. Если конфигурация отображения требует обновления, его выполняют отдельно. Пример показывает разделение интерфейса и прав; он не означает, что Telegram автоматически ведёт расписание смен или роли вашей службы поддержки.
Перевод команд и описаний
Название команды должно быть коротким и устойчивым, а описание — понятным пользователю выбранного языка. Не переводите технические идентификаторы произвольно при каждом редактировании. Если команда изменилась, учтите старые ссылки, инструкции и сообщения, где её могли сохранить пользователи.
Проверьте fallback для языка, у которого нет отдельного списка. Пользователь должен получить рабочее меню, а не набор пустых описаний. Внутренние названия отделов и сокращения особенно плохо переносятся в другие языки: лучше объяснять действие словами, которыми человек описывает свою задачу.
Также переведите ответ на неизвестную команду и сообщение об отсутствии прав. Часто меню локализовано, а первый сбой возвращает длинный технический текст на другом языке. Это не только редакционная проблема: человек может не понять, нужно ли повторить действие, войти заново или обратиться к сотруднику.
Совместимость после обновления
Не удаляйте популярную команду без понятного перехода, если она встречается в старых инструкциях. В приложении можно предусмотреть временное сопоставление старого действия новому либо сообщение с актуальным вариантом. Конкретный срок поддержки зависит от проекта, но судьба старого ввода должна быть определена.
Если команда изменила смысл, лучше не оставлять прежнее имя для неожиданно другой операции. Пользователь может повторно отправить её из истории. Особенно осторожно меняйте действия, связанные с удалением, отправкой или изменением заявки: старый привычный ввод не должен запускать новое последствие без объяснения.
При развёртывании сверяйте серверный обработчик и опубликованное меню. Новая команда, уже показанная клиентам, не должна попадать на старый обработчик без поддержки. Обратная ситуация тоже неудобна: функция существует, но её невозможно найти из обычного интерфейса и справки.
Приёмочная проверка
Подготовьте тестовых пользователей разных ролей и языков. Проверьте меню в поддерживаемых типах чатов, затем отправьте вручную команды, которых в меню нет. Это проверяет реальный доступ, а не только внешнее отличие интерфейса. Используйте вымышленные обращения, чтобы не раскрывать настоящие данные при испытании.
Затем измените роль при открытом клиенте и повторите служебное действие. Проверьте старую команду, неизвестный ввод и недоступный ресурс. Ожидаемый ответ должен быть понятным и не превращаться в техническую ошибку. Отдельно испытайте обновление конфигурации и возврат прежней версии меню при откате.
Рабочий набор команд помогает найти нужное действие, а серверные правила определяют возможность его выполнения. Эти части проверяют вместе, но не заменяют друг другом. Тогда интерфейс остаётся удобным, а изменение меню не становится случайным способом выдать либо отозвать реальные полномочия.
Команды в групповых разговорах
В группе команда может приходить с указанием конкретного бота. Обработчик должен учитывать документированный формат и не путать обращение к другому приложению со своим действием. Также проверьте фактическую видимость сообщений при текущем privacy mode и правах бота. Разница между личным чатом и группой влияет на доступные события, но не отменяет серверную проверку пользователя.
Если служебная команда отвечает закрытыми сведениями, подумайте, допустимо ли показывать их всему групповому разговору. Возможно, результат нужно получить в личном чате по предусмотренному переходу и дополнительной проверке. Не переносите успешный личный сценарий в группу без повторной оценки получателя ответа. На приёмке используйте отдельную тестовую группу и несколько ролей, чтобы увидеть, кому виден результат и какие действия доступны участникам, которым служебное меню вообще не показывали.
Источники
Публикация списков описана в Bot API: setMyCommands, области — в BotCommandScope. Общие правила команд представлены в Telegram Bot Features.