МессенджерыTelegram

Telegram: Боты

Telegram: Подключение бота, публикации, кнопки и работа с его чатами.

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

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

Создайте бота через @BotFather и получите его токен.

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

Установка инструмента →

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

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

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

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

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

Выбрать профиль бота →

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

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

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

Что умеет Bot API →

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

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

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

  • Бот — это отдельный аккаунт Telegram, которым управляет программа. tg personal bot работает с ним через официальный Bot API Telegram. К вашему собственному аккаунту это не имеет никакого отношения: у бота есть свое имя, свои чаты и свой токен, а tg … без слова bot — это все равно вы (см. использование своего аккаунта).
  • Токен — это пароль бота. Вы создаете бота с помощью @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

Каждая команда и параметр находятся в справке по командам.

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

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 не может начать разговор с тем, кто ему не писал.

  • Группа или канал. Добавьте бота, напишите сообщение и посмотрите события:

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

    Каждая строка содержит chat_id. Бот без прав администратора видит в группе только команды и ответы ему, если режим приватности не отключён через @BotFather.

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

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

Несколько ботов

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

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>, отдельно от личной сессии. Если хранилища ключей нет, используется файл, доступный только вам.

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 нумерует сообщения внутри каждого чата.

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). --md и --html несовместимы. Удаление спрашивает подтверждение; --allow-dangerous подтверждает. Закрепление тихое без --notify. Отправка возвращает сообщение и operation_id записи в журнале. Telegram разрешает удалять только сообщения моложе 48 часов.

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

Файлы

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

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 МБ (отправка файлов).

Чаты

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

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

Администраторы и участники

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

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 или часть имени.

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. Отправка и bot watch продолжают работать через Bot API; получение обновлений в сессии истории отключено. Команда ничего не отправляет и не отмечает прочитанным.

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

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 для ботов действуют: короткое ожидание выполняется, длительное завершает запуск, чтобы вы могли продолжить позже.

События в чатах бота

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 для вашего аккаунта (см. правила для групп, которые вы запускаете):

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. Правила лежат в том же файле, что и правила профиля личного аккаунта с таким же именем.

Кнопки

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

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.

Командное меню

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

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

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

Вебхуки

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

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 отклоняет второй адрес, пока первый не будет удален.

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

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

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

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

tg sales bot sends list

Настройки бота, такие как часовой лимит на отправку, находятся в разделе bot файла конфигурации: tg sales config set --bot sends_per_hour 200 (см. configuration).

Полный 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 или запустите команду, где можно ответить
8sends_per_hour бота израсходованподождите или увеличьте лимит
14ответ сервера не получен: неизвестно, отправил ли Telegram сообщениепроверяйте чат, прежде чем повторять его

Каждый код находится в ссылке на команду. --trace и --record тоже работают для бота: каждый запрос API бота представляет собой строку в stderr, а не его адрес, поскольку в нем находится токен. Неудачный запуск сохраняется и отображается в tg personal runs list вместе с каждым запросом к Bot API, его временем и повторами, если они были (см. диагностика).

Подключение бота к агенту (MCP)

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

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:

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, что и личный аккаунт. Этот же форматтер применяется к правкам текста и подписям файлов и фотографий.