Telegram: Боты
Telegram: Подключение бота, публикации, кнопки и работа с его чатами.
На этой странице вы подключите бота к инструменту командной строки, проверите доступ к чату и подготовите первое сообщение. Бот — отдельный аккаунт мессенджера, который принимает сообщения и выполняет заданные действия: отвечает пользователям, публикует объявления и показывает кнопки. С помощью инструмента командной строки вы или ваш ИИ-агент можете действовать от имени своего бота. Это удобно для обращений клиентов, новостей сообщества и записи на мероприятия.
Первое подключение
Создайте бота через @BotFather и получите его токен.
Как создать бота через BotFather
- Откройте @BotFather в Telegram, нажмите «Запустить» и отправьте /newbot.
- Укажите отображаемое имя бота, затем свободное имя пользователя с окончанием bot, например my_club_helper_bot.
- BotFather пришлёт токен — ключ доступа к боту. Используйте его в команде подключения ниже.
- Установите инструмент командной строки, если он ещё не установлен.
- В командах ниже sales — имя отдельного профиля бота. Введите первую команду и вставьте токен в скрытое поле терминала. Токен можно передать агенту, но он останется в истории переписки. По возможности выполните эту команду сами и введите токен в терминале.
- Выполните вторую команду: она покажет имя подключённого бота. Добавьте бота в нужную группу или канал и выдайте права для вашей задачи.
tg sales bot auth set
tg sales bot auth showКогда имя бота совпадает с ожидаемым, переходите к проверке доступа и первому сообщению ниже.
Проверить, какой бот подключён
Используй tg CLI с профилем моего бота sales. Покажи имя бота и проверь доступ к группе «Клуб». Объясни, что он может делать и каких прав не хватает. Ничего не отправляй и не меняй.Ожидайте имя бота, выбранную группу и понятное объяснение доступа. Имя должно совпадать с ботом, которого вы подключили выше.
Подготовить сообщение с кнопками
Используй tg CLI с профилем бота sales. Подготовь объявление для группы «Клуб» с кнопками «Записаться» и «Подробнее». Покажи текст и предложенные действия кнопок. Пока ничего не отправляй.Проверьте текст, ссылки и действие каждой кнопки. Публикация от бота — отдельное действие; бот должен быть добавлен в выбранный чат и иметь нужный доступ.
Команды и инструкции
Используйте эту страницу, если у вас есть бот Telegram или вы хотите его иметь, и он вам нужен, чтобы публиковать сообщения, отвечать людям, смотреть группу или поддерживать там порядок. Вы узнаете, как подключить бота к tg, найти его чаты, отправлять и читать сообщения от имени бота, ограничивать места, где он может писать, и передавать бота своему ИИ-агенту.
Несколько слов на этой странице:
- Бот — это отдельный аккаунт Telegram, которым управляет программа.
tg personal botработает с ним через официальный Bot API Telegram. К вашему собственному аккаунту это не имеет никакого отношения: у бота есть свое имя, свои чаты и свой токен, аtg …без словаbot— это все равно вы (см. использование своего аккаунта). - Токен — это пароль бота. Вы создаете бота с помощью @BotFather в Telegram, и он дает вам токен.
- Имя бота — это слово, под которым вы хотите сохранить токен бота, например
sales. Это первое слово каждой команды бота:tg sales bot …. - Локальная копия — это то, что бот отправил, получил или импортировал и сохранил на этом компьютере. Telegram не предоставляет боту историю сообщений, поэтому для чтения старых сообщений используется эта копия.
Что можно сделать
Каждая команда и параметр находятся в справке по командам.
Первое подключение
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_querywatch сначала сохраняет событие, затем выводит: сообщения — в локальную историю бота, нажатия кнопок — для 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".
Если хранилище ключей недоступно, операция завершается отказом, не сохраняя токен в файл.
Когда бот отказывается или терпит неудачу
Отклоненная или неудачная команда указывает причину в сообщении об ошибке и заканчивается кодом:
Каждый код находится в ссылке на команду. --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, что и личный аккаунт. Этот же форматтер применяется к правкам текста и подписям файлов и фотографий.