# Bot API Telegram и MAX для ИИ-агента (/ru/docs/bot-api)

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

Bot API — официальный способ управлять ботом Telegram или MAX из программы:
[Telegram Bot API](https://core.telegram.org/bots/api) и [MAX Bot API](https://dev.max.ru/docs-api).
Инструменты командной строки `tg` и `max` покрывают его целиком: все 185 методов Telegram и все
33 операции MAX. Кроме того, они добавляют то, чего в официальном API нет: копию сообщений бота
с поиском, модерацию группы по вашим правилам и ограничения на то, куда бот может писать.
Поручите работу с ботом агенту или выполняйте команды сами.

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

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

## Что умеет бот [#что-умеет-бот]

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

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

## Что CLI добавляет к Bot API [#что-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-и-max]

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

Все команды и ограничения: [боты Telegram](/llms.mdx/docs/ru/tg/bot/content.md) · [боты MAX](/llms.mdx/docs/ru/max/bot/content.md).

## Подключите бота [#подключите-бота]

Сначала создайте бота: в Telegram через [BotFather](https://t.me/BotFather), в MAX на [business.max.ru](https://business.max.ru/self). Шаги описаны в [инструкции Telegram](/llms.mdx/docs/ru/tg/bot/content.md) и [MAX](/llms.mdx/docs/ru/max/bot/content.md). Затем сохраните его токен (Секретный ключ вашего бота, с которым программа может действовать от его имени. Он не связан со входом в личный аккаунт; сохраните его через команду подключения бота.) в скрытом запросе терминала:

```sh
tg support bot auth set
max support bot auth set
```

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

```sh
tg support bot me
max support bot me
```

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

## Поручите агенту задачу [#поручите-агенту-задачу]

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

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

Агент должен показать бота, выбранный чат и черновик. Вы проверяете текст и получателя, затем отдельно разрешаете отправку. Как узнать чат и отправить сообщение: [Telegram](/llms.mdx/docs/ru/tg/bot/content.md) или [MAX](/llms.mdx/docs/ru/max/bot/content.md).

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

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

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

## Перед автоматизацией [#перед-автоматизацией]

Выдайте профилю бота только нужные [права](/llms.mdx/docs/ru/configuration/content.md#%D0%BF%D1%80%D0%B0%D0%B2%D0%B0) и определите разрешённых получателей.
Для важных сообщений просите проверку текста перед отправкой. Вебхуки и чтение обновлений
связывают бота с другими приложениями: изменение может прервать существующую интеграцию.

## Когда нужен полный API [#когда-нужен-полный-api]

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

```sh
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](/llms.mdx/docs/ru/agents/content.md#mcp-%D0%B8-%D0%BD%D0%B0%D0%B2%D1%8B%D0%BA%D0%B8) даёт отдельные инструменты для типичных задач. Агент с терминалом может использовать оба интерфейса.

[Настройка и задачи Telegram-бота](/llms.mdx/docs/ru/tg/bot/content.md) · [MAX-бота](/llms.mdx/docs/ru/max/bot/content.md). Официальные методы: [Telegram](https://core.telegram.org/bots/api) и [MAX](https://dev.max.ru/docs-api).
