Telegram: Личный аккаунт
Telegram: Читайте переписку, находите договорённости, собирайте документы и готовьте ответы с подключённым мессенджером.
Соберите контекст для конкретного решения: что изменилось, какие материалы нужны и кому ответить. Выберите задачу, подставьте свои чаты и отправьте запрос агенту. Для первого короткого запроса откройте «Первые задачи»; здесь — задачи, в которых нужно сопоставить несколько сообщений.
Что изменилось, пока меня не было
Используй tg CLI. Я не читал рабочую группу три дня. Сравни последние договорённости с теми, что были до моего отсутствия: сроки, объём работы и ответственные. Покажи только изменения, спорные места и сообщения-источники. Ничего не отправляй.Вы получите список «было → стало», а не пересказ всех сообщений. Например: срок перенесли с пятницы на понедельник; новый срок подтвердили, а нового ответственного пока только предложили.
Собрать пакет материалов для встречи
Используй tg CLI. Найди в рабочей группе и переписке с Анной материалы для завтрашней встречи: актуальную презентацию, расчёт стоимости и список открытых вопросов. Для каждого файла покажи сообщение с последним согласованием. Сначала покажи список, не скачивай и ничего не отправляй.Вы получите список нужных файлов с объяснением, какая версия согласована, и вопросы для повестки. Потом попросите сохранить выбранные файлы в указанную папку.
Разобраться в долгом обсуждении
Используй tg CLI. В группе родителей найди обсуждение поездки за последний месяц. Собери в одном ответе дату, место встречи, стоимость и что нужно взять. Отдели подтверждённые решения от предложений, приложи исходные сообщения. Ничего не отправляй.Вместо десятков сообщений получите памятку. Если место встречи обсуждали, но не выбрали, агент оставит этот вопрос открытым.
Проверить обещания перед ответом
Используй tg CLI. Перед ответом подрядчику проверь нашу личную переписку и группу ремонта за две недели. Что мы обещали друг другу, что уже выполнено и что ещё нужно уточнить? Подготовь ответ со ссылками на договорённости. Покажи черновик без отправки.Вы получите проверяемый список обязательств и черновик, который учитывает обе переписки. Даты и обещания без подтверждения должны остаться вопросами.
Команды и инструкции
tg позволяет вам или вашему ИИ-агенту читать сообщения и выполнять действия от своего аккаунта Telegram через терминал. Эта страница показывает работу с аккаунтом: от первого входа до чтения, отправки и управления группами в том порядке, в котором они вам понадобятся. Откройте эту страницу, когда начнете с tg или когда захотите узнать, что возможно, прежде чем спрашивать своего агента.
Прочитав эту страницу, вы узнаете, как назвать чат, как читать и искать так, чтобы никто не видел, что вы просматриваете, как безопасно отправлять сообщения и как получать ответы, которые может использовать скрипт. Каждая команда и параметр находятся в справке по командам; на этой странице объясняется, как они сочетаются друг с другом.
Термины, используемые на этой странице:
- Профиль: один вход в аккаунт Telegram на этом компьютере, со своей сессией и настройками. Его выбирает первое слово команды (profiles).
- Чат: любой разговор — индивидуальный чат, группа, канал или сохраненные сообщения.
- Локальное хранилище: база данных на этом компьютере, где tg хранит все прочитанные сообщения (локальное хранилище).
- Защита отправки: проверка каждой отправки — профиль только для чтения, список разрешенных получателей и часовой лимит (защита отправки).
Каждая команда выполняет одно действие, выводит результат и выходит. Только tg personal watch, tg personal serve и tg personal mcp serve продолжают работать и сообщают об этом.
Ниже схема команды, а не команда для копирования. Вместо обозначений в скобках подставляют значения, как в примерах ниже.
tg [profile] [options] <resource> <action> [arguments]Что можно сделать
Прочитайте чат с агентом
После подключения аккаунта попросите короткий итог переписки. Эта задача читает сообщения и ничего не отправляет.
Ваш запрос:
Подведи итог пяти последних сообщений Book club. Покажи решения и открытые вопросы. Ничего не отправляй.
Команда:
tg personal messages list "Book club" --limit 5 --jsonПример ответа агента:
Решили: следующая встреча в четверг в 18:00.
Открыто: где встречаться.
Могу показать сообщения, на которых основан итог. Ничего не отправлено.
Резюме выше является вымышленным. Попросите агента открыть исходное сообщение, прежде чем полагаться на его интерпретацию. Настройка, действия с сообщениями и разрешения описаны в разделах ниже.
Начало работы
npm install -g @wirecat/tg-clitg skill install --for all # the agent skilltg personal setup # guided app registration, login and agent skilltg personal chats list --limit 5 # your newest chatstg personal messages list me # Saved Messages, the latest 20Выделите около пяти минут на настройку. Загрузка истории осуществляется отдельно: выберите чат и объём истории для tg personal messages sync <chat> --last 100. Агент может прочитать tg skill show без входа в систему; tg personal setup --agent codex явно выбирает навык для одного агента. tg setup --help объясняет флаги. Больше ничего читать не нужно.
Чтобы узнать параметры для задачи, выполните tg commands search messages --json для одной
команды или tg commands messages --json для группы. Оба ответа содержат глобальные параметры
и коды завершения. Каждый путь команды проверяйте отдельным вызовом;
tg commands --json возвращает всё дерево.
Вход
tg personal setup — команда первого запуска. По умолчанию она автоматически регистрирует приложение и предлагает вход по QR; --app browser и --method phone выбирают альтернативы. Для входа без остальных шагов либо для завершения прерванного или истёкшего входа используйте:
tg personal session start # QR code: Settings → Devices → Link Desktop Devicetg personal session start phone # phone number, the code Telegram sends, your 2FA passwordtg personal session start phone --sms # the same, asking for the code by SMS instead of in the apptg personal session start qr # without a terminal (an agent): the QR code as text to paste into the chatПри первом входе также запрашивается ваше собственное приложение Telegram с сайта my.telegram.org; --app auto заполняет сайт за вас. Оба шага, и что где хранится: логин, сессии и профили.
Секреты не передаются аргументами. Хеш приложения и пароль 2FA вводятся скрыто, код и телефон — по запросу или через stdin. Аргументы видны процессам в ps и остаются в истории оболочки.
В CI переменные TG_API_ID и TG_API_HASH передают данные приложения вместо хранилища ключей и имеют приоритет над ним.
tg personal account show # who this profile is logged in as, with the phone number
tg personal account show --hide-phone # the same without the phone numbertg account list # every profile on this computer and the account each is logged in astg personal account sessions list # every device and app logged in to the account; ends nothingtg personal session end # log out on Telegram's side, and delete the session heresession end завершает сессию и в Telegram: устройство исчезает из списка. Для завершения с другого устройства используйте Настройки → Устройства.
Профили: первое слово
Можно использовать несколько аккаунтов. Профиль задаётся первым словом, а не параметром:
tg personal chats list # profile "personal"tg work chats list # profile "work"
export TG_PROFILE=work # or for a whole shell sessionПервое слово считается профилем, если это не команда. Имя chats запрещено с пояснением причины. Допустимы буквы, цифры, точки, дефисы и подчёркивания.
Каждый профиль имеет свою сессию, свое приложение, свои настройки и свой список разрешенных получателей. TG_PROFILE_LOCK привязывает процесс к одному профилю, поэтому агент не может выбрать профиль с меньшими ограничениями (профили).
Как указать чат
Везде, где команда принимает <chat>, доступны:
- название или часть:
"Book club",book - идентификатор:
-1001234567890 - имя пользователя:
@example_channel meдля «Избранного»
Если название подходит нескольким чатам, ошибка перечисляет их с идентификаторами. tg не угадывает: отправку в неверный чат нельзя отменить. Повторите с идентификатором. Он не меняется, поэтому используйте его дальше.
messages show и messages context также принимают указатель msg: вместо чата и идентификатора сообщения. Его возвращает search messages --json для каждого результата.
Для человека (<person> в contacts show) можно указать идентификатор, @username или часть имени.
Чтение
Чтение не отмечает сообщения прочитанными. Команды ниже не показывают собеседнику ваш просмотр. Это делает только tg personal chats mark-read (ниже).
Чаты
tg personal chats list # newest first, archived chats includedtg personal chats list 'unread_count>0 kind:group' --offline # only groups with unread messagestg personal chats list 'title:*book*' --offline # titles containing "book"; at least 3 characterstg personal chats show "Book club" # kind, unread count, last message, who is in itЗапрос по чатам выполняется по локальному архиву, поэтому ему нужен --offline: онлайн Telegram ничего не фильтрует. kind: принимает dialog (личный чат), group, channel, saved. Для групп и каналов есть отдельный раздел.
Сообщения
tg personal messages list "Book club" # the latest 20, oldest firsttg personal messages list "Book club" --limit 50tg personal messages list "Hiking" topic:12 # one forum topic; topics list shows the idstg personal messages show "Book club" 4242 # one messagetg personal messages context "Book club" 4242 # it, and 5 messages either sidetg personal messages context "Book club" 4242 --before-n 2 --after-n 10В context выбранное сообщение отмечается ◀ в терминале и "anchor": true в JSON.
topic:<id> в запросе читает сообщения темы от самого нового назад или от id<…. Общая тема (1) не принимается: Telegram не присваивает её сообщениям ID темы, поэтому читайте весь чат. С --offline условие topic: оставляет только сохранённые сообщения этой темы.
Ссылки на сообщения
tg personal messages link <chat> <message> или tg personal messages link <msg:locator> возвращает { item: { ref, url, access, reason } }. Постоянные ссылки каналов и супергрупп могут быть общедоступными или ограниченными; ссылка не дает членства. Диалоги, основные группы и сохраненные сообщения возвращают локатор. Offline проверяет сохраненную цель и не возвращает постоянную ссылку. Локатор другого аккаунта отклонен. Эта единственная команда отличается от messages links, которая объясняет взаимоотношения диалога (поиск темы).
Что требует ответа
tg personal inbox # other people's unread messages, in every chattg personal inbox 'date>2h' # everything that came in during the last two hourstg personal inbox --new # what arrived since the last --new — for scheduled runstg personal inbox --new --jsonl # the same for a script: one message per lineinbox показывает только чужие сообщения с указанием чата. Чаты без уведомлений и архив пропускаются, кроме упоминаний и ответов вам; --all включает их. Число пропущенных выводится в stderr.
inbox --new сдвигает сохранённую позицию. Следующий --new продолжает с неё, показывая сообщения один раз. Первый --new охватывает 24 часа. inbox без --new и inbox 'date>…' позицию не меняют. Обычный inbox повторяет результат, пока сообщения не прочитаны в приложении: сам он не отмечает прочитанным.
За запуск читаются максимум 20 чатов. Остальные попадают в запись missing с шагом, который читает такой чат. Если ожидающих сообщений больше --limit, показываются самые новые, а stderr объясняет, как прочитать остальные.
Обязательства и ожидания: review
tg personal review # the last 3 daystg personal review 'date>"2026-09-23T09:00:00+02:00"' # from where the last review endedtg personal review 'chat:"Book club"' --jsonВсе сообщения — ваши и чужие — в чатах с активностью после date> в запросе. Они помогают понять обещания, ожидания и неясности; классификацию выполняете вы или агент. Отметки прочитанного нет.
Первый шаг next в ответе, review.next, — это следующая проверка: она начинается там, где закончилась эта
(date>"<until>"). Следующую проверку запускайте с этого шага, чтобы не было пропусков. При неполном результате — слишком много чатов или ограничение последними 300 сообщениями — команда предупреждает; границу лучше не сдвигать. Максимум 20 чатов за запуск.
Вопросы без ответа
tg personal review --unanswered # questions nobody answered in 24 hourstg personal review 'chat:Neighbours' --unanswered 4h--unanswered [duration] оставляет вопросы, ожидающие вас или администраторов группы. Вопрос — сообщение с ? (знак ? в ссылках не учитывается) или ответ вам/администратору. Он закрыт, если вы или администратор ответили либо написали следом за автором. Вопросы моложе указанного срока (по умолчанию 24 часа) исключаются. Если администраторы неизвестны, учитываются только ваши ответы и выводится предупреждение. Указывайте длительность, например 4h или 1d; число часов без единицы не принимается.
Сохраненные голосовые расшифровки также учитываются в этом фильтре. Добавьте --transcribe, чтобы расшифровывать голосовые сообщения, у которых нет сохраненной расшифровки, перед выбором вопросов. Голосовое сообщение, которое не удалось расшифровать, делает обзор неполным: пустой результат не означает, что вопросов без ответа нет. Сохраняйте предыдущую границу, пока в ответе есть запись missing.
Голосовые сообщения
tg personal messages transcribe "Book club" 4242 # by Telegram where it can, else a model heretg personal messages transcribe "Book club" 4242 --local # only the model on this machinetg personal messages list "Book club" --transcribe # every voice message shown that has no text yettg personal inbox --transcribetg personal review --transcribetg personal messages list "Book club" --transcribe --model gigaam-v3Локальная расшифровка принимает полную запись Ogg Opus с одним или двумя каналами без фиксированного ограничения в десять минут. Более длинным записям нужно больше памяти и времени на обработку.
Telegram распознаёт речь для Premium и несколько сообщений в неделю по пробной квоте. Иначе работает локальная модель без передачи записи с компьютера. Модель скачивается один раз и только по запросу:
tg personal models list kind:audio # the models, which is downloaded, which is the defaulttg personal models download parakeet-v3 # once, checked against the sha256 this version expects| Модель | Языки | Размер |
|---|---|---|
parakeet-v3 — по умолчанию | 25: болгарский, чешский, датский, немецкий, греческий, английский, испанский, эстонский, финский, французский, хорватский, венгерский, итальянский, литовский, латышский, мальтийский, нидерландский, польский, португальский, румынский, русский, словацкий, словенский, шведский, украинский | 670 МБ |
gigaam-v3 | русский — лучшая из трёх моделей для русского | 232 МБ |
gigaam-v3-ctc | русский — немного быстрее, хуже с заглавными буквами | 225 МБ |
--model выбирает другую модель для одной команды, рядом с --transcribe или в messages transcribe; transcribe_with и speech_model в настройках выбирают значения по умолчанию (конфигурация). Расшифровка хранится в локальном хранилище и повторно используется в списках сообщений, входящих и проверках. Повторный вызов messages transcribe может запросить новую расшифровку или снова запустить распознавание. --transcribe может занять несколько минут.
Файлы
tg personal messages download "Book club" 4242 --output-dir ~/Downloads # one message's filestg personal messages download "Book club" --all --output-dir ~/tg-files # every file of the chat, newest firstФотографии, файлы, видео и голосовые заметки сохраняются; папка создается, если она отсутствует. Файл сохраняет свое собственное имя; тот, у кого нет имени, получает идентификатор сообщения. Загрузка никогда не перезаписывает файл. При использовании --all перед уже занятым именем ставится идентификатор сообщения. --all запоминает место остановки в небольшом файле рядом с загрузками и продолжает выполнение той же команды оттуда. Сохраненные файлы доступны для чтения только вам. Отправка файлов, форматов и текста с возможностью поиска: вложения файлов.
Люди
tg personal contacts list # people you have a one-to-one chat with, newest firsttg personal contacts list 'name:*ann*' --order nametg personal contacts show @example_user # their bio and the chats you sharetg personal contacts lookup # who has a phone number — asks for it, or reads it from stdintg personal contacts sync # your whole Telegram contact list into the local storetg personal contacts show @example_user # flags, last seen, registered, messages per shared chattg personal contacts context @example_user --chat "Book club" # their latest messages theretg personal contacts check @example_user # does the account look like a bot or a spammercontacts list — это люди, с которыми вы общаетесь один на один. contacts sync также добавляет остальную часть вашего списка контактов Telegram. name: и notes: ищут людей, которых хранит локальное хранилище, поэтому сначала нужен
contacts sync (или ранее прочитанные сообщения); если ничего не сохранено, запрос отклоняется. notes: и search notes находят любую часть слова, в любом регистре, в том числе в заголовке; запрос из одного или двух символов отклоняется ("search needs at least three characters"). contacts lookup никогда не принимает число в качестве аргумента: передавайте его по конвейеру или вводите по запросу. Профиль человека, его последние сообщения, проверка бота и что он куда отправляет: люди.
Изменение контактов и собственного профиля:
tg personal contacts add @example_user # under the name they showtg personal contacts rename @example_user Ann "from work" # a name only you seetg personal contacts remove @example_user # the chat staystg personal contacts block @example_user # they need not be a contacttg personal contacts unblock @example_usertg personal contacts import people.txt # one "number, name" per line; never numbers as argumentstg personal account update --first-name Ann --description "about me" --photo me.jpgtg personal account sessions end --others # logs out every other device, your phone too; asks firstcontacts import возвращает количество и найденных Telegram людей, без телефонов. account sessions end спрашивает подтверждение; --yes подтверждает в скрипте.
Страницы
Списки показывают limit строк (по умолчанию 20). chats list, contacts list, chats members list и topics принимают --page и --all:
tg personal contacts list --limit 5 # five a pagetg personal contacts list --limit 5 --page 2 # the sixth to the tenthtg personal contacts list --all # every row, no paging⚠ Нумерация страниц живого списка может повторить или пропустить строку. Новое сообщение между запросами сдвигает чаты через границу страниц.
У сообщений чата нет страниц: они принимают запрос по id и date, а для следующей страницы — --cursor, что дает точное продолжение:
tg personal messages list "Book club" "id<4242" # older than message 4242tg personal messages list "Book club" "id>4242" # newer than 4242, oldest firsttg personal messages list "Book club" "date>2h" # what came in during the last two hourstg personal messages list "Book club" 'date>"2026-09-20T09:00:00+02:00"'tg personal messages list "Book club" "date<1d" # what came before this time yesterdayВ терминале строка со следующей страницей идёт в stderr; в JSON это шаг page.next, который дает --cursor. id< и id> принимают идентификатор сообщения. date> и date< — ISO 8601 или период назад: 30m, 2h, 1d. В messages context параметры --before-n, --after-n задают число сообщений вокруг выбранного.
Найти чат и написать в него
tg personal chats list 'title:*book* kind:group' --offline # groups with "book" in the titletg personal contacts list 'name:*ann*' # people by name or @usernametg personal search all "contract" # messages and notes kept here, and Telegram's own searchtg personal search all "contract" --offline # only this computer; the query never leaves ittg personal search messages "contract" # the text of every message this machine has kepttg personal search messages 'contract chat:"Book club"'tg personal search messages 'body:/.*invoice.*(march|april).*/'Для поиска чата и контактов необходимо минимум три символа. search messages использует язык поисковых запросов: invoice также находит другие формы слова, invoic* соответствует началу, а exact:invoice только эту форму. Он читает то, что было получено или сохранено serve, а также запрашивает собственный поиск Telegram (--backend archive только для архива). body:/…/ сопоставляет регулярное выражение со всем текстом сообщения. Подробнее: поиск сообщений. Если у вас есть чат, используйте его идентификатор.
Отправка
Ничего не отправляется, пока вы не введете отправляющую команду, и оно не запрашивает подтверждения: чат и текст уже находятся в введенной вами строке. Каждая отправка проходит через защиту отправки: профиль только для чтения, список профиля allow, список разрешенных получателей и часовой лимит (защита отправки). Записывается каждая попытка, а не ее текст: tg personal sends list.
tg personal messages send me "a note to myself"tg personal messages send "Book club" "See you at 7" --silent # no notificationtg personal messages send "Book club" "a link, no card" --no-previewtg personal messages send "Book club" "**Bold** and _italic_" --md # Telegram Markdowntg personal messages send "Book club" "<b>Bold</b> and <i>italic</i>" --html--md использует форматтер Telegram: **bold** или *bold*, _italic_, __underline__, ~~struck~~ или ~struck~, ||spoiler||, встроенный код, изолированный код с языком, [label](https://example.com) и цитаты — строки, начинающиеся с > . Стили могут быть вложенными; code/pre не может вкладываться в другие объекты, ссылки не могут вкладываться, а цитаты не могут быть вложены. Без флага текст остается в том виде, в котором он был набран. Обратная косая черта экранирует знак; Внутренние слова _ и * остаются буквальными. Незакрытые знаки оформления внутри строки остаются буквальными; незакрытый блок кода запрещен. Ссылки поддерживают абсолютные URL-адреса http, https и mailto. messages edit и подписи мультимедиа используют один и тот же форматтер. Telegram __text__ подчеркнута; MAX __text__ выделен жирным шрифтом. Одиночный *text* в Telegram выделен жирным шрифтом.
--html обрабатывает текст как HTML Telegram, такой же, как в Bot API: <b>, <i>, <u>, <s>, <a href>, <code>, <pre language="…">, <blockquote> и <tg-spoiler>. Переносы строк и пробелы сохраняются как введены. Ссылка-упоминание (tg://user?id=) или пользовательский эмодзи отклоняются. --md и --html нельзя использовать вместе. messages edit тоже принимает --html.
Текст через stdin
Если аргумент текста отсутствует, он читается из stdin. Так можно отправить несколько строк и не оставлять текст в ps и истории оболочки:
printf 'first line\n\nthird line' | tg personal messages send me
tg personal messages send "Book club" < note.txtОтложенная отправка
tg personal messages send "Book club" "Tomorrow" --at-time 2026-10-01T09:00 # local timetg personal messages send "Book club" "In two hours" --at-time 2h # or 30m, 1d from nowtg personal messages scheduled "Book club" # what waits to be sent there--at-time передаёт сообщение Telegram, который отправит его даже при выключенном компьютере. Время округляется вниз до минуты. Менее минуты или более года вперёд запрещено. Сообщение учитывается в лимите в час отправки. Отмена и изменение доступны в приложении Telegram; tg этого не делает.
Файлы, фото и голосовые
tg personal messages send "Book club" "The agenda" --file agenda.pdf # byte for byte; the text is the captiontg personal messages send "Book club" --photo picture.jpg # recompressed by Telegramtg personal messages send "Book club" --file trip.mp4 # a video plays in the chattg personal messages send "Book club" --file trip.mp4 --as-file # the same video as a file to downloadtg personal messages send "Book club" --voice note.ogg # a voice message, alone, with no texttg personal messages send "Book club" --file 3f9a.pdf --filename "Report Q3.pdf" # the name others seeПовторите --photo или --file, чтобы отправить до десяти вложений одним альбомом. Фотографии и видео можно объединять; документы должны идти отдельной группой. Голосовые сообщения отправляются отдельно. Подпись относится к первому элементу, каждый элемент учитывается в часовом лимите отправок. JSON содержит первое message и полный список messages.
tg personal messages send "Book club" "Trip photos" --photo first.jpg --photo second.jpg--photo принимает .jpg, .png, .webp. .mp4 и .mov с --file отправляются как видео, если нет --as-file. --voice принимает Ogg Opus (.ogg, .oga, .opus) без текста и других файлов. Известные файлы и папки с учётными данными, собственные папки tg и локальное хранилище защищены. Обычные скрытые рабочие папки разрешены; --allow-any-file в CLI позволяет использовать защищённые пути.
--spoiler размывает фотографию или видео до тех пор, пока на них не нажмут; документ и голосовое сообщение этот параметр не принимают. --caption-above показывает текст над фотографией или файлом. Telegram позволяет только ботам останавливать пересылку одного сообщения; для защиты контента включите собственную настройку чата в Telegram. Форматы, загрузки и текстовый поиск внутри файлов: вложения файлов.
Ответ на сообщение
tg personal messages send "Book club" "Agreed" --reply-to 4242Ответ — разновидность отправки; доступны все её параметры.
Реакции и опросы
tg personal reactions add "Book club" 4242 👍 # replaces the reaction you hadtg personal reactions remove "Book club" 4242tg personal reactions list "Book club" 4242 reaction:🔥 --limit 20 # who reacted, newest first; --cursor goes ontg personal polls show "Book club" 4250 # the poll and its answer idstg personal polls voters "Book club" 4250 'answers:<answer id>' # who chose it; not in an anonymous polltg personal polls vote "Book club" 4250 <answer id>tg personal polls vote "Book club" 4250 --retracttg personal polls create "Book club" "Which day?" Monday Tuesday --anonymoustg personal polls create "Book club" "Pizza now?" yes no --close-time 5m # closes by itself; 5s to 10mtg personal polls close "Book club" 4250 # your own poll; it cannot be reopenedtg personal polls create "Book club" "2+2?" 3 4 5 --quiz --correct 2 --solution "Four." # a quiz; a vote is finalПри чтении чата реакции отображаются под сообщением — 👍 3 🔥 1 (you: 🔥). reactions list называет тех, кто отреагировал; Telegram отказывает в канале и в чате, который скрывает список, а ошибка называет причину (reactions.broadcast, reactions.list-hidden) вместо пустого ответа. Голос в публичном опросе показывает ваше имя всем участникам чата. Голосуйте по ID из polls show, а не по порядковому номеру ответа. --multiple позволяет выбирать несколько ответов. Изменить голос можно только в опросе, созданном с --revote. Голосование в закрытом опросе, два ответа в опросе с одним вариантом, изменение или отзыв окончательного голоса и --retract без голоса отклоняются до отправки; закрытие чужого опроса тоже отклоняется.
Боты и их кнопки
Используйте, когда бот отвечает кнопками под сообщением или нужно запустить бота либо открыть его мини-приложение.
tg personal messages show "Shop bot" 4300 # the buttons are numbered under the messagetg personal messages press "Shop bot" 4300 2 # button 2, counted from 1 across the rows
tg personal messages press "Shop bot" 4300 "Order" # or by its exact texttg personal chats start "Shop bot" --start ref7 # the same as its Start button; the bot sees it
tg personal chats start "https://t.me/shop_bot?start=ref7" # a bot's link, even one you never opened
tg personal chats app "Shop bot" --start go # the address of its mini app, signed in as youБот видит, что вы нажали кнопку или запустили его. press работает только с callback-кнопками. Кнопка, запрашивающая ваш пароль 2FA, ссылка, кнопка, отправляющая ваш номер телефона или местоположение, и кнопка, открывающая мини-приложение, отклоняются до отправки. Адрес, который печатает chats app, входит в приложение бота от вашего имени: никому его не показывайте.
Правка, пересылка, закрепление, удаление
tg personal messages edit "Book club" 4242 "the corrected text" # your own message; --md or --html as in a sendtg personal messages forward "Book club" 4242 --to me # checked against the chat it goes totg personal messages forward "Book club" 4242 --to "Hiking" --topic 12 # into one topic of a forumtg personal messages pin "Book club" 4242 # quiet unless --notifytg personal messages unpin "Book club" 4242tg personal messages delete me 4242 4243 --allow-dangerous # at most 10, for you onlytg personal messages delete me 4242 --allow-dangerous --for-everyoneРедактирование меняет текст, который могли уже прочитать. Пересылка создаёт новое сообщение и проверяется по чату назначения как отправка. Удаление необратимо и требует ответа y или --allow-dangerous. В супергруппах и каналах Telegram удаляет только у всех, поэтому нужен --for-everyone.
Что учитывается в почасовом лимите: сообщение, пересылка, редактирование, закрепление с уведомлением, новый опрос, закрытие опроса и каждое удалённое сообщение. Реакция, голос и тихое закрепление не учитываются.
Неизвестный результат отправки
Код 14 означает обрыв после отправки: сообщение могло уйти. Ошибка содержит --operation-id. Повторите с ним: Telegram исключит дубликат.
tg personal messages send "Book club" "See you at 7" --operation-id <id from the error>tg personal messages forward "Book club" 4242 --to me --operation-id <id from the error>Пересылка и опрос тоже получают идентификатор. Повтор без него создаст второе сообщение. Файл загружается до отправки сообщения: оборванную загрузку tg повторяет три раза, и если она так и не удалась, в ошибке сказано, что ничего не отправлено, — такую команду можно просто запустить снова. Другие записи — закрепление, реакция, отметка о прочтении, удаление, голос, папки, контакты — так же завершаются кодом 14, когда Telegram не отвечает; сообщение говорит, безопасно ли повторять. Создание папки повторять небезопасно: сначала посмотрите tg personal chats folders list, иначе папок может стать две. Отправка с --at-time не повторяется: проверьте tg personal messages scheduled <chat>.
Ваш список чатов: архив, закрепление, непрочитанное, звук
tg personal chats archive "Book club" # into the archive; `unarchive` brings it backtg personal chats pin "Book club" # to the top of your list; `unpin` lets it move downtg personal chats mark-unread "Book club" # the dot on your own devices; nobody sees ittg personal chats mute "Book club" --until 2h # without --until, for good; `unmute` hears it againЭто меняет только ваш список и уведомления; никому в чате об этом не сообщается. Telegram отклоняет закрепление сверх лимита закреплённых чатов, закрепление в архиве тоже отклоняется.
Отметка прочитанным
tg personal chats mark-read "Book club" # up to the newest messagetg personal chats mark-read "Book club" --until-id 4242 # only up to this onetg personal chats mark-read "Hiking" --topic 12 # only this forum topictg personal messages list "Book club" # read without sending a receiptСобеседник видит прочтение. Действие read проходит защиту, но не входит в часовой лимит.
Папки
tg personal chats folders list # your folders, in the order the app shows themtg personal chats folders show "Trips" # one folder, with the names of its chatstg personal chats folders create "Trips" --chat "Hiking" --chat @katetg personal chats folders update "Trips" --title "Travel" --add "Climbing" --remove @katetg personal chats folders delete "Travel" # the chats staytg personal chats folders order "Travel" "Work" # these first; the rest keep their order after themtg personal chats folders join https://t.me/addlist/AbCdEf # a folder someone shared: joins every chat in ittg personal chats folders create "Inbox" --include contacts,groups --skip muted,archived --emoji 📥tg personal chats folders update "Inbox" --exclude-chat "Noisy group" --pin @katetg personal chats folders update "Inbox" --include none # no kinds any more; only the chats named in itПапка может автоматически включать типы contacts, non-contacts, groups, channels, bots через --include; --skip исключает muted, read, archived. --exclude-chat исключает конкретный чат, --pin закрепляет его сверху. При update --include и --skip заменяют прежние правила; --remove удаляет чат из всех списков. Общая папка по ссылке не принимает правила. --emoji должен быть значком папки Telegram: другой Telegram молча отбросит, и ответ покажет реально сохранённое значение.
Папка указывается по ID или точному названию. Папки видите только вы; каждое изменение всё равно проходит проверки как изменение account. join отличается: участники этих чатов видят, что вы вступили, как при tg personal chats join. Папка «Все чаты» сохраняет своё место при order.
Комментарии к постам канала
tg personal messages comments "Rozetked" 27644 # the comments under post 27644, oldest firsttg personal messages comments "Rozetked" 27644 "id<3732413"tg personal messages send "My channel" "Thanks!" --comment-to 120Комментарии находятся в группе обсуждения канала: ответ указывает её в discussion, а комментарий отправляется как ответ в этой группе, поэтому список получателей и почасовой лимит учитывают его для неё. Пост канала без группы обсуждения или с закрытыми комментариями приводит к завершению с кодом 6.
Отправка от имени канала
В группе, где вы можете писать от имени одного из своих каналов, сначала получите список доступных отправителей, затем выберите одного:
tg personal chats send-as "Book club"tg personal messages send "Book club" "Meeting moved to 8" --send-as <id from the list>В списке всегда есть вы, а default отмечает сохранённый выбор группы; чтение ничего не меняет. ID, которого нет в списке, отклоняется. --send-as работает и с файлами, tg personal messages forward и tg personal polls create — для пересылки нужен список чата из --to. При повторении операции с неизвестным результатом передайте тот же --send-as вместе с --operation-id.
В группе канал может быть сохранён как отправитель по умолчанию — Telegram делает это для группы обсуждения вашего канала. В такой группе отправка, пересылка или опрос без --send-as отклоняются (код 2), чтобы не уйти от имени канала: ошибка предлагает --send-as <your id> для отправки от вашего имени и --send-as <channel id> — от имени канала.
Чего пока нет в tg
Отправка стикеров и геопозиции остаётся в планах. Несколько фотографий или видео уже можно отправить одним альбомом, повторив --photo или --file.
Сохранить ответ для проверки
Черновик Telegram позволяет проверить текст в приложении и самостоятельно нажать «Отправить»:
tg personal messages send me "Review this text" --draft
tg personal messages send CHAT "A **formatted** reply" --draft --md --reply-to MESSAGE_IDКоманда заменяет существующий черновик в чате или теме форума и не отправляет сообщение. С черновиками работают --topic, --reply-to, --md, --html и --no-preview. Сохранением управляет отдельное разрешение drafts. Пустой текст, вложения, отложенная отправка и другие параметры только для отправки отклоняются; команда не очищает черновики. В результате возвращается saved: true, а не отправленное сообщение.
Группы и каналы
Все для группы, которую вы ведёте — правила модерации, проверки, полный список настроек — находится в группы, которые вы ведёте.
tg personal chats inspect https://t.me/+AbCdEf # where an invite or public link leads; does not jointg personal chats members list "Hiking" --all # everyone, with their role and when last seentg personal chats events "Hiking" # who joined, left, was added or removed — 7 daystg personal chats events "Hiking" 'time>="2026-09-01T00:00:00+02:00"'tg personal topics list "Hiking" # a forum group's topics, newest activity firsttg personal search topics "Hiking" "gear"tg personal topics show "Hiking" 12 # one topic: title, closed or pinned, last activitytg personal review 'chat:Hiking' --unanswered # questions nobody answeredЭти команды только читают. events читает служебные сообщения чата: кто что сделал и кому. Имена: join, leave, add, remove, create, title и pin.
Это что-то меняет, и люди в чате это видят.
Для форума используйте tg personal topics enable <chat> и tg personal topics create <chat> <title>. Базовая группа требует --upgrade --yes; сохраните новый идентификатор чата, возвращенный обновлением. Прочитайте topics list после неизвестного результата создания вместо повторения создания. Отправьте на его идентификатор с помощью tg personal messages send <chat> <text> --topic <id> или tg personal polls create <chat> <question> <answers> --topic <id>. tg personal topics edit <chat> <id> --title <new> переименовывает тему, --closed on/--closed off закрывает ее для новых сообщений или открывает заново, --pinned on/--pinned off закрепляет ее вверху или открепляет, а на общей теме (id 1) --hidden on/--hidden off скрывает ее из списка тем или возвращает её в список. --emoji <emoji> задаёт теме значок, в topics edit и в topics create. Эмодзи должен входить в стандартный набор значков тем Telegram, доступный любому аккаунту; tg personal topics icons list показывает его, а другой эмодзи отклоняется вместе с этим списком. topics edit --emoji none убирает значок. tg personal topics order <chat> <id...> размещает закрепленные темы в указанном порядке; он ничего не закрепляет и не открепляет. Правку и порядок тем можно безопасно повторять. Если исход создания неизвестен, сначала проверьте список тем, прежде чем создавать снова. tg personal topics delete <chat> <id> удаляет тему и каждое сообщение в ней для всех; его нельзя отменить, поэтому по умолчанию он сначала запрашивает; явный topics.delete: allow или --allow-dangerous пропускает вопрос. Общая тема не может быть удалена.
tg personal chats create "Hiking 2027" @olga 12345 # a supergroup; the people added are toldtg personal chats create "Trail news" --channel # a channel; people join it by its linktg personal chats join https://t.me/+AbCdEf # by an invite link, or a public onetg personal chats leave "Hiking 2027"tg personal chats update "Hiking 2027" --title "Hiking 2028" --description "routes and dates"tg personal chats update "Hiking 2027" --all-can-pin off --only-admins-add ontg personal chats links show "Hiking 2027" # the invite link, if you may see ittg personal chats links reset "Hiking 2027" # a new one; the old one stops workingtg personal chats links create "Hiking 2027" --approval --expire-time 7d # another link; who joins asks firsttg personal chats links create "Hiking 2027" --max-uses 20 # at most 20 people join by ittg personal chats update "Hiking 2027" --join-approval on # everyone asks first, by any linktg personal chats requests list "Hiking 2027" # who asked to join, newest firsttg personal chats requests list "Hiking 2027" 'name:*Ana*' # by name; or link:<link>tg personal chats requests confirm "Hiking 2027" 67890 # let them in; decline turns them awaytg personal chats requests reject "Hiking 2027" --all # every pending request at once; --link narrows ittg personal chats links list "Hiking 2027" # your links, with how many joined and how many waittg personal chats links remove "Hiking 2027" https://t.me/+AbCd # stop one linktg personal chats links update "Hiking 2027" https://t.me/+AbCd --no-approval --max-uses 50 # change only thesetg personal chats members add "Hiking 2027" @kate 67890 # they are toldtg personal chats members remove "Hiking 2027" @kate # their messages staytg personal chats admins add "Hiking 2027" @kate --can pin,deletetg personal chats admins remove "Hiking 2027" @kateНовая группа — это всегда супергруппа. Имя человека, чьи настройки конфиденциальности запрещают его добавление, указано в ответе под provider_metadata.not_added; группа все равно создается. chats join в группу, администраторы которой одобряют присоединение, отвечает requested: true и завершается с кодом 0: запрос отправлен, и вы попадаете в него, как только администратор его примет. Каждый из них проходит через охрану как изменение chat, и каждый добавленный человек засчитывается в почасовой лимит.
chats links create создает еще одну ссылку-приглашение и никому не сообщает: --approval заставляет того, кто присоединится по ней, спросить подтвердить вступление, --expire-time задаёт срок действия (2026-12-01T09:00 или 30m, 2h, 7d с этого момента), а --max-uses ограничивает число вступлений. chats links update меняет одни и те же три на одной из ваших ссылок, а также на собственной ссылке группы (--no-approval отключает одобрение, --expire-time never отменяет срок действия); неуказанные настройки сохраняются. Ссылка с одобрением вступления, не имеет ограничения на использование, поэтому --approval с --max-uses отклоняется. chats update --join-approval on заставляет всех спрашивать первыми, какую бы ссылку они ни использовали.
В группе, администраторы которой одобряют присоединение, chats requests list показывает ожидающие запросы с примечанием, отправленным пользователем; их видят только админы, а чтение никому не говорит. Запрос сужает список: name: или username: находит людей, link: оставляет тех, кто спросил, по одной ссылке-приглашению; Telegram не может делать и то, и другое одновременно. confirm и reject отвечают на один, по идентификатору из списка. Принятый запрос учитывается в почасовом лимите, отклоненный — нет; список получателей проверяет только группу. Тому, кто уже является участником, отвечают already: true, а отсутствующий запрос заканчивается выходом 6. --all отвечает на каждый ожидающий запрос, а с --link — на те, которые пришли по одной ссылке; они учитываются в первую очередь, и прием, превышающий часовой лимит, отклоняется до того, как кого-либо впустят. chats links list показывает только ваши собственные ссылки; отзыв собственной ссылки группы приводит к тому, что Telegram выдает новую, о чем свидетельствует ответ.
chats update меняет заголовок, описание и две настройки Telegram за один раз; ответом является группа в ее нынешнем виде, и chats show показывает те же настройки. Правила модерации — chats rules и chats moderate — находятся в правилах модерации.
Вывод: таблицы, JSON и коды выхода
На терминале tg печатает таблицу; в канал или с помощью --json он печатает одно значение JSON на стандартный вывод и ничего больше — ни счетчика, ни галочки, ни предупреждения. Примечания, предупреждения и ошибки передаются в поток stderr в каждом режиме. Именно это позволяет сценарию или вашему агенту полагаться на ответ.
tg personal chats list --json | jq -r '.items[].id'tg personal messages list me --jsonl | jq -r 'select(.type == "item") | .data.text' # message text from item records--json: одно значение JSON. Каждый список представляет собой один объект всегда одной и той же формы:{ "items": [...], "page": { "limit": 20, "has_more": true }, "meta": { ... } }; если строк больше, список называет следующий шаг вpage.next.--allи--offlineотвечают одним и тем же объектом. Одна сущность, а не список, — это{ "item": {...}, "meta": {...} }.- Сообщения чата листаются через
--cursor, а не по номеру страницы; его несетpage.next. --jsonl: записи элементов содержат результат вdata; последняя запись завершения содержит полноту и данные страницы. Проверяйте её, а не считайте поток набором сообщений без оболочки. Отчёт (stats …) — один объект, поэтому--jsonlдля него отклоняется; спискиstats * evidenceпо-прежнему выдаются потоком.- Ошибка выдаёт
{ "error": { "code": "...", "message": "..." } }в stderr. Отказ до начала вывода не пишет результат, поэтому его нельзя принять за пустой ответ. Если поток уже выдал записи, сохраните их и проверьте запись завершения; отсутствие такой записи тоже означает незавершённый поток. - Частичное чтение и скачивание может завершиться с кодом
0: проверьтеcompleteиbatchилиissue; JSONL частичной загрузки добавляетbatch_summary. - Переход по коду выхода, а не по тексту. Текст меняется; код этого не делает.
0сработал,2неправильный ввод,4не вошел в систему,5профиль не может этого сделать,6не найден,7нет в списке разрешенных получателей,8установлен лимит (почасовой лимит или собственный Telegram),9Telegram не ответил вовремя,14неизвестно, дошло ли сообщение. Полная таблица находится в кодах выхода. - Идентификаторы — это строки. Не преобразуйте идентификатор в число.
--quietскрывает обычные сообщения о работе; ошибки остаются.-vи-vvдобавляют детали к представлению таблицы.--timeout 30sограничивает всю команду (500ms,30sили2m).tg commands --json— это все дерево команд, сeffects: { remote, local }для каждой команды:remote: "write"значит, что команда что-то меняет в Telegram.
if tg personal messages send "Book club" "See you at 7" --json > /dev/null; then
:
else
send_status=$?
case "$send_status" in
14) echo "it may have gone — repeat only with the same --operation-id" ;;
4) echo "run tg personal session start" ;;
esac
fiПодключите своего ИИ-агента
ИИ-агент, выполняющий команды в терминале (например, Claude Code, Codex или Gemini CLI), читает файл навыков tg: правила и ловушки, которые --help не может объяснить. tg personal setup устанавливает его, как и tg skill install (--for claude, agents или all, по умолчанию). Чтобы установить его вручную:
mkdir -p ~/.claude/skills/tg-cli && tg skill show > ~/.claude/skills/tg-cli/SKILL.md # Claude Code
mkdir -p ~/.agents/skills/tg-cli && tg skill show > ~/.agents/skills/tg-cli/SKILL.md # Codex, Gemini CLIЛокальный Cursor тоже читает ~/.agents/skills/tg-cli/. Установленные инструкции берутся из той же версии пакета, что и tg. Если агент не видит навык, начните новую сессию агента. Как каждый агент находит навыки: Codex, Gemini CLI, Cursor.
Агент без терминала (например, Claude Desktop или Cursor) подключается через MCP: сервер MCP.
Отображение переписки
tg personal messages list и tg personal search messages в терминале выводят переписку, а не таблицу:
10:05:12 Anna
Shall we call on Thursday?
10:09:03 Boris
↳ Anna: Shall we call on Thursday?
Thursday works.
📎 photo
edited 10:09:30Время локальное, новый день отмечен строкой. ↳ — исходное сообщение ответа, ↪ — автор пересланного, 📎 — вложение. Управляющие символы показываются текстом и не исполняются. Пересланная карточка контакта печатается как 👤 с именем и телефоном; в JSON у вложения есть contact с полями name, first_name, last_name, phone (целиком, как прислал Telegram) и user_id, и хранилище её сохраняет, так что --offline показывает то же. -v добавляет идентификаторы сообщения, автора и чата; -vv — все известные данные.
Новые сообщения в реальном времени
tg personal watch # new messages, until Ctrl-C or --timeouttg personal watch --jsonl # one {"type":"item","data":message} line per message, then a {"type":"end"} linetg personal watch --jsonl | ./on-message.shtg personal watch --events --jsonl # edits, deletions and reactions tootg personal watch --jsonl --timeout 2m # a timeout ends it normally, with exit code 0Каждая строка имеет вид {"type":"item","data":…}; последняя — {"type":"end","complete":true} либо false после ошибки, которая также задаёт код завершения. Поля записаны в snake_case. С --events каждый data указывает свой event: message, edit, delete или reaction. Без параметра data содержит само сообщение. При удалении в личном чате или небольшой группе Telegram не сообщает чат, поэтому он отсутствует.
watch начинается с этого момента. То, что поступило, пока ничего не прослушивалось, не отображается. Чтобы поддерживать актуальность локального хранилища, включая все, что поступило, пока этот компьютер был выключен, используйте serve в фоновом режиме или в качестве системной службы (поддержание актуальности хранилища):
tg personal server start # serve in the background; answers once it is connectedtg personal server statustg personal server install # a systemd user unit or a launchd agent that starts at every login; starts nothing nowЧто сделала команда
tg personal --trace chats list # also show each request on stderrtg personal --no-record chats list # keep nothing of this runtg personal runs list # what was kept, newest firstНеудачный запуск всегда сохраняется. Запись содержит операции, идентификаторы, количество и продолжительность — но не сообщение, имя, заголовок чата, номер телефона или ключ. Полностью: диагностика.
Локальная база
Все прочитанные tg данные сохраняются на компьютере для работы без сети:
tg personal chats list --offline # only from the store, never connecttg personal messages sync "Project Alpha" --dry-run # how much a fetch would taketg personal messages sync "Project Alpha" --background # a chat's history, as a jobtg personal store export "Project Alpha" --format markdown --output alpha.mdtg personal store backup ~/tg-store.db # a copy of the store, while it is in useОбычная команда все равно запрашивает Telegram. --offline предназначен для случаев, когда сети нет или подключение не требуется; отправка с --offline отклонена. Извлечение, экспорт, поиск, резервное копирование и сервис: локальный архив.
Настройки и разрешения профиля
Настройки хранятся в необязательном config.json. Приоритет: параметр → переменная окружения → профиль в файле → общие значения файла → встроенное значение.
tg config show # every setting, and where it came fromtg personal config set limit 50tg work config set permissions.messages readonly # profile "work" changes no messagestg personal config set permissions.messages.send ask # a yes or no before each sendtg personal config set sends_per_hour 10permissions сообщает, что профиль может делать для каждой команды: deny, readonly, ask или allow. По умолчанию все разрешено, а удаление сообщений и завершение сессий спрашивается в первую очередь. Отказ — это код выхода 5, а в ошибке указывается команда, которая это разрешает. В файле нет поля для секрета. Каждая настройка и переменная: конфигурация.
Один человек
tg personal contacts show <person> показывает, что Telegram говорит об одном человеке и насколько он активен в чатах, которыми вы делитесь. tg personal contacts check <person> оценивает их как возможных ботов, фейков или спамеров по всем причинам. tg personal contacts context <person> считывает информацию о них в архиве: без --chat, для каждого аккаунта, связанного с ними с помощью contacts link; с --chat, их новейшими сообщениями в каждом названном вами чате. Что каждый спрашивает в Telegram или общедоступном спам-листе, и что он куда отправляет: люди.
Несколько ограничений, которые следует знать: предполагаемая дата регистрации определяется на основе идентификатора аккаунта с таблицей сообщества, которая заканчивается августом 2026 года; для более новых ID оценки нет. Проверка бота считывает до 1000 сохраненных сообщений. contacts context возвращает тела сообщений, поэтому он соответствует разрешениям messages; связывание и отключение идентификаторов контролируется contacts и никогда не меняет адресную книгу Telegram.
Дальше
- Локальный архив: поиск, получение истории чата, экспорт, резервное копирование.
- Конфигурация: настройки и возможности профиля.
- Безопасность: то, что достигает диска, и защита отправки.
- Сценарии: обычная работа для вашего ИИ-агента.