Выбираем область команд под задачу
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
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";
php setup-commands.php
Имена команд записываются без /. Для каждого списка указывайте полный набор: setMyCommands заменяет его целиком. Допустимы до 100 команд; имя — от 1 до 32 строчных латинских букв, цифр и подчёркиваний. Наши списки намеренно короткие, чтобы меню оставалось понятным.
Успех всех вызовов означает сохранение этих комбинаций scope/language_code. Сценарий из нескольких запросов не атомарен: если связь оборвалась посередине, часть списков уже могла обновиться. Сверьте фактические значения и повторно примените желаемую конфигурацию. Не выводите в журнал URL с токеном.
Убираем старые настройки при смене роли
Сначала отзовите роль менеджера в своей базе. Это сразу закроет доступ к очереди. Затем удалите персональные меню, чтобы Telegram вернулся к общему набору. Следующий фрагмент использует функцию telegram из setup-commands.php; выполняйте его вместо блока установки после получения ID сотрудника из своей базы.
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
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 и запасной список, затем аналогичные общие настройки.
{
"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-токен в браузер. Решение о роли остаётся в приложении: транспорт не назначает сотрудникам доступ к заявкам.
Официальная документация
Команды и области — назначение меню и необходимость проверки доступа.
Приоритет списков — выбор области и языка.
setMyCommands, deleteMyCommands, getMyCommands — запись, удаление и чтение.