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

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

Что это такое

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

Практическая разница простая. Bot API отвечает на вопрос «каким вызовом это сделать», Bot Features — на вопрос «что вообще можно сделать и где это включается».

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

Команды

Команда — это /keyword, который Telegram подсвечивает в сообщении и подсказывает пользователю после ввода /.

Правила:

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

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

Scopes и menu button

Список команд можно показывать по-разному для разных аудиторий: администраторам группы, конкретному чату или пользователям с определённым language_code. Это делается через scopes. Кнопка меню рядом с полем ввода показывает те же команды с описаниями, а вместо меню её можно назначить на запуск Mini App.

Клавиатуры и кнопки

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

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

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

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

Выбор чата или пользователя

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

1. Опишите критерии в объекте KeyboardButtonRequestChat или KeyboardButtonRequestUser.
2. Создайте KeyboardButton и положите критерии в поле request_chat или request_user.
3. Отправьте ReplyKeyboardMarkup с этой кнопкой.
4. После выбора обработайте служебное сообщение chat_shared или user_shared с идентификатором.

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

Inline-режим, deep links и attachment menu

Inline-режим

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

Deep linking

У каждого бота есть ссылка https://t.me/<bot_username>, в которую можно передать параметр:

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

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

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

Attachment menu

Бота можно добавить в меню вложений, чтобы вызывать его в любом чате. Возможность доступна только одобренным ботам.

Ephemeral messages

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

Отдельная часть механики — ephemeral-команды: сообщение пользователя остаётся невидимым для остальных участников группы и для других ботов.

Mini Apps

Mini App — это веб-интерфейс, который открывается внутри Telegram и может заменить сайт целиком. Главное, что даёт платформа:

• Main Mini App с кнопкой запуска, скриншотами и демо-видео в профиле бота;
• превью с поддержкой нескольких языков и попадание в Mini App Store;
• ярлыки на домашнем экране устройства;
• настраиваемый splash screen с собственной иконкой и цветами для светлой и тёмной темы;
• полноэкранный режим, включая ландшафтную ориентацию;
• нативные диалоги: чтение QR-кодов, биометрия, шаринг медиа в чаты и в Stories через shareToStory;
• доступ к геолокации, данным акселерометра и ориентации, базовой информации о железе устройства;
• параметр chat_instance для совместных сценариев при открытии из группы.

Монетизация

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

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

Самая интересная для агентных сценариев часть документации появилась вокруг четырёх режимов.

Secretary Mode

Пользователь подключает бота к своему аккаунту, и бот обрабатывает входящие сообщения, а при наличии прав отвечает от имени владельца. Владелец сам выбирает, к каким чатам есть доступ.

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

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

Действия от имени владельца возможны в чатах, активных за последние 24 часа. При подключении бот получает deep link вида /start bizChat<user_chat_id>.

Managed bots

Бот может создавать и управлять другими ботами по поручению владельцев. Включите режим управления в MiniApp BotFather, затем дайте пользователю ссылку формата https://t.me/newbot/<manager_bot>/<new_username>?name=<new_name>. После подтверждения ваш бот получит апдейт managed_bot с объектом ManagedBotUpdated, а токен нового бота запрашивается методом getManagedBotToken.

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

Bot-to-bot

По умолчанию боты не видят сообщений друг друга. Режим Bot-to-Bot Communication Mode в BotFather открывает три канала связи: упоминание или ответ в группе, личные сообщения по @username при включённом режиме у обеих сторон и обмен внутри бизнес-аккаунта через Chat Access Mode.

Guest Mode

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

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

Доступны два уровня, и оба рендерятся нативно во всех клиентах Telegram.

Rich messages предназначены для структурированных ответов: отчётов, потоковых ответов ИИ, фрагментов документации. Поддерживаются Rich Markdown и Rich HTML, а внутри — заголовки, списки и таск-листы, таблицы с выравниванием и объединением ячеек, медиаблоки с подписями, цитаты, сворачиваемые блоки, сноски, ссылки внутри документа и полноценный LaTeX.

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

Языки

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

Управление ботом

Privacy mode

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

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

Независимо от privacy mode бот всегда получает служебные сообщения, все сообщения из личных чатов и все сообщения из каналов, где он состоит. Боты, добавленные в группу администраторами, получают вообще всё. Отключать privacy mode документация советует только когда без этого бот не работает; в остальных случаях достаточно force reply.

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

Простой путь — второй бот с отдельным токеном и тот же код. Для более сложных случаев есть отдельное тестовое окружение с новым аккаунтом и новым ботом: запросы идут на https://api.telegram.org/bot<token>/test/METHOD_NAME, а в LoginUrl и WebAppInfo разрешены HTTP-ссылки без TLS. Флуд-лимиты в тестовом окружении не смягчены и иногда строже, поэтому retry-политика нужна сразу.

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

BotFather сам присылает предупреждения, если у популярного бота (порядка 300 запросов в минуту) падает конверсия ответов: мало ответов на личные сообщения, на inline-запросы или на callback-запросы. По умолчанию приходит не больше одного алерта на бота в час, у каждого есть кнопки Fixed, Support и Mute на 8 часов или неделю.

Local Bot API

Открытый сервер Bot API можно поднять у себя. Работает на порту 8081 и принимает только HTTP, так что HTTPS-запросы нужно терминировать прокси. Перед переключением на локальный адрес вызовите logOut.

Практические сценарии

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

Личный агент по одной ссылке

Пользователь получает собственного бота, не заходя в BotFather. Включите Bot Management Mode в MiniApp BotFather и отправьте ссылку вида https://t.me/newbot/ManagerBot/CoolAIAgentBot?name=Cool+AI+Agent. После подтверждения придёт апдейт managed_bot, токен запрашивается через getManagedBotToken, дальше бот управляется обычными методами. Заранее решите, где хранятся токены и что происходит при отзыве доступа.

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

Нужен ответ по запросу, но не хочется добавлять бота в чат и отдавать ему историю. Включите Guest Mode: бот отвечает на упоминание или на ответ на его сообщение, получает только контекст вызова и даёт один ответ. Хорошо для перевода, проверки фактов и коротких справок. В одном сообщении можно позвать до трёх гостевых ботов.

Обработка входящих вместо владельца

Бизнес-аккаунт получает много однотипных сообщений. Secretary Mode позволяет боту читать выбранные чаты и отвечать от имени владельца в чатах, активных за последние 24 часа. Храните business_connection_id из апдейта подключения, каждый раз проверяйте can_reply и предусмотрите поведение на случай, когда права отозвали.

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

Курс, доступ или шаблон продаются через Stars с валютой XTR. Для регулярной оплаты используйте подписочные тарифы, для платного контента — paid media, где фото и видео открываются после оплаты. Физические товары идут через внешнего провайдера: инвойс, answerPreCheckoutQuery, служебное сообщение об оплате, выполнение заказа.

Отчёты, которые читаются в чате

Сводки, выгрузки и потоковые ответы модели удобнее отдавать rich-сообщениями: заголовки, таблицы с объединением ячеек, сворачиваемые блоки, сноски и LaTeX рендерятся нативно. Для коротких подтверждений хватит MarkdownV2. Посмотреть возможности вживую можно у @RichTextDemoBot.

Связка сайта и аккаунта Telegram

Два рабочих пути. Login-виджет: подберите бота под название сайта, привяжите домен через /setdomain, встройте виджет. Inline-вариант: кнопка с login_url авторизует пользователя до загрузки страницы. Обратное направление — deep link с одноразовым токеном в параметре start, по которому бэкенд связывает аккаунты.

Обмен между несколькими агентами

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

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

Если задача сводится к нескольким действиям, обойдитесь командами и inline-клавиатурой: переключение настроек делается редактированием того же сообщения, а выбор группы или пользователя — кнопкой с request_chat или request_user. Mini App имеет смысл, когда нужен полноценный экран со своей логикой.

Минимальный рабочий сценарий и проверка

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

# токен храните в переменной окружения, а не в коде и не в репозитории
export BOT_TOKEN="<токен из BotFather>"

# 1. Проверка доступности бота
curl "https://api.telegram.org/bot$BOT_TOKEN/getMe"

# 2. Публикация списка команд
curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{"commands":[{"command":"start","description":"Начать работу"},{"command":"help","description":"Что умеет бот"}]}'

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

• оба запроса возвращают {"ok":true, ...};
• getMe показывает username и флаги бота;
• в чате с ботом ввод / показывает список из двух команд с описаниями.

Ограничения и что учитывать

• Secretary, managed, bot-to-bot и guest режимы не работают без включения в BotFather или в его MiniApp; ephemeral-поведение задаётся на уровне конкретной команды.
• Privacy mode включён по умолчанию у всех ботов, кроме добавленных в группу сразу администраторами. После отключения privacy mode бота нужно заново добавить в группу.
• file_id привязан к конкретному боту, поэтому тестовый экземпляр не может переиспользовать медиа основного.
• Attachment menu доступен только одобренным ботам.
• Цифровые продажи возможны только в Stars.
• В группах с включённым privacy mode бот получает команды при особых условиях, поэтому для групповых сценариев проверяйте настройку заранее.
• Действия от имени бизнес-аккаунта ограничены чатами, активными за последние 24 часа.
• Работа ботов подчиняется Telegram Bot Developer Terms of Service; для бизнес-сценариев отдельно смотрите раздел 5.4.

Ссылки

• Обзор возможностей: core.telegram.org/bots/features
• Полный справочник методов: core.telegram.org/bots/api
• Mini Apps: core.telegram.org/bots/webapps
• Платежи в Stars: core.telegram.org/bots/payments-stars
• Условия для разработчиков: telegram.org/tos/bot-developers
• Создание и настройка бота: @BotFather

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

По теме

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

Этот справочник полезен, когда нужно выбрать формат взаимодействия до начала разработки: команда, inline-режим, Mini App или гостевой агент в чужом чате.

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