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

Что такое команды для Telegram бота и зачем они нужны

В экосистеме Telegram боты автоматизируют рутину, развлекают, предоставляют данные и управляют устройствами. Основной инструмент взаимодействия пользователя с ботом — команды для Telegram бота. Команда — это текст, начинающийся со слеша (/), который бот распознаёт и обрабатывает по заданной логике. Например, /start — стандартная команда для инициализации диалога, /help — вызов справки. Однако возможности гораздо шире: можно создавать собственные команды с разными уровнями доступа, параметрами и даже областью действия (scope). Эта статья проведёт вас от регистрации первого бота до развёртывания корпоративной системы команд.

Прежде чем погружаться в детали, важно понять, как Telegram обрабатывает команды. Когда пользователь отправляет сообщение, начинающееся с /, клиент Telegram (мобильный, десктопный или веб) автоматически подсвечивает его как команду и может подсказывать варианты, если бот их зарегистрировал. Само сообщение отправляется боту как обычный текст — разбор происходит на стороне сервера бота. Telegram API предоставляет несколько способов зарегистрировать список команд: через BotFather (для всех пользователей) или программно через метод setMyCommands (с возможностью указать язык, тип чата и даже конкретных пользователей).

Создание бота и первичная настройка команд через BotFather

Первый шаг к созданию собственных команд — получить бота и зарегистрировать его команды. Для этого используется официальный бот Telegram @BotFather. Следуйте шагам:

1. Начните диалог с @BotFather и отправьте команду /newbot. Следуйте инструкциям, чтобы задать имя и username (заканчивается на bot). После успешного создания вы получите токен бота — ключ доступа к HTTP API.
2. Чтобы добавить команды, отправьте /setcommands и выберите своего бота из списка. Откроется редактор, где можно ввести список команд в формате:
   команда1 - Краткое описание команда2 - Ещё описание
   Каждая команда — строка, команда без слеша, затем пробел, дефис, пробел и описание (не более 256 символов). Максимум 100 команд.
3. Отправьте список — BotFather подтвердит сохранение. Теперь при вводе / в чате с ботом пользователи увидят подсказки.

После настройки команд не забудьте запустить процесс, который будет принимать обновления. Самый простой способ — написать скрипт на Python с библиотекой python-telegram-bot (версия 20.x) или любой другой. Подключение к API происходит через токен. Пример минимального кода для обработки команд /start и /help:

from telegram.ext import Application, CommandHandler

async def start(update, context):
    await update.message.reply_text('Привет! Я бот.')

async def help_command(update, context):
    await update.message.reply_text('Список доступных команд...')

def main():
    app = Application.builder().token('YOUR_TOKEN').build()
    app.add_handler(CommandHandler('start', start))
    app.add_handler(CommandHandler('help', help_command))
    app.run_polling()

if __name__ == '__main__':
    main()

Обратите внимание: имя команды в CommandHandler указывается без слеша. Если команда не зарегистрирована через BotFather, она всё равно может обрабатываться программно, но не будет отображаться в подсказках. Рекомендуется всегда синхронизировать список зарегистрированных команд с реальными обработчиками.

Программное управление командами: setMyCommands и scope

Начиная с Bot API 5.3 (апрель 2021), разработчики получили возможность динамически назначать команды с помощью метода setMyCommands. Это открывает гибкость, недоступную через BotFather: можно задать разные наборы команд для разных языков, типов чатов (private, group, supergroup, channel) или даже для конкретных пользователей. Метод принимает массив объектов BotCommand и опциональный объект BotCommandScope. Пример запроса через curl:

curl -X POST "https://api.telegram.org/botYOUR_TOKEN/setMyCommands" \
-H "Content-Type: application/json" \
-d '{
  "commands": [
    {"command": "start", "description": "Запустить бота"},
    {"command": "status", "description": "Текущее состояние"}
  ],
  "scope": {"type": "all_private_chats"}
}'

Scope определяет, где эти команды будут видны. Возможные типы: default (все чаты), all_private_chats, all_group_chats, all_chat_administrators, chat (конкретный чат), chat_administrators, chat_member. Это особенно полезно для корпоративных ботов, где рядовым сотрудникам доступен один набор команд, а администраторам — расширенный. Также можно локализовать описания команд — для этого поле language_code принимает двухбуквенный код языка (например, ru).

Когда не стоит использовать setMyCommands? Если бот небольшой и команды статичны, проще и надёжнее задать их через BotFather — не нужно писать лишний код и вспоминать о вызове API. Программное управление оправдано, когда команды зависят от роли пользователя, языка или динамически меняются (например, сезонные промо-команды).

Типы команд и их особенности

Команды в Telegram можно разделить на несколько категорий по способу их использования и адресации:

• Стандартные слэш-команды (например, /weather, /subscribe) — самый распространённый тип. Они могут быть с параметрами, переданными в том же сообщении после пробела, или требовать отдельного ввода.
• Inline-команды — начинаются с /, но обрабатываются в строке набора, когда пользователь вводит @username_бота и команду. Позволяют выбрать вариант из всплывающего списка (InlineQuery). Фактически это не команды бота в классическом смысле, но их тоже можно рассматривать как команды для быстрого доступа к функциям бота.
• Команды с аргументами — например, /settimer 30. Бот разбирает текст после команды (update.message.text) и извлекает аргументы. Важно предусмотреть проверку наличия аргументов, их валидность и безопасность.
• Команды-кнопки — хотя технически это не команды, но часто через кнопки (InlineKeyboardButton) с callback_data реализуется логика, аналогичная командам. Разница в способе вызова: пользователь нажимает кнопку, а не пишет текст.

Обработка аргументов — одна из задач, где новички часто допускают ошибки. Например, команда /subscribe channel_name — если пользователь отправит только /subscribe, бот должен корректно сообщить об ошибке, а не падать. Хорошей практикой является разделение на «чистую» команду (без аргументов) и вариант с аргументами через один и тот же CommandHandler, проверяя context.args.

Работа с аргументами: практический пример

Предположим, бот для напоминаний. Команда /remind 10 позвонить должна установить таймер на 10 минут с текстом «позвонить». Реализация на Python с использованием python-telegram-bot:

async def remind(update, context):
    if not context.args:
        await update.message.reply_text('Использование: /remind <минуты> <текст>')
        return
    try:
        minutes = int(context.args[0])
    except ValueError:
        await update.message.reply_text('Первый аргумент должен быть числом (минуты).')
        return
    text = ' '.join(context.args[1:])
    # Здесь планировщик задач
    await update.message.reply_text(f'Напоминание установлено через {minutes} мин.')

Обратите внимание: команда /remind зарегистрирована без описания аргументов. В описании в BotFather можно написать «Установить напоминание: /remind {минуты} {текст}», но самого разбора аргументов это не упрощает — вся логика на стороне бота.

Обработка команд в группах и супергруппах

Когда бот работает в групповом чате, важно понимать, кто может вызывать команды. Telegram автоматически предоставляет контекст Chat и ChatMember. В группах можно ограничить выполнение некоторых команд только администраторам (т.е. пользователям со статусом administrator или creator). Это делается проверкой прав в обработчике:

from telegram import ChatMember

async def ban(update, context):
    user_status = await update.effective_chat.get_member(update.effective_user.id)
    if user_status.status not in (ChatMember.ADMINISTRATOR, ChatMember.CREATOR):
        await update.message.reply_text('Только администраторы могут использовать /ban.')
        return
    # логика бана

Также можно задать scope команд так, чтобы определённые команды были видны только в группах (all_group_chats) или только в личных сообщениях (all_private_chats). Комбинируя scope и программную проверку прав, выстроите гибкую систему доступа.

Эмпирическое наблюдение: в больших группах (1000+ участников) частый вызов команд, которые анализируют всю историю или делают запросы к внешним API, может замедлить бота. Рекомендуется использовать умеренный кеш и не блокировать event loop.

Интеграция команд с внешними сервисами и автоматизация

Команды бота — это лишь точка входа. Часто за ними стоит интеграция с базами данных, CRM, платежными системами и другими API. Например, команда /track 12345 может возвращать статус доставки из внешнего сервиса логистики. Реализация включает отправку HTTP-запроса к API, обработку ответа и форматирование ответа пользователю. Важно помнить об ограничениях Telegram Bot API: отправлять сообщения можно не быстрее 30 сообщений в секунду (для обычных ботов — около 20-30 сообщений/сек, точное ограничение может меняться). При массовых рассылках лучше использовать очередь.

Пример использования aiomysql для получения данных по команде /profile:

import aiomysql

async def profile(update, context):
    user_id = update.effective_user.id
    pool = context.bot_data.get('db_pool')
    async with pool.acquire() as conn:
        async with conn.cursor() as cur:
            await cur.execute("SELECT name, points FROM users WHERE telegram_id=%s", (user_id,))
            row = await cur.fetchone()
    if row:
        await update.message.reply_text(f"Профиль: {row[0]}, баллы: {row[1]}")
    else:
        await update.message.reply_text("Профиль не найден.")

Для асинхронных вызовов используйте non-blocking библиотеки. Бот на aiohttp или FastAPI отлично сочетается с Bot API.

Ошибки и устранение неполадок

При разработке команд для Telegram бота можно столкнуться с типичными проблемами:

• Команда не отображается в подсказках — вероятно, она не зарегистрирована через BotFather или setMyCommands, или задан scope, исключающий текущий чат. Проверьте список команд с помощью getMyCommands (POST запрос к боту).
• Бот не реагирует на команду — проверьте, что обработчик команды зарегистрирован (CommandHandler('command', handler)). Убедитесь, что команда не перехватывается другим обработчиком (порядок добавления важен). Если бот использует webhook, проверьте, что веб-сервер принимает POST-запросы от Telegram.
• Команда срабатывает в группе, но не в личке или наоборот — посмотрите scope, заданный через setMyCommands. Если scope указан all_group_chats, команда не появится в private чате. Это может ввести пользователей в заблуждение, поэтому рекомендуется задавать базовые команды (например, /start, /help) без scope или с default.
• Аргументы не передаются — проверьте, что команда и аргументы разделены пробелом. В Bot API аргументы — это текст после команды (включая пробелы). Используйте context.args (список) и context.args_text (строка) в зависимости от версии библиотеки.

Лучшие практики для команд бота

Опираясь на многолетний опыт сообщества, можно выделить несколько рекомендаций, которые сделают взаимодействие с ботами удобным и безопасным:

• Минимализм в подсказках — не регистрируйте более 5-7 команд на один scope, если это не критично. Слишком длинный список запутывает пользователя.
• Единообразие описаний — используйте одинаковый стиль: глагол в повелительном наклонении, краткое объяснение результата. Плохо: «/config – настройка». Хорошо: «/config – Открыть настройки профиля».
• Безопасность — никогда не доверяйте аргументам команды. Проверяйте типы, экранируйте SQL-запросы (или используйте ORM), не выполняйте системные команды на основе пользовательского ввода.
• Логирование — записывайте вызов команд (без чувствительных данных) для отладки и анализа.
• Обработка ошибок — возвращайте понятное сообщение при неправильном вводе. Например, «Команда не распознана. Используйте /help для списка команд.»

Следуя этим простым правилам, вы обеспечите удобство и безопасность вашего бота.

Когда не стоит создавать собственные команды

Несмотря на полезность, есть сценарии, когда лучше обойтись без команд или использовать альтернативные механики:

• Если логика реализуется на кнопках — пользователям часто удобнее нажать кнопку, чем вводить текст с телефона.
• Для частых обновлений состояния (например, курс валют) лучше настроить регулярную рассылку или подписку, а не команду, которую нужно вводить каждый раз.
• Если в группе много участников, которые могут случайно или намеренно злоупотреблять командами (например, массовый вызов /weather), стоит установить ограничение по времени между вызовами (throttling) или исключить команду из общего доступа.
• При интеграции с платными сервисами — не делайте команду, которая запускает платные операции без подтверждения. Используйте кнопки с Confirm/Cancel.

Развёртывание бота в команде и корпоративной среде

Для разработки вдвоём или в компании понадобится система контроля версий, тестовый бот (второй токен) и автоматическое обновление команд. Используйте переменные окружения для токена, чтобы не хранить его в коде. Для управления конфигурацией команд можно хранить их в JSON-файле и загружать при старте, вызывая setMyCommands. Пример конфигурации:

[
  {
    "command": "profile",
    "description": "Показать профиль",
    "scope": {"type": "all_private_chats"}
  },
  {
    "command": "setrole",
    "description": "Назначить роль (только админ)",
    "scope": {"type": "chat_administrators"}
  }
]

Такой подход упрощает ревью изменений и позволяет разным членам команды согласовывать команды без ручного вмешательства в BotFather.

Часто задаваемые вопросы

Можно ли удалить команду бота через BotFather?

Да, в BotFather используйте /setcommands, выберите бота и очистите весь список, сохранив пустой. Альтернативно через API используйте setMyCommands с пустым массивом commands.

Почему моя команда не видна в группе, хотя она зарегистрирована?

Проверьте scope: если команда задана с scope all_private_chats, она не появится в группах. Используйте setMyCommands с scope default или all_group_chats. Также убедитесь, что бот имеет достаточные права (не ограничен администратором группы).

Как передать параметры в команду, если пользователь использует мобильное приложение?

Параметры передаются так же, как и с десктопа: после команды через пробел. Например, «/search кот» — бот получит аргумент «кот». Рекомендуется в описании команды указывать формат, например «/search <запрос> — Поиск по базе».

Есть ли ограничение по длине команды в Telegram?

Сама команда (без слеша) может быть до 32 символов. Описание — до 256 символов. Количество команд — до 100 на один scope. Telegram не ограничивает длину текста после команды.

Можно ли сделать команду, которая реагирует на сообщения без слеша?

Технически да, вы можете реализовать обработку любого текста как команды (через MessageHandler с фильтром TEXT). Однако Telegram не покажет такую «псевдокоманду» в меню подсказок. Пользователи должны знать её вручную. Обычно такие решения используют для ботов, работающих как «ChatGPT», где любое сообщение считается запросом.

Заключение

Команды — фундамент взаимодействия с Telegram ботами. Они просты в создании, но требуют продуманного подхода к именованию, описанию и обработке. Используйте BotFather для быстрого прототипирования, а setMyCommands — для гибкого распределения по ролям и локалям. Не забывайте про безопасность: проверяйте аргументы, ограничивайте доступ к административным командам и логируйте вызовы. Следуя описанным практикам, вы создадите бота, которым будет удобно пользоваться и который легко поддерживать.

Если вы только начинаете, возьмите за основу шаблон с обработчиком /start и /help, постепенно добавляя новые. А когда наберёте опыт, переходите к динамическим командам с scope — это даст профессиональный уровень управления.