Источники#

tgs sources позволяет перечислить и изучить диалоги Telegram в вашем аккаунте — каналы, супергруппы, группы, пользователей и ботов. Весь вывод в формате JSON, удобном для обработки через jq или AI-агентов.

Пайп в jq: диагностические логи ([tgs] retry: …, [tgs] FLOOD_WAIT: …) пишутся в stderr, а JSON — в stdout. При пайпе в jq глушите stderr, чтобы парсер не подавился:

tgs sources list --with-stats 2>/dev/null | jq '.sources[].title'

Избегайте 2>&1 | jq … — это смешает логи со stdout и сломает разбор JSON.

Список всех источников#

Самый простой вызов возвращает все диалоги в вашем аккаунте:

tgs sources list

Ответ — JSON-объект с массивом sources, полем total и опциональным cursor:

{
  "sources": [
    {
      "id": -1001234567890,
      "type": "channel",
      "title": "Durov's Channel",
      "username": "durov",
      "access": "public",
      "members_count": 1234567,
      "verified": true,
      "unread_count": 0,
      "last_message": {"id": 4321, "date": "2026-05-28T08:15:00Z"}
    }
  ],
  "total": 287
}

total — общее число диалогов в вашем аккаунте до применения фильтра --type. CLI гарантирует, что total >= len(sources) (счётчик Telegram бывает устаревший — мы поднимаем total до фактически возвращённого количества). Не делите total на длину массива — для пагинации используйте cursor.

Фильтр по типу#

Используйте --type для ограничения результатов по типу диалога. Можно передать один тип или несколько через запятую:

# Только каналы
tgs sources list --type channel

# Каналы и супергруппы
tgs sources list --type channel,supergroup

# Только боты
tgs sources list --type bot

Поддерживаемые типы: channel, supergroup, group, user, bot.

Получение полных метрик#

По умолчанию tgs sources list работает быстро и не делает лишних API-запросов. Добавьте --with-stats, чтобы получить статистику сообщений по каждому источнику:

tgs sources list --with-stats

Каждый источник в ответе будет содержать объект stats:

{
  "stats": {
    "total_messages": 12345,
    "messages_24h": 3,
    "first_message": {"id": 1, "date": "2015-08-26T10:00:00Z"}
  }
}

first_message — best-effort: для broadcast-каналов Telegram MTProto иногда не возвращает самое первое сообщение, и поле просто отсутствует. total_messages и messages_24h присутствуют всегда.

Заметка о производительности: --with-stats делает примерно 4 API-запроса на источник, а messages_24h обходит историю сообщений (до ~1000 шт.) до пересечения порога 24 часа — у гипер-активных источников значение упирается в этот лимит. Для больших аккаунтов это может занять несколько минут. Статистика неактивных источников (последнее сообщение старше 7 дней) кешируется на диске и используется повторно между запусками.

Изучение одного источника#

tgs sources inspect даёт полную картину по одному источнику. Работает как для подписанных каналов, так и для публичных, на которые вы не подписаны:

# По username
tgs sources inspect @durov

# По числовому Telegram ID — используйте префикс `id:` (голый "-1001234…" будет
# съеден парсером CLI как флаг; используйте `id:` или разделитель `--`).
tgs sources inspect id:-1001234567890

# Разделитель `--` тоже работает, но всё после него считается позиционным —
# флаги команды должны идти ДО `--`:
tgs sources inspect --no-stats -- -1001234567890

# Ваше «Избранное» (Saved Messages)
tgs sources inspect -

В ответе появляются дополнительные поля, недоступные в list: subscribed, description, creation_date, invite_link. для broadcast-каналов creation_date отражает дату создания канала; для пользователей это поле опускается (Telegram не отдаёт дату регистрации пользователя).

Ограничение числовых ID: числовой ID работает только если этот peer был ранее разрешён через @username или +телефон (этот вызов кладёт access_hash в локальный peer-кеш). Обычный tgs sources list peer-кеш НЕ наполняет. Если inspect числового ID падает с “peer is not in the local cache”, сделайте сначала один inspect @<username> (или +<phone>), затем повторите id:<n>.

Изучение канала без подписки#

Зная @username, вы можете изучить любой публичный канал, не вступая в него:

tgs sources inspect @somebigtechchannel

В ответе subscribed будет false, а ключ stats будет полностью отсутствовать в JSON. Остальные отображаемые поля (title, username, access, members_count, description, verified) подтягиваются из публичной информации канала.

Чтобы пропустить получение статистики (быстрее):

tgs sources inspect @durov --no-stats

Пагинация для больших аккаунтов#

Если у вас сотни диалогов, используйте --limit и --cursor для постраничного обхода:

# Первая страница
tgs sources list --limit 50

В ответе будет строка cursor. Передайте её для получения следующей страницы:

tgs sources list --limit 50 --cursor "eyJvIjo1MCwiZCI6MH0"

Когда страниц больше нет, ключ cursor полностью отсутствует в JSON (он не возвращается со значением ""). Цикл выше корректно обрабатывает это через jq -r '.cursor? // empty'.

Типичный цикл пагинации в shell-скрипте:

cursor=""
while true; do
  if [ -z "$cursor" ]; then
    result=$(tgs sources list --limit 50)
  else
    result=$(tgs sources list --limit 50 --cursor "$cursor")
  fi

  echo "$result" | jq '.sources[]'

  cursor=$(echo "$result" | jq -r '.cursor? // empty')
  [ -z "$cursor" ] && break
done

Архивированные диалоги#

Архивированные диалоги по умолчанию скрыты из списка. Передайте --archived, чтобы включить их:

tgs sources list --archived

Папки#

В Telegram пользователи могут группировать диалоги по папкам — это вкладки в официальном клиенте. tgs sources folders перечисляет ваши папки и разворачивает содержащиеся в каждой из них чаты, повторяя то, что показывает UI:

tgs sources folders

Стандартная вкладка «Все чаты» в вывод не попадает — только пользовательские папки и совместные чатлисты.

Содержимое папки всегда включает её архивные чаты: папка — это представление, которое может охватывать архив, поэтому tgs sources folders (и любая команда с --folder) раскрывает каждого участника независимо от того, в архиве он или нет. Отдельного флага для этого нет.

Зная нужную папку, передавайте --folder в другие команды, чтобы ограничить выборку её содержимым. Принимается числовой ID папки или её имя (без учёта регистра):

# Список чатов из папки «Crypto»
tgs sources list --folder Crypto

# То же, по числовому ID
tgs sources list --folder 3

Как использовать --folder в поисковых командах — см. раздел Фильтр по папке в руководстве по поиску.

Полная справка#

Backward Поиск Справочник Forward