# Telegram: Боты (/ru/docs/tg/bot)

На этой странице вы подключите бота к инструменту командной строки, проверите доступ к чату и подготовите первое сообщение. Бот — отдельный аккаунт мессенджера, который принимает сообщения и выполняет заданные действия: отвечает пользователям, публикует объявления и показывает кнопки. С помощью инструмента командной строки вы или ваш ИИ-агент можете действовать от имени своего бота. Это удобно для обращений клиентов, новостей сообщества и записи на мероприятия. 

## Первое подключение

[Создайте бота через @BotFather и получите его токен.](https://t.me/BotFather)

**Как создать бота через BotFather**

1. Откройте @BotFather в Telegram, нажмите «Запустить» и отправьте /newbot.
2. Укажите отображаемое имя бота, затем свободное имя пользователя с окончанием bot, например my_club_helper_bot.
3. BotFather пришлёт токен — ключ доступа к боту. Используйте его в команде подключения ниже.

[Установка инструмента](/llms.mdx/docs/ru/installation/content.md)

1. Установите инструмент командной строки, если он ещё не установлен.
2. В командах ниже sales — имя отдельного профиля бота. Введите первую команду и вставьте токен в скрытое поле терминала. Токен можно передать агенту, но он останется в истории переписки. По возможности выполните эту команду сами и введите токен в терминале.
3. Выполните вторую команду: она покажет имя подключённого бота. Добавьте бота в нужную группу или канал и выдайте права для вашей задачи.

```sh
tg sales bot auth set
tg sales bot auth show
```

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

## Проверить, какой бот подключён

```text prompt
Используй tg CLI с профилем моего бота sales. Покажи имя бота и проверь доступ к группе «Клуб». Объясни, что он может делать и каких прав не хватает. Ничего не отправляй и не меняй.
```

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

[Выбрать профиль бота](/llms.mdx/docs/ru/configuration/content.md)

## Подготовить сообщение с кнопками

```text prompt
Используй tg CLI с профилем бота sales. Подготовь объявление для группы «Клуб» с кнопками «Записаться» и «Подробнее». Покажи текст и предложенные действия кнопок. Пока ничего не отправляй.
```

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

[Что умеет Bot API](/llms.mdx/docs/ru/bot-api/content.md)

## Команды и инструкции

Используйте эту страницу, если у вас есть бот Telegram или вы хотите его иметь, и он вам нужен, чтобы публиковать сообщения, отвечать людям, смотреть группу или поддерживать там порядок. Вы узнаете, как подключить бота к `tg`, найти его чаты, отправлять и читать сообщения от имени бота, ограничивать места, где он может писать, и передавать бота своему ИИ-агенту.

Несколько слов на этой странице:

- **Бот** — это отдельный аккаунт Telegram, которым управляет программа. `tg personal bot` работает с ним через официальный [Bot API Telegram](https://core.telegram.org/bots/api). К вашему собственному аккаунту это не имеет никакого отношения: у бота есть свое имя, свои чаты и свой токен, а `tg …` без слова `bot` — это все равно вы (см. [использование своего аккаунта](/llms.mdx/docs/ru/tg/usage/content.md)).
- **Токен** — это пароль бота. Вы создаете бота с помощью [@BotFather](https://t.me/BotFather) в Telegram, и он дает вам токен.
- **Имя бота** — это слово, под которым вы хотите сохранить токен бота, например `sales`. Это первое слово каждой команды бота: `tg sales bot …`.
- **Локальная копия** — это то, что бот отправил, получил или импортировал и сохранил на этом компьютере. Telegram не предоставляет боту историю сообщений, поэтому для чтения старых сообщений используется эта копия.

## Что можно сделать [#что-можно-сделать]

| Задача | Команда |
| --- | --- |
| Подключите бота и проверьте, что это за бот | `tg <bot> bot auth set`, `tg <bot> bot me` |
| Отправлять, редактировать, удалять и закреплять сообщения и файлы | `tg <bot> bot messages send\|edit\|delete\|pin` |
| Просматривайте новые сообщения, нажатия кнопок и присоединения | `tg <bot> bot watch` |
| Читать и искать то, что увидел бот | `tg <bot> bot messages list`, `tg <bot> bot search messages` |
| Импортировать старые сообщения канала или супергруппы | `tg <bot> bot messages sync` |
| Управление администраторами и удаление участников | `tg <bot> bot chats admins`, `tg <bot> bot chats members remove` |
| Поддерживайте порядок в группе по своим правилам | `tg <bot> bot chats moderate` |
| Кнопки ответа, настройка командного меню и вебхуков | `tg <bot> bot callbacks`, `commands`, `webhooks` |
| Ограничьте количество чатов, в которые бот может писать | `tg <bot> bot recipients` |
| Вызов любого метода API бота | `tg <bot> bot api <method>` |
| Подключите бота к своему ИИ-агенту | `tg <bot> bot mcp serve` |

Каждая команда и параметр находятся в [справке по командам](/llms.mdx/docs/ru/tg/commands/content.md).

## Первое подключение [#первое-подключение]

```sh
tg sales bot auth set     # the token, at a hidden prompt
tg sales bot auth show    # which bot it is
```

Перед сохранением `auth set` проверяет в Telegram, какому боту принадлежит токен. Опечатка не заменит рабочий токен.

## Как найти идентификатор чата [#как-найти-идентификатор-чата]

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

- **Человек.** Используйте `user:<id>`. Отправка возвращает чат в поле `item.chat_id` с `--json`. Человек должен сначала запустить бота: бот Telegram не может [начать разговор](https://core.telegram.org/bots#how-are-bots-different-from-users) с тем, кто ему не писал.
- **Группа или канал.** Добавьте бота, напишите сообщение и посмотрите события:

  ```sh
  tg sales bot watch --events --jsonl --timeout 1m
  ```

  Каждая строка содержит `chat_id`. Бот без прав администратора видит в группе только команды и ответы ему, если [режим приватности](https://core.telegram.org/bots/features#privacy-mode) не отключён через @BotFather.

После `tg sales bot chats show <id>` бот узнаёт название чата, и команды ниже принимают его. `chats list` показывает все увиденные чаты.

- Идентификатор группы или канала **отрицательный**.
- Положительный идентификатор относится к человеку.

## Несколько ботов [#несколько-ботов]

Для каждого бота выберите имя. Оно указывается **первым словом** команды, как имя профиля личного аккаунта:

```sh
tg sales bot auth set
tg support bot auth set
tg personal bot list --check  # every name with a bot token, and which bot each is
```

Без имени используется `TG_PROFILE`; если он не задан, команда останавливается и перечисляет профили.

## Хранение токена [#хранение-токена]

Токен хранится в системном хранилище ключей под именем `bot:<name>`, отдельно от личной сессии. Если хранилища ключей нет, используется файл, доступный только вам.

```sh
tg sales bot auth show    # where the token comes from, and which bot it is
tg sales bot me           # the bot's id, name and username
tg sales bot auth remove  # forget it
```

Заданная переменная `TG_BOT_TOKEN` имеет приоритет над хранилищем ключей; так токен передают в CI. `auth set` не сохраняет токен из переменной.

Telegram включает токен в адрес каждого запроса. `tg` никогда не выводит этот адрес: ни в ошибках, ни с `--trace`, ни в записи запуска.

## Сообщения [#сообщения]

Чат задаётся идентификатором, `user:<id>` для человека или названием увиденного чата. Сообщение всегда указывается вместе с чатом: Telegram нумерует сообщения внутри каждого чата.

```sh
tg sales bot messages send "Team" "Build is ready"
tg sales bot messages send user:4815162342 "Hello"
tg sales bot messages send "Team" "**Weekly** report" --md       # or --html
tg sales bot messages send "Team" "Got it" --reply-to 511
echo "From a pipe" | tg sales bot messages send "Team"
tg sales bot messages edit "Team" 512 "Fixed text"
tg sales bot messages delete "Team" 512 513 --allow-dangerous
tg sales bot messages pin "Team" 512 --notify
tg sales bot messages unpin "Team" 512
```

`--silent` отправляет без уведомления. Максимум 4096 символов ([`sendMessage`](https://core.telegram.org/bots/api#sendmessage)). `--md` и `--html` несовместимы. Удаление спрашивает подтверждение; `--allow-dangerous` подтверждает. Закрепление тихое без `--notify`. Отправка возвращает сообщение и `operation_id` записи в журнале. Telegram разрешает удалять только сообщения моложе 48 часов.

Если соединение оборвалось при отправке, `tg` не повторяет её: результат неизвестен (код 14). Перед повтором проверьте чат.

### Файлы [#файлы]

`--file` прикрепляет файл с диска и отправляет его как документ, независимо от его типа. `--photo` отправляет изображение `.jpg`, `.png` или `.webp` в виде фотографии, а `--voice` — файл Ogg Opus в виде голосового сообщения, отдельно, без текста. Текст становится подписью и может быть опущен:

```sh
tg sales bot messages send "Team" "Weekly report" --file report.pdf
tg sales bot messages send "Team" --photo screenshot.png
```

Известные файлы и папки с учётными данными, собственные папки `tg` и хранилище сообщений защищены. Обычные скрытые рабочие папки разрешены; `--allow-any-file` в CLI позволяет использовать защищённые пути. Одно вложение на сообщение: фото до 10 МБ, остальные файлы до 50 МБ ([отправка файлов](https://core.telegram.org/bots/api#sending-files)).

## Чаты [#чаты]

Telegram не предоставляет боту полный список его чатов. Поэтому `chats list` показывает **только чаты, которые бот видел на этом компьютере**.

```sh
tg sales bot chats list
tg sales bot chats show -1001234567890    # from Telegram; the bot remembers its title
tg sales bot chats action "Team" typing   # typing, photo, video, voice, file — a few seconds
tg sales bot chats leave "Team"           # only an admin can bring the bot back
```

### Администраторы и участники [#администраторы-и-участники]

Бот должен быть администратором с правом назначать администраторов или удалять участников. Человек задаётся идентификатором пользователя.

```sh
tg sales bot chats admins list "Team"                                  # who runs it, and what each may do
tg sales bot chats admins add "Team" 4815162342 --can pin,delete --title Mod
tg sales bot chats admins remove "Team" 4815162342                     # they stay in the chat
tg sales bot chats members remove "Team" 4815162342                    # they may come back by the link
tg sales bot chats members remove "Team" 4815162342 --block            # they may not
```

`--can` принимает members, admins, info, pin, link, post, edit, delete. Отдельного права чтения в Telegram нет: администратор всегда читает. Назначение работает в супергруппах и каналах, титул — только в супергруппах. Bot API не позволяет получить список участников или добавить людей.

## Сохранённые данные бота [#сохранённые-данные-бота]

Все, что видел `tg sales bot watch`, хранится на этом компьютере, и эти команды читают его, не спрашивая Telegram. Человек — это идентификатор, `@username` или часть имени.

```sh
tg sales bot messages list "Team"
tg sales bot messages show "Team" 512
tg sales bot contacts show @ann              # where Ann wrote, and her private chat with the bot
tg sales bot search messages "price list"    # best match first; --newest for newest first
tg sales bot search messages --from @ann     # what one person wrote
tg sales bot messages between @ann Bob       # what both wrote, in the chats both wrote in
```

**В Bot API Telegram нет метода чтения истории.** `messages list` и `messages show` отвечают на основе того, что отправил бот, что получил `bot watch` и что `bot messages sync` импортировал на этот компьютер, и так и говорят. Для поиска необходимо каждое слово; `"a phrase"`, `-word`, `a OR b` и фильтры `from:`, `chat:`, `after:`, `before:` и `has:` работают, опечатка исправляется. `contacts show --sync-first` отклонен: сначала импортируйте старые сообщения с `bot messages sync`.

`--all-bots` и `--bots <names>` также читают копии других ботов, если `read_other_bots` профиля это позволяет.

### Получение старых сообщений [#получение-старых-сообщений]

`bot messages sync` загружает старые сообщения канала или супергруппы в локальную копию бота. Команда создаёт отдельную сессию MTProto API Telegram с существующим токеном бота и читает номера сообщений через [channels.getMessages](https://core.telegram.org/method/channels.getMessages). Отправка и `bot watch` продолжают работать через Bot API; получение обновлений в сессии истории отключено. Команда ничего не отправляет и не отмечает прочитанным.

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

```sh
tg sales bot messages sync -1001234567890 --until-id https://t.me/c/1234567890/512 --limit 20 --json
tg sales bot messages sync -1001234567890 --last 200 --pause 1s
```

`--until-id` начинает с указанного сообщения (ссылка t.me) включительно; ссылка должна вести в тот же чат. Без параметра команда использует самое новое сохранённое сообщение бота в этом чате. Если его нет, берёт номер самого нового сообщения из личной сессии того же профиля, если она есть. Если номер неизвестен обоим источникам, команда завершается с кодом `2` и просит указать `--until-id`. Используются собственные ключи приложения Telegram этого профиля (`api_id` и `api_hash`), никогда — ключи другого профиля; подходят и `TG_API_ID` с `TG_API_HASH`. Вход в личный аккаунт не выполняется.

- `--limit` ограничивает число сообщений за запуск (по умолчанию 1000).
- `--page-size` ограничивает число запрашиваемых номеров на страницу, максимум 100.
- `--pause` задаёт паузу между запросами (по умолчанию 1 секунда), в том числе при чтении пустых диапазонов.
- `--last` останавливает загрузку, когда сохранено указанное число последних сообщений.
- `--since-time` останавливается на более старых сообщениях; время в ISO 8601 либо `2h` / `1d` назад.
  Укажите `--last` или `--since-time`, но не оба.

Повторный запуск продолжает чтение назад. JSON содержит `chat`, `fetched`, `complete` и `ranges`. Загруженные сообщения доступны через `bot messages list --offline`, поиск и контакты. Сессия бота хранится отдельно в каталоге состояния, для каждого профиля и идентификатора бота; при завершении команды она закрывается.

**Ограничения:** личные чаты и обычные группы не поддерживаются: номера их сообщений идут в одной последовательности для всех чатов бота. Бот должен иметь доступ к каналу или супергруппе. Удалённые сообщения и служебные номера оставляют пробелы; чтение проходит через них вплоть до номера 1. Большие пробелы могут потребовать много запросов даже при небольшом `--limit`. Лимиты Telegram для ботов действуют: короткое ожидание выполняется, длительное завершает запуск, чтобы вы могли продолжить позже.

## События в чатах бота [#события-в-чатах-бота]

```sh
tg sales bot watch                       # new messages, until Ctrl-C or --timeout
tg sales bot watch --events --jsonl      # and the rest: edits, buttons pressed, people joining and leaving
tg sales bot watch --types message,callback_query
```

`watch` сначала сохраняет событие, затем выводит: сообщения — в локальную историю бота, нажатия кнопок — для `callbacks answer`. Следующий запуск продолжает после сохранённого обновления. Telegram хранит обновления 24 часа: более редкий запуск пропускает события. С `--events` строки имеют тип: `message`, `edit`, `callback`, `joined`, `left`, `added`, `removed`, `other`. Вступления и выходы доступны только боту-администратору. `--types` принимает имена обновлений Telegram.

## Модерация группы по правилам [#модерация-группы-по-правилам]

Бот, являющийся администратором группы, может судить о том, что там нового, по правилам группы, как это делает `tg personal chats moderate` для вашего аккаунта (см. [правила для групп, которые вы запускаете](/llms.mdx/docs/ru/tg/groups/content.md#rules)):

```sh
tg sales bot chats rules set -1001234567890 invites delete   # invite links to other chats: delete
tg sales bot chats moderate -1001234567890 --dry-run         # what breaks the rules, without acting
tg sales bot chats moderate -1001234567890                   # act as the rules allow
```

Бот проверяет только то, что `tg sales bot watch` сохранил или `bot messages sync` загрузил на этом компьютере. Вступления не проверяются. Удалённый участник не сможет вернуться по ссылке, если не задан `--no-block`. Правила лежат в том же файле, что и правила профиля личного аккаунта с таким же именем.

## Кнопки [#кнопки]

Когда человек нажимает кнопку под сообщением бота, бот получает идентификатор обратного вызова и отвечает на него:

```sh
tg sales bot callbacks answer <callback> --notification "Done"   # a note only the person who pressed sees
tg sales bot callbacks answer <callback> --text "Confirmed"      # replaces the message the button was on
```

`--text` заменяет сообщение, на кнопку которого нажали; нажатие должно быть сохранено через `bot watch`.

## Командное меню [#командное-меню]

Меню — это то, что люди видят после ввода `/` в чате с ботом.

```sh
tg sales bot commands set start=Begin "report=Today's report"
tg sales bot commands list
tg sales bot commands clear
```

Команда Telegram нуждается в описании.

## Вебхуки [#вебхуки]

Вебхук — это адрес, по которому Telegram отправляет все, что получает бот.

```sh
tg sales bot webhooks set https://bot.example.com/telegram --secret-stdin
tg sales bot webhooks list
tg sales bot webhooks delete https://bot.example.com/telegram
```

Бот содержит один вебхук; пока он установлен, `bot watch` ничего не получает, а `webhooks set` отклоняет второй адрес, пока первый не будет удален.

## Разрешённые получатели [#разрешённые-получатели]

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

```sh
tg sales bot recipients add -1001234567890    # a chat id
tg sales bot recipients add user:4815162342   # a person
tg sales bot recipients list
tg sales bot recipients remove -1001234567890
tg sales bot recipients clear                 # any chat again
```

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

```sh
tg sales bot sends list
```

Настройки бота, такие как часовой лимит на отправку, находятся в разделе `bot` файла конфигурации: `tg sales config set --bot sends_per_hour 200` (см. [configuration](/llms.mdx/docs/ru/tg/configuration/content.md)).

## Полный Bot API [#полный-bot-api]

`tg <bot> bot api <method>` предоставляет все методы в закрепленной схеме Telegram Bot API — все 185 из них, включая операции, выходящие за рамки удобных команд бота, описанных выше. В именах методов и полей используется формат kebab-case: `get-me`, `get-chat --chat-id <id>`. `tg bot api --help` перечисляет методы; В справке каждого метода перечислены его поля. Результаты сохраняют собственную структуру Telegram; целые числа за пределами безопасного диапазона JavaScript являются строками.

Передавайте поля отдельными флагами или в JSON: `--body <json>`, `--body -` (stdin)
либо `--body-file <path>`. `--body-file -` также читает stdin. Одно поле нельзя передавать
одновременно флагом и в теле JSON. Параметр API `timeout` задаётся через `--poll-timeout`;
глобальный `--timeout` ограничивает время выполнения всей команды.

Значение `@path` означает загрузку локального файла только в полях, объявленных файловыми
в схеме, включая вложенные поля массива `media` в JSON. В обычном тексте символ `@` сохраняется.
Защищённый путь в `@path` отклоняется до подключения; `bot api --allow-any-file` разрешает чтение таких путей во всех файловых полях вызова.
Секретные поля, например `secret_token` и `provider_token`, передаются через stdin или JSON-файл,
доступный только владельцу; отдельных флагов для них нет.

Операции используют `permissions.bot.api.<method>`, список получателей бота и журнал отправок.
Разрушительные действия по умолчанию требуют подтверждения. `get-updates` тоже требует его:
параметр смещения может подтвердить получение обновлений или пропустить их. Операция записи
без ответа сервера никогда не повторяется автоматически. Этот интерфейс требует соединения
с мессенджером и отказывается работать с `--offline`.

`get-managed-bot-token` и `replace-managed-bot-token` требуют `--store-token <profile>`.
Полученный токен сохраняется только в системном хранилище ключей и никогда не выводится.
Профиль назначения должен принадлежать указанному боту; это проверяется до смены токена на сервере.
После сохранения stdout содержит только профиль, идентификатор бота и `stored: "keyring"`.
Если хранилище ключей недоступно, операция завершается отказом, не сохраняя токен в файл.

## Когда бот отказывается или терпит неудачу [#когда-бот-отказывается-или-терпит-неудачу]

Отклоненная или неудачная команда указывает причину в сообщении об ошибке и заканчивается кодом:

| Код | Что случилось | Что делать |
|---|---|---|
| `4` | нет токена бота, или Telegram его не принял | снова запустите `bot auth set` |
| `5` | права профиля не позволяют боту это сделать | измените разрешение, только если вы хотите его разрешить |
| `6` | чат не найден — например, указано название, которое бот ещё не видел | используйте идентификатор чата или откройте чат с помощью `bot chats show` |
| `7` | чата нет в списке получателей бота, или никто не ответил на вопрос на уровне `ask` | добавьте чат с `bot recipients add` или запустите команду, где можно ответить |
| `8` | `sends_per_hour` бота израсходован | подождите или увеличьте лимит |
| `14` | ответ сервера не получен: неизвестно, отправил ли Telegram сообщение | проверяйте чат, прежде чем повторять его |

Каждый код находится в [ссылке на команду](/llms.mdx/docs/ru/tg/commands/content.md). `--trace` и `--record` тоже работают для бота: каждый запрос API бота представляет собой строку в stderr, а не его адрес, поскольку в нем находится токен. Неудачный запуск сохраняется и отображается в `tg personal runs list` вместе с каждым запросом к Bot API, его временем и повторами, если они были (см. [диагностика](/llms.mdx/docs/ru/tg/diagnostics/content.md)).

## Подключение бота к агенту (MCP) [#подключение-бота-к-агенту-mcp]

`tg <name> bot mcp serve` предоставляет бота вашему ИИ-агенту, а `tg personal mcp serve` обслуживает ваш аккаунт:

```sh
claude mcp add sales-bot -- tg sales bot mcp serve
tg sales bot mcp config          # the entry for Claude Desktop, Cursor and other apps
```

Агент получает все, что позволяют разрешения профиля бота, в разделе `bot.`: чаты, которые бот видел, сообщения, администраторы, меню команд, журнал и список получателей - и, если профиль не доступен только для чтения, писать от имени бота: отправлять, редактировать, закреплять, показывать индикатор набора текста, отвечать на нажатия кнопок, удалять, удалять участников. `permissions.bot: readonly` блокирует запись, если это не разрешено более конкретным правилом. Как и в других командах, `ask` и `allow` разрешают запрошенную запись MCP без формы подтверждения на сервере; `deny` и `readonly` блокируют его. Старые флаги подтверждения не действуют. По-прежнему применяется отдельное согласие правила модерации: действия, требующие его, возвращают план, который вы можете утвердить через CLI. `tg_bot_read` (`command: "status"`) говорит, какой профиль обслуживает сервер и какие действия записи доступны.

Прямым инструментам `bot api <operation>` требуется `permissions.bot.api: allow` (или `ask`); по умолчанию
действует `deny`, а `permissions.bot: allow` их не включает. Список команд сохраняет их и называет
недостающее разрешение, когда они недоступны. Эти вызовы обходят защиту отправки и
список получателей. Включайте их из терминала только когда агенту нужны неограниченные вызовы Bot API:

```sh
tg sales config set --bot permissions.bot.api allow
```

Каждый инструмент — та же команда, что в терминале, выполненная в процессе сервера, поэтому для защищённых команд действуют список получателей и журнал бота. Его аргументы — собственные аргументы и параметры команды в snake_case: `messages send` принимает `chat`, `text`, `md` или `html`, `reply_to` и `silent`.
Изменения вебхуков, меню команд и списка получателей остаются в списке команд; для выполнения нужны разрешения профиля бота, в том числе полномочия на изменения следующего запуска. Токеном вы управляете только в терминале. Инструменты агента не принимают файлы, `--allow-dangerous` и `--max-actions` модерации.

Бот использует для `--md` те же [правила форматирования Telegram](/llms.mdx/docs/ru/tg/usage/content.md#sending), что и личный аккаунт. Этот же форматтер применяется к правкам текста и подписям файлов и фотографий.
