Поиск#

tgs предоставляет четыре подкоманды поиска, которые напрямую отображаются на методы поиска MTProto в Telegram. Весь вывод — это JSON, что упрощает передачу в jq, скармливание AI-агенту или программную обработку.

Поиск в чате#

Самая частая операция: поиск сообщений в конкретном чате.

tgs search messages "docker compose" -c @devops_notes

Аргумент запроса обязателен. Флаг -c / --chat указывает, в каком чате искать. Все поддерживаемые форматы см. в разделе Резолв чатов ниже.

Несколько чатов#

Передайте несколько чатов, повторив флаг или указав значения через запятую:

# Повторение флага
tgs search messages "release" -c @frontend -c @backend

# Через запятую
tgs search messages "release" -c @frontend,@backend

tgs выполняет поиск по каждому чату последовательно и объединяет результаты в один JSON-ответ.

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

Используйте --from / -f, чтобы показать только сообщения от конкретного отправителя:

tgs search messages "bug" -c @dev_chat --from @alice

Значение --from принимает те же форматы, что и --chat (юзернейм, числовой ID, номер телефона или ссылка t.me).

Фильтр по типу контента#

Флаг --filter ограничивает результаты определённым типом сообщений. Доступно 15 фильтров:

Пример — найти все документы в канале:

tgs search messages "" -c @project_files --filter document

Пустой запрос ("") с фильтром возвращает все сообщения этого типа.

Фильтр по дате#

Сузьте результаты до диапазона дат с помощью --after и --before. Оба принимают два формата:

• Строка даты: YYYY-MM-DD (трактуется как полночь UTC)
• Unix-timestamp: количество секунд с начала эпохи

# Сообщения за январь 2025
tgs search messages "deploy" -c @ops --after 2025-01-01 --before 2025-02-01

# С использованием Unix-timestamp
tgs search messages "deploy" -c @ops --after 1704067200 --before 1706745600

Оба флага необязательны и могут использоваться независимо.

Темы форума#

Для супергрупп с включённым режимом форума используйте --topic, чтобы искать в конкретной теме по её ID:

tgs search messages "error" -c @dev_forum --topic 42

Без --topic поиск охватывает все темы форума.

Поиск по комментариям к постам канала#

У каналов в Telegram может быть связанная группа-дискуссия, где живут комментарии под каждым постом. Используйте --include-comments, чтобы одной командой автоматически искать и в канале, и в его группе-дискуссии — угадывать username группы не нужно:

tgs search messages "release" -c @somechannel --include-comments

Для каждого канала из --chat проверяется наличие связанной группы-дискуссии; если она есть, эта группа прозрачно добавляется к поиску. На каналы без комментариев флаг не влияет.

Результаты объединяют посты и комментарии, отсортированные по дате. Поле reply_to_msg_id у каждого комментария указывает на сообщение, на которое он отвечает, позволяя восстановить дерево обсуждения.

Глобальный поиск#

Ищите сразу по всем вашим чатам с помощью tgs search global:

tgs search global "meeting notes"

Сужение по типу чата#

Ограничьте глобальный поиск определёнными типами чатов:

# Только каналы
tgs search global "announcement" --channels-only

# Только группы
tgs search global "discussion" --groups-only

# Только личные чаты
tgs search global "hey" --users-only

Эти флаги взаимоисключающие — передача более одного одновременно отклоняется с ошибкой.

Поиск в архиве#

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

tgs search global "old thread" --archived

Глобальный поиск также поддерживает --filter, --after, --before, --limit и --cursor — так же, как search messages.

Счётчики контента#

Получите разбивку количества сообщений по типам для чата, не загружая сами сообщения:

tgs search counters -c @mychannel

Возвращаются счётчики для всех 15 типов фильтров. Чтобы запросить только определённые типы:

tgs search counters -c @mychannel --filters photo,video,document

Счётчики также поддерживают --topic для форумных групп.

Календарное представление#

Получите результаты поиска, сгруппированные по дате — удобно для понимания, когда был опубликован конкретный контент:

tgs search calendar -c @mychannel --filter photo

Для календарных запросов обязательны и --chat, и --filter. Ответ содержит список дат с соответствующим количеством сообщений и диапазоном ID сообщений (min_msg_id, max_msg_id) для каждой даты.

Фильтр по папке#

Все поисковые подкоманды принимают --folder <id|имя>, который ограничивает поиск чатами внутри пользовательской папки Telegram. --folder принимает числовой ID папки или имя папки без учёта регистра:

# Искать сообщения по всем чатам папки «Work»
tgs search messages "release notes" --folder Work

# Подсчитать медиа в чатах папки «Crypto»
tgs search counters --folder Crypto

# Календарный вид, ограниченный папкой
tgs search calendar --folder Crypto --filter photo

Под капотом tgs раскрывает папку в список её чатов и выполняет запрос к каждому из них (fan-out), объединяя результаты так же, как при поиске по нескольким чатам. В список разрешённых чатов всегда попадают архивные чаты папки — папка это представление, которое может охватывать архив, — поэтому при заданном --folder флаг --archived не нужен (и игнорируется).

Замечание для tgs search global: старый флаг --folder у search global (который выбирал основную папку или архив Telegram по числовому ID) заменён на --archived. Флаг --folder теперь единообразно обозначает пользовательские папки во всех подкомандах.

Чтобы просмотреть ваши папки и узнать их ID или точные имена, используйте tgs sources folders.

Курсорная пагинация#

tgs использует пагинацию на основе курсора, а не на основе смещения. Это соответствует нативному подходу Telegram и позволяет избежать пропущенных или дублированных результатов, когда во время пагинации приходят новые сообщения.

Каждый ответ поиска включает поле cursor (пустая строка, если результатов больше нет). Передайте его обратно с --cursor, чтобы получить следующую страницу:

# Первая страница (по умолчанию: 50 результатов)
tgs search messages "update" -c @news --limit 10

# Следующая страница с использованием курсора из предыдущего ответа
tgs search messages "update" -c @news --limit 10 --cursor "eyJvIjo1MCwiZCI6MH0"

Флаг --limit управляет размером страницы (1-100, по умолчанию 50).

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

cursor=""
while true; do
  if [ -z "$cursor" ]; then
    result=$(tgs search messages "query" -c @chat --limit 20)
  else
    result=$(tgs search messages "query" -c @chat --limit 20 --cursor "$cursor")
  fi

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

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

Резолв чатов#

tgs принимает несколько форматов для идентификации чатов, пользователей и групп:

Все они работают в --chat, --from и любом другом флаге, принимающем ссылку на пир.

Примечание: Инвайт-ссылки (t.me/+hash) не поддерживаются для поиска.

tgs кеширует разрешённые пиры локально, чтобы избежать лишних API-вызовов. Используйте --no-cache, чтобы обойти кеш, если подозреваете устаревшие данные. (search global разрешает пиры на стороне сервера и не имеет флага --no-cache.)

Обработка лимитов#

Telegram применяет ограничения частоты через ошибки FLOOD_WAIT, которые указывают, сколько секунд нужно подождать перед повторной попыткой. tgs обрабатывает это автоматически:

1. При получении FLOOD_WAIT tgs выводит предупреждение в stderr и засыпает на требуемое время.
2. После ожидания повторяет запрос.
3. Если требуемое ожидание превышает --max-wait (по умолчанию: 60 секунд), tgs немедленно возвращает ошибку вместо блокировки.

# Разрешить до 120 секунд ожидания flood wait
tgs search messages "query" -c @bigchannel --max-wait 120

# Быстрый отказ — не ждать дольше 5 секунд
tgs search messages "query" -c @bigchannel --max-wait 5

При временных сетевых ошибках tgs повторяет до 3 раз с экспоненциальным backoff и jitter. Постоянные ошибки (некорректный пир, недостаточно прав и т. д.) никогда не повторяются.

Полный справочник#

• tgs search messages — поиск в конкретных чатах
• tgs search global — поиск по всем чатам
• tgs search counters — разбивка количества сообщений по типам
• tgs search calendar — результаты поиска, сгруппированные по дате