Возможности Telegram-ботов — справочник по Bot Features

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

Что описывают Bot Features и Bot API

Bot Features — раздел официальной документации Telegram с обзором пользовательских интерфейсов и режимов работы ботов. Полный перечень методов, объектов, полей и ограничений находится в Bot API Reference.

Практическая разница проста: Bot Features помогает выбрать подходящую механику, а Bot API показывает, какими методами и объектами её реализовать.

Карта возможностей Telegram-ботов

Команды, scopes и кнопка меню

Команда — это конструкция вида /keyword, которую Telegram подсвечивает в сообщениях и предлагает после ввода /.

Основные правила:

• команда начинается с / и содержит до 32 символов;
• допустимы латинские буквы, цифры и подчёркивания;
• для читаемости рекомендуется нижний регистр;
• конкретная команда вроде /newlocation обычно понятнее общей /new с дополнительным параметром.

Telegram просит разработчиков поддерживать глобальные команды /start, /help и, если у бота есть настройки, /settings.

Через scopes можно показывать разные списки команд администраторам групп, отдельным чатам и пользователям с разными значениями language_code. Кнопка меню рядом с полем ввода открывает команды с описаниями либо запускает Mini App.

Клавиатуры и выбор чатов

Обычная клавиатура

ReplyKeyboardMarkup заменяет системную клавиатуру набором готовых вариантов. Простая текстовая кнопка сразу отправляет свой текст в чат. Параметр one_time_keyboard скрывает клавиатуру после использования, а input_field_placeholder меняет подсказку в поле ввода.

Inline-клавиатура

Inline-клавиатура размещается под сообщением бота. Нажатие не создаёт пользовательского сообщения в чате. Поддерживаются callback- и URL-кнопки, переход в inline-режим, платежи, игры, копирование текста, стили и отключённые состояния кнопок.

Выбор чата или нескольких пользователей

Бот может открыть системный список групп, каналов или пользователей, отфильтрованный по заданным критериям:

1. Опишите критерии в KeyboardButtonRequestChat или KeyboardButtonRequestUsers.
2. Поместите объект в поле request_chat или request_users кнопки KeyboardButton.
3. Отправьте кнопку внутри ReplyKeyboardMarkup.
4. Обработайте служебное сообщение chat_shared или users_shared.

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

Inline-режим, deep links и приватные ответы

Inline-режим

Пользователь вводит @username бота и поисковую фразу в любом чате, получает варианты и отправляет выбранный результат. Inline-режим нужно предварительно включить в BotFather, иначе бот не будет получать соответствующие обновления.

Deep linking

Параметр запуска можно передать в ссылке:

https://t.me/your_bot?start=airplane

После открытия бот получит /start airplane. Для добавления в группу используется startgroup:

https://t.me/your_bot?startgroup=spaceship

Параметр содержит до 64 символов. Допустимы A-Z, a-z, 0-9, _ и -; бинарные данные рекомендуется кодировать через base64url. Типичные применения — одноразовый токен связывания аккаунтов и контекст рекламного перехода.

Attachment menu

Некоторые боты можно запускать из меню вложений любого чата. В рабочей среде интеграция доступна ограниченному кругу одобренных ботов; в тестовой среде её могут использовать все боты.

Ephemeral messages

Ephemeral messages позволяют отправить в группе ответ, который видят только выбранный пользователь и бот. Поддерживаются текст, rich messages, фотографии, видео, анимации, аудио, документы, голосовые сообщения, стикеры, контакты, локации и места.

Bot API 10.3 использует объект EphemeralMessageParameters в методах отправки. Он также позволяет заменить исходное сообщение callback-запроса приватным представлением для конкретного пользователя. Ephemeral-сообщения можно редактировать и удалять до истечения срока их жизни.

Команду можно сделать приватной с помощью поля is_ephemeral объекта BotCommand. Тогда сообщение пользователя не увидят остальные участники группы и другие боты.

Потоковые ответы и темы в личных чатах

Потоковый черновик

В личном чате бот может показывать временный черновик, пока формируется окончательный ответ. Для обычного текста используется sendMessageDraft, для структурированного — sendRichMessageDraft.

Черновик не остаётся в истории автоматически. После завершения нужно отправить результат через sendMessage или sendRichMessage. В Bot API 10.3 можно разрешить пользователю остановить генерацию: бот получит обновление stopped_message_generation с объектом MessageGenerationStopped.

Темы в личном чате

Темы разделяют долгую переписку с одним ботом на независимые ветки: например, отдельные проекты, заказы или обращения в поддержку. Режим предварительно включается в BotFather. Для управления используются методы createForumTopic, editForumTopic и deleteForumTopic, а при отправке сообщения передаётся message_thread_id.

Mini Apps

Mini App — веб-интерфейс, открывающийся внутри Telegram. Его можно запускать из профиля бота, клавиатуры, inline-кнопки, кнопки меню, inline-режима, прямой ссылки и attachment menu.

Платформа поддерживает:

• Main Mini App с кнопкой запуска, скриншотами и демо-видео в профиле;
• локализованные превью; для ботов с Main Mini App — отображение в разделе Apps поиска;
• ярлыки на домашнем экране устройства;
• настраиваемый экран загрузки;
• полноэкранный режим в портретной и альбомной ориентации;
• QR-сканер, биометрию и нативные диалоги;
• отправку подготовленного медиа в чаты и открытие редактора Stories через shareToStory;
• геолокацию, акселерометр, ориентацию и гироскоп;
• базовую информацию о производительности Android-устройства;
• chat_instance и chat_type для совместных сценариев, открытых из контекста чата;
• локальное и защищённое хранилища DeviceStorage и SecureStorage.

Монетизация

Поток цифровой продажи:

1. Отправьте инвойс через sendInvoice с currency: "XTR".
2. Получите обновление pre_checkout_query.
3. Ответьте методом answerPreCheckoutQuery в течение 10 секунд.
4. Дождитесь сообщения с полем successful_payment.
5. Сохраните telegram_payment_charge_id для возможного возврата.
6. Только после подтверждения оплаты выдайте товар или услугу.

Для физических товаров можно использовать внешнего платёжного провайдера и другую валюту по правилам соответствующего сценария Telegram.

Агентные режимы

Secretary Mode

Secretary Mode позволяет подключить бота к аккаунту пользователя. Бот обрабатывает выбранные входящие сообщения и выполняет разрешённые действия от имени владельца.

Порядок подключения:

1. Включите Secretary Mode в BotFather.
2. Обрабатывайте обновления business_connection.
3. Принимайте business_message, edited_business_message и deleted_business_messages.
4. Проверяйте актуальные разрешения в поле rights объекта BusinessConnection, включая rights.can_reply.
5. Передавайте business_connection_id в методы отправки и другие поддерживаемые методы.

Отправка и редактирование от имени владельца доступны в подходящих личных чатах с входящими сообщениями за последние 24 часа; набор действий определяется выданными правами и может быть отозван пользователем.

Managed bots

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

1. Включите Bot Management Mode в Mini App BotFather.
2. Передайте пользователю ссылку:

https://t.me/newbot/ManagerBot/CoolAIAgentBot?name=Cool+AI+Agent

1. После подтверждения получите обновление managed_bot с объектом ManagedBotUpdated.
2. Запросите токен через getManagedBotToken.
3. Для ротации используйте replaceManagedBotToken, а для прав доступа — getManagedBotAccessSettings и setManagedBotAccessSettings.

Токены управляемых ботов требуют того же уровня защиты, что и любые другие секреты инфраструктуры.

Bot-to-bot communication

Обычно боты не видят сообщения друг друга. После включения Bot-to-Bot Communication Mode доступны следующие варианты:

• в группе — команда с упоминанием /command@OtherBot или ответ на сообщение другого бота; достаточно, чтобы режим был включён хотя бы у одного участника обмена;
• в личной переписке между ботами — режим должен быть включён у отправителя и получателя;
• через бизнес-аккаунт — отправляющему боту нужен включённый режим и подходящий доступ к аккаунту.

В группе бот с включённым режимом также может получать сообщения других ботов без явного упоминания или ответа, если он администратор или для него отключён Group Privacy Mode.

Guest Mode

Гостевой бот отвечает в чате, участником которого не является. Он получает обновление guest_message с контекстом вызова и отправляет один ответ через answerGuestQuery. Доступа ко всей истории и списку участников у него нет. В одном сообщении можно вызвать до трёх гостевых ботов.

Inline-режим подходит, когда пользователь выбирает результат и отправляет его сам. Guest Mode используется, когда бот отвечает в чужом чате от собственного имени.

Форматирование сообщений

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

Rich messages предназначены для структурированных отчётов, документации и ответов ИИ. Они поддерживают заголовки, списки, таблицы, математические выражения, медиаблоки, цитаты, ссылки внутри документа и сворачиваемые элементы. Bot API 10.3 добавил кнопки в rich messages, компактные таблицы, раскрываемые цитаты и блоки документов.

Rich messages можно отправлять методом sendRichMessage, редактировать через editMessageText с параметром rich_message и формировать постепенно через sendRichMessageDraft.

Язык интерфейса

Поле language_code содержит IETF language tag пользователя и может использоваться для локализации текстов, команд и inline-результатов. Mini Apps также получают язык в данных пользователя.

Privacy mode, тестирование и Local Bot API

Privacy mode

При включённом privacy mode бот в группе получает ограниченный набор сообщений:

• явно адресованные ему команды;
• некоторые общие команды, например /start, если бот последним отправил сообщение в группу;
• сообщения, отправленные через его inline-режим;
• ответы на его сообщения;
• служебные события.

Личные чаты, сообщения каналов, где присутствует бот, и служебные события обрабатываются отдельно от этого ограничения. Бот с правами администратора группы получает все сообщения. Отключайте privacy mode только для сценариев, которым действительно нужен общий поток переписки.

Тестирование

Для простого тестирования достаточно отдельного бота с собственным токеном. Telegram также предоставляет тестовую среду с отдельным аккаунтом и ботом:

https://api.telegram.org/bot<token>/test/METHOD_NAME

В тестовой среде для LoginUrl и WebAppInfo допустимы HTTP-ссылки без TLS. Лимиты запросов там не смягчены и могут быть строже, поэтому обработку повторов и задержек лучше предусмотреть сразу.

Статус-алерты

BotFather может предупреждать о заметном падении доли обработанных личных сообщений, inline-запросов или callback-запросов у популярных ботов. У алерта доступны действия Fixed, Support и временное отключение уведомлений.

Local Bot API

Открытый сервер Bot API можно запустить в собственной инфраструктуре. Перед переходом с облачного адреса вызовите logOut. Локальный сервер позволяет:

• скачивать файлы без ограничения размера;
• загружать файлы до 2000 МБ и передавать локальные пути;
• использовать HTTP, локальные IP-адреса и произвольные порты для webhook;
• устанавливать max_webhook_connections до 100 000;
• получать абсолютный локальный путь к файлу через file_path.

Для публичного доступа к локальному серверу самостоятельно настройте TLS, аутентификацию, сетевые ограничения и мониторинг.

Полезные сценарии

Личный агент без ручного создания в BotFather

Включите Bot Management Mode и выдайте ссылку формата:

https://t.me/newbot/{manager_bot_username}/{suggested_bot_username}?name={suggested_bot_name}

После подтверждения получите обновление managed_bot, запросите токен и сохраните его в защищённом хранилище. Результат можно проверить методом getMe нового бота. Сценарий не подходит без продуманной ротации токенов и обработки отзыва доступа.

Помощник в рабочей группе без постоянного доступа

Включите Guest Mode. Пользователь вызывает бота упоминанием или ответом, бот получает только доступный контекст и отвечает через answerGuestQuery. Это подходит для перевода, проверки фактов и коротких справок, но не для задач, которым нужна история чата.

Обработка входящих сообщений бизнес-аккаунта

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

Потоковый ответ ИИ

Создавайте черновик через sendMessageDraft или sendRichMessageDraft, обновляйте его по мере генерации и отправляйте финальную версию отдельным методом. При включённой остановке обработайте stopped_message_generation, чтобы прекратить вычисления на бэкенде.

Продажа цифрового продукта

Используйте Stars и валюту XTR, подтвердите pre_checkout_query в течение 10 секунд и выдавайте продукт только после successful_payment. Для поддержки возвратов сохраняйте telegram_payment_charge_id.

Быстрый интерфейс без Mini App

Для нескольких действий используйте команды и inline-клавиатуру. Выбор группы или пользователей можно вынести в системную кнопку request_chat или request_users. Mini App оправдан, когда нужен отдельный экран со сложным состоянием и собственной логикой.

Минимальная проверка бота

Токен храните в переменной окружения, а не в исходном коде или репозитории.

export BOT_TOKEN="<токен из BotFather>"

curl "https://api.telegram.org/bot$BOT_TOKEN/getMe"

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setMyCommands" -H "Content-Type: application/json" -d '{"commands":[{"command":"start","description":"Начать работу"},{"command":"help","description":"Что умеет бот"}]}'

Признаки успеха:

• оба запроса возвращают JSON с "ok": true;
• getMe содержит идентификатор, имя пользователя и актуальные флаги возможностей бота;
• после ввода / в чате видны команды /start и /help с описаниями.

Этот пример проверяет доступность API и публикацию команд, но не тестирует получение обновлений. Для полной проверки отдельно настройте webhook или getUpdates.

Ограничения, которые стоит проверить до запуска

• Secretary Mode, managed bots, bot-to-bot communication, Guest Mode, inline-режим и темы включаются отдельно в BotFather или его Mini App.
• Privacy mode включён по умолчанию; бот с правами администратора получает весь поток сообщений группы.
• file_id привязан к конкретному боту, поэтому тестовый экземпляр не может переиспользовать идентификаторы медиа основного бота.
• Attachment menu в рабочей среде доступно ограниченному кругу ботов.
• Цифровые товары и услуги внутри Telegram продаются только за Stars с кодом XTR.
• Действия Business Bot определяются текущими правами и ограничениями конкретного чата.
• Потоковый черновик нужно завершать обычным или rich-сообщением, если результат должен остаться в истории.
• Bot-to-bot сценариям необходимы защита от циклов и ограничения частоты.
• Работа ботов регулируется Telegram Bot Platform Developer Terms of Service; для Business Bots отдельно учитывайте раздел 5.4.

Официальные ссылки

• Telegram Bot Features
• Telegram Bot API
• Bot API changelog
• Telegram Mini Apps
• Платежи за цифровые товары в Stars
• Условия для разработчиков ботов
• @BotFather

Чеклист перед запуском

Следующий шаг

Telegram Business Bots — как боты управляют бизнес-аккаунтом в Telegram

Связанные материалы

• Статья: Как мы превратили аудиоверсии pimenov.ai в Telegram-плейлист
• Блог: Люди + агенты в одном чате: как мы собрали рабочий контур в Telegram

Этот справочник помогает выбрать формат взаимодействия до начала разработки и проверить ограничения выбранного режима.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov