Перейти к содержанию
9 минут чтения
Тема: Практика Telegram Bot API · Команды · Роли

Как настроить разные меню команд для клиента и менеджера в Telegram-боте

Для примера бот сервисного центра показывает клиенту команды записи и помощи, а менеджеру — ещё очередь заявок. Сделаем разные списки для личных чатов, добавим русский и английский языки и разберём снятие роли. Меню будет помогать навигации, а доступ к данным проверит сервер.

Выбираем область команд под задачу

setMyCommands задаёт список подсказок для конкретной области — scope — и языка. Сначала полезно отделить сценарий общения с клиентом от настройки Telegram: какие действия доступны каждому, какие требуют роли и что произойдёт при ручном вводе команды.

Задача

Подходящая область

Общий запасной набор

default

Все личные диалоги

all_private_chats

Личный диалог конкретного менеджера

chat с ID его личного чата

Все администраторы одной рабочей группы

chat_administrators с ID группы

Один сотрудник в определённой группе

chat_member с ID группы и user_id

Область chat_member относится к участнику группы, а не к роли сотрудника во всех разговорах с ботом. В нашем примере менеджер работает в личном чате: используем chat. Роль manager существует в базе приложения, Telegram о ней не знает. При назначении и снятии роли приложение само обновляет меню.

Пользователь должен заранее открыть диалог с ботом. Сохраните его числовой Telegram ID из проверенного входящего события. Не разрешайте сотруднику назначать себе роль передачей произвольного ID в публичной форме.

Понимаем приоритет и языковые версии

В личном диалоге Telegram ищет первый настроенный список в таком порядке: chat с языком пользователя, chat без языка, all_private_chats с языком, all_private_chats без языка, default с языком, default без языка. Найденные списки не объединяются.

Поэтому менеджерское меню должно содержать и обычные клиентские команды, если сотруднику они тоже нужны. Персональный список без языка перекрывает даже русскую версию более общей области. Если менеджеру требуется перевод, запишите его в той же персональной области.

Пустой language_code — запасной список для языков без отдельной настройки. ru и en — языки интерфейса, а не признак роли и не язык, который пользователь выбрал в вашей CRM. Если язык внутри сервиса выбирается отдельно, согласуйте это с логикой личных меню.

Настраиваем списки на PHP

Для примера используем PHP 8.3+ с cURL и прямой Telegram Bot API. Создайте setup-commands.php вне публичного каталога. BOT_TOKEN и MANAGER_CHAT_ID передайте через окружение процесса. Обычный PHP не загружает .env самостоятельно. Скрипт изменяет настройки меню одного тестового бота; на каждом сообщении запускать его не нужно.

PHP · setup-commands.php
<?php
declare(strict_types=1);

function telegram(string $method, array $params): mixed
{
    $token = getenv('BOT_TOKEN');
    if (!is_string($token) || $token === '') {
        throw new RuntimeException('Set BOT_TOKEN');
    }
    $curl = curl_init('https://api.telegram.org/bot'.$token.'/'.$method);
    curl_setopt_array($curl, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode($params, JSON_THROW_ON_ERROR),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT => 15,
    ]);
    try {
        $raw = curl_exec($curl);
        if ($raw === false) {
            throw new RuntimeException('Transport error; inspect current settings');
        }
        $status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
        $body = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
        if ($status !== 200 || !is_array($body) || ($body['ok'] ?? false) !== true) {
            throw new RuntimeException('Telegram rejected command settings');
        }
        return $body['result'];
    } finally {
        unset($curl);
    }
}

$manager = filter_var(getenv('MANAGER_CHAT_ID'), FILTER_VALIDATE_INT);
if ($manager === false || $manager <= 0) {
    throw new RuntimeException('Set a positive MANAGER_CHAT_ID');
}
$client = [
    '' => [['command' => 'start', 'description' => 'Start'],
           ['command' => 'request', 'description' => 'New request'],
           ['command' => 'help', 'description' => 'Help']],
    'ru' => [['command' => 'start', 'description' => 'Начать'],
             ['command' => 'request', 'description' => 'Создать заявку'],
             ['command' => 'help', 'description' => 'Помощь']],
];
foreach ($client as $language => $commands) {
    telegram('setMyCommands', [
        'scope' => ['type' => 'all_private_chats'],
        'language_code' => $language, 'commands' => $commands,
    ]);
    $commands[] = ['command' => 'queue',
        'description' => $language === 'ru' ? 'Очередь заявок' : 'Request queue'];
    telegram('setMyCommands', [
        'scope' => ['type' => 'chat', 'chat_id' => $manager],
        'language_code' => $language, 'commands' => $commands,
    ]);
}
// Explicit English variants also replace any older English lists.
foreach ([['type' => 'all_private_chats'],
    ['type' => 'chat', 'chat_id' => $manager]] as $scope) {
    $commands = $client[''];
    if ($scope['type'] === 'chat') {
        $commands[] = ['command' => 'queue', 'description' => 'Request queue'];
    }
    telegram('setMyCommands', [
        'scope' => $scope, 'language_code' => 'en', 'commands' => $commands,
    ]);
}
echo "Command lists updated\n";
Bash · Запуск после настройки окружения
php setup-commands.php

Имена команд записываются без /. Для каждого списка указывайте полный набор: setMyCommands заменяет его целиком. Допустимы до 100 команд; имя — от 1 до 32 строчных латинских букв, цифр и подчёркиваний. Наши списки намеренно короткие, чтобы меню оставалось понятным.

Успех всех вызовов означает сохранение этих комбинаций scope/language_code. Сценарий из нескольких запросов не атомарен: если связь оборвалась посередине, часть списков уже могла обновиться. Сверьте фактические значения и повторно примените желаемую конфигурацию. Не выводите в журнал URL с токеном.

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

Сначала отзовите роль менеджера в своей базе. Это сразу закроет доступ к очереди. Затем удалите персональные меню, чтобы Telegram вернулся к общему набору. Следующий фрагмент использует функцию telegram из setup-commands.php; выполняйте его вместо блока установки после получения ID сотрудника из своей базы.

PHP · Снятие персональных списков
foreach (['', 'ru', 'en'] as $language) {
    telegram('deleteMyCommands', [
        'scope' => ['type' => 'chat', 'chat_id' => $manager],
        'language_code' => $language,
    ]);
}

Удаляются только перечисленные комбинации. Если раньше были de или другие языки, их тоже нужно удалить. Telegram не предоставляет здесь метод перечисления всех когда-либо заданных областей: храните собственный реестр управляемых пар scope/language_code.

При переходе со старого default-меню на all_private_chats удалите или замените ненужные default-списки, если они могли содержать служебные команды для других чатов. Не стирайте все области без разбора: у рабочей группы может быть отдельный согласованный набор.

Проверяем полномочия при выполнении команды

Клиент может вручную отправить /queue, даже если её нет в меню. В update нет доказательства того, из какой области была выбрана команда. Полномочия проверяются по ID отправителя и текущей роли в базе на каждое защищённое действие, включая callback-кнопки и открытие конкретной заявки.

Для примера такая функция защищает команду в личном чате. Предполагается существующая таблица staff с telegram_user_id, active и role. Это образец запроса к вашей модели ролей, а не требование создавать отдельную таблицу именно с таким именем.

PHP · Проверка доступа к очереди
<?php
declare(strict_types=1);

function canViewQueue(PDO $db, array $message): bool
{
    if (($message['chat']['type'] ?? null) !== 'private'
        || !is_int($message['from']['id'] ?? null)) {
        return false;
    }
    $query = $db->prepare('SELECT 1 FROM staff
        WHERE telegram_user_id = ? AND active = 1 AND role = ? LIMIT 1');
    $query->execute([$message['from']['id'], 'manager']);

    return $query->fetchColumn() !== false;
}

Если функция вернула false, не загружайте и не отправляйте список заявок. Ошибка БД тоже должна останавливать действие, а не давать запасной доступ. Для рабочих групп отдельно определите допустимые chat_id; роль сотрудника не означает, что персональные данные можно показать в любой группе.

Проверяем сохранённые списки и интерфейс

getMyCommands читает конкретную пару области и языка. Он не вычисляет итоговое меню произвольного пользователя по всем fallback-правилам. Для нашего менеджера проверьте ru, en и запасной список, затем аналогичные общие настройки.

JSON · Параметры getMyCommands для менеджера
{
  "scope": {"type": "chat", "chat_id": 123456789},
  "language_code": "ru"
}

В ответе должны быть start, request, help и queue. После снятия роли запрос к удалённой персональной паре вернёт пустой список; общий набор продолжит существовать в all_private_chats. Проверьте итоговое отображение в двух аккаунтах: клиент и менеджер, с русским и английским интерфейсом. Если Telegram показывает старое меню, переоткройте диалог после сверки API; клиентское отображение может обновиться не мгновенно.

Если вместо списка команд кнопка меню запускает Mini App, проверьте setChatMenuButton/getChatMenuButton: тип web_app управляется отдельно. Сохранённые setMyCommands при этом не исчезают. Для возвращения списка команд задайте menu_button с type=commands в нужном личном чате либо в настройке по умолчанию.

Отдельно вручную отправьте /queue с клиентского аккаунта и со снятой ролью менеджера. Оба запроса должны быть отклонены. Это важнее того, скрылась ли подсказка визуально.

Если методы вызываются через BotGate

Параметры setMyCommands, deleteMyCommands и getMyCommands сохраняются. Используйте настроенный API endpoint BotGate с авторизацией по API-ключу согласно документации, а не добавляйте ключ или Telegram-токен в браузер. Решение о роли остаётся в приложении: транспорт не назначает сотрудникам доступ к заявкам.

Официальная документация