Работа с агентом

Bot API Telegram и MAX для ИИ-агента

Управляйте ботом Telegram или MAX через ИИ-агента или терминал по Bot API: отправляйте сообщения и файлы, обрабатывайте события и помогайте с задачами в группе.

Используйте бота через агента или терминал, чтобы отвечать на запросы, публиковать объявления или помогать в группе. Подключите его и проверьте доступ перед первой задачей. Бот — отдельный аккаунт со своим именем и правами. Он не получает доступ к вашей личной переписке, а команды без bot по-прежнему работают от вашего личного аккаунта.

Bot API — официальный способ управлять ботом Telegram или MAX из программы: Telegram Bot API и MAX Bot API. Инструменты командной строки tg и max покрывают его целиком: все 185 методов Telegram и все 33 операции MAX. Кроме того, они добавляют то, чего в официальном API нет: копию сообщений бота с поиском, модерацию группы по вашим правилам и ограничения на то, куда бот может писать. Поручите работу с ботом агенту или выполняйте команды сами.

На этой странице:

  1. Что умеет бот
  2. Что CLI добавляет к Bot API
  3. Чем отличаются Telegram и MAX
  4. Подключите бота
  5. Поручите агенту задачу
  6. Отправить сообщение самому
  7. Перед автоматизацией
  8. Когда нужен полный API

Что умеет бот

ЗадачаTelegramMAX
Отправлять, отвечать, редактировать, удалять и закреплять сообщения, с Markdown или HTMLДаДа
Отправлять файлы, фото и голосовыеДаДа
Видеть новые сообщения, правки, нажатия кнопок, входы и выходы участниковДаДа, и удалённые сообщения
Отвечать на кнопки, задавать меню команд, подключать вебхукДаДа
Назначать и снимать админов с нужными правами; удалять и блокировать участниковДаДа
Получать список участников группыНет: Telegram Bot API этого не умеетДа, по 100 за страницу
Добавлять участников в группуНет: Telegram Bot API этого не умеетДа, пока сервер MAX это выполняет
Отвечать в комментариях под постами каналаНетДа
Проверять группу по вашим правилам и удалять нарушенияДаДа
Читать и искать то, что бот отправил и получилДаДа
Загружать старые сообщенияКаналы и супергруппыДа

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

Что CLI добавляет к Bot API

  • История с поиском. В Telegram Bot API нет способа прочитать старые сообщения. CLI хранит на вашем компьютере всё, что бот отправил и получил, поэтому вы и агент можете просматривать сообщения, искать по ним и узнавать, кто что написал. Старые сообщения тоже можно загрузить.
  • Модерация группы по вашим правилам. Правила группы сохраняются один раз. Бот проверяет по ним новые сообщения, показывает, что собирается сделать, и действует только в пределах правил.
  • Ограничения на запись. У каждого бота есть список чатов, куда ему можно писать, необязательный лимит в час и журнал всех записей. Текст сообщений в журнал не попадает. Ограничения действуют и для полного API.
  • Защищённый токен. Токен хранится в системном хранилище ключей и никогда не выводится на экран, даже в сообщениях об ошибках.
  • Несколько ботов. У каждого бота своё имя профиля — первое слово команды: tg sales bot …, tg support bot ….
  • Результат, понятный программе. --json даёт чистые данные и понятные коды выхода. Если связь оборвалась во время отправки, CLI не отправляет повторно: он сообщает, что результат неизвестен, и вы сначала проверяете чат.
  • Подключение для агента. tg <bot> bot mcp serve и max <bot> bot mcp serve передают бота приложению агента только с теми правами, которые вы задали.

Чем отличаются Telegram и MAX

  • Telegram: человек должен сам начать диалог с ботом, прежде чем бот сможет ему написать. В группе бот без прав админа видит только команды и ответы ему, если в BotFather не отключён режим приватности.
  • MAX: создать бота могут только проверенные организации, индивидуальные предприниматели и самозанятые, и каждый бот проходит модерацию. Бот может вступать в группы только после того, как вы разрешите это в настройках приватности бота на business.max.ru.

Все команды и ограничения: боты Telegram · боты MAX.

Подключите бота

Сначала создайте бота: в Telegram через BotFather, в MAX на business.max.ru. Шаги описаны в инструкции Telegram и MAX. Затем сохраните его токен в скрытом запросе терминала:

tg support bot auth set
max support bot auth set

support — выбранное вами имя профиля бота. Выполните команду своего мессенджера. Лучше самостоятельно ввести токен в скрытом поле терминала выше. Вы можете передать его агенту, но тогда токен сохранится в истории чата с агентом. Не вставляйте его в аргументы команды или снимки экрана. Проверка ниже покажет, какой бот подключён:

tg support bot me
max support bot me

Ожидайте имя и идентификатор именно вашего бота. Затем добавьте его в нужную группу или канал либо начните с ним личную беседу. Для Telegram пользователь должен сначала начать диалог с ботом, чтобы тот мог ему написать.

Поручите агенту задачу

В примере используется профиль Telegram-бота support. Для MAX замените «Используй tg CLI» на «Используй max CLI» и укажите его профиль бота. В браузерном чате назовите подключённый инструмент бота.

Запрос
Используй tg CLI с подключённым ботом support: проверь, кто он и какие события ему доступны. Предложи, как подготовить отчёт для моей группы. Покажи, какой чат выбран, и составь черновик. Пока ничего не отправляй.

Агент должен показать бота, выбранный чат и черновик. Вы проверяете текст и получателя, затем отдельно разрешаете отправку. Как узнать чат и отправить сообщение: Telegram или MAX.

Отправить сообщение самому

tg support bot messages send "Команда" "Отчёт готов"
max support bot messages send "Команда" "Отчёт готов"

Замените чат и текст теми, которые хотите отправить. Это настоящее сообщение от бота. Бот также может отправлять файлы, отвечать на сообщения и управлять чатами при необходимых правах. Не выдавайте ему права администратора для действий, которым они не нужны.

Перед автоматизацией

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

Когда нужен полный API

Для обычных задач есть удобные команды вроде bot messages send. Для более редких операций доступен весь нативный Bot API Telegram и MAX.

tg support bot api --help
max support bot api --help
tg support bot api get-me --json
max support bot api get-my-info --json

Справка метода объясняет его поля. Имена и параметры следуют API провайдера. Полный API доступен через командную строку; MCP даёт отдельные инструменты для типичных задач. Агент с терминалом может использовать оба интерфейса.

Настройка и задачи Telegram-бота · MAX-бота. Официальные методы: Telegram и MAX.