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

Язык поисковых запросов Telegram

Все поля, операторы, пресеты и ограничения поиска сообщений Telegram: правила дат, регулярные выражения и JSON-ответ для скриптов и агентов.

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

Если вы используете ИИ-агента с tg, вам не нужно учить этот язык: опишите, что вы хотите, простыми словами, и агент напишет запрос. Эта страница предназначена для людей, которые сами вводят поисковые запросы, и для всех, кому нужны все фильтры: точные операторы, каждое поле, предустановки, правила дат и ограничения.

Это справочник для запросов tg personal search messages, tg personal search all, tg personal stats messages show, сохраненные поисковые запросы и --filter тематического поиска. Для повседневных примеров начните с поиск сообщений.

Термины, используемые на этой странице:

  • Запрос: текст, который вы ищете, например invoice from:me date:7d.
  • Поле: имя и двоеточие, которые ограничивают одну часть запроса одним свойством сообщения, например from: (отправитель) или date: (когда оно было отправлено). Слова без поля ищут текст сообщения.
  • Оператор: слово или знак, объединяющий условия, например AND, OR и NOT.
  • Словоформы: одно и то же слово с разными окончаниями. piso и pisos — формы одного слова.

Язык представляет собой строгий профиль синтаксиса запросов Apache Lucene: слова, фразы, AND/OR/NOT, группы, поля, диапазоны, ограниченные подстановочные знаки и регулярные выражения. «Строгий» означает, что все, что он не поддерживает, является ошибкой, которую никогда не игнорируют молча. В полном справочнике (пока только на русском языке) есть сгенерированные таблицы полей, операторов, пресетов и лимитов, а также исполняемые примеры; техническая спецификация описывает грамматику и компилятор.

Для почты chat: выбирает цепочку писем по id или теме; from: выбирает отправителя. У почты нет kind: и topic:.

Что можно выразить

Вы хотитеНаписать
сообщения со всеми этими словами в любой формеinvoice paid
эти слова вместе, в таком порядке"invoice paid"
то или иное слово, без третьего(cafe OR library) NOT loud
только эта точная форма словаexact:piso или --exact для каждого слова без поля
слова, начинающиеся с чего-тоinvo*
отправитель, чат, разновидность чатаfrom:me, chat:"Book club", kind:private
периодdate:7d, date:[2026-01-01 TO 2026-02-01}
файлы по имени, типу или размеруfilename:*.pdf, mime:image, size>10MB
текст, похожий на пароль, карту или телефонpreset:secret, preset:card
ваши меткиtag:work
шаблонtext:/pass(port)?/

Слова и словосочетания без полей соответствуют словоформам. --exact выбирает точные формы слов без полей; явный text: по-прежнему соответствует формам. Языковые настройки архива определяют, какие формы совпадают (формы слов).

Операторы

ОператорПримерЗначение
словаinvoice paidоба слова
фраза"invoice paid"слова в этом порядке
AND, &&alpha AND betaоба
OR, ||alpha OR betaлюбое из двух
NOT, !, -alpha NOT betaпервое без второго
++alpha OR betaalpha обязательно, beta необязательно
группа(alpha OR beta) gammaскобки задают порядок
группа поляfrom:(alice OR bob)поле применяется к каждому значению
диапазонdate:[2026-01-01 TO 2026-02-01}[ ] включают, { } исключают, * — открытая граница
сравнениеsize>10MB, date>=7d, date:>=7dоткрытый диапазон; форма с двоеточием означает то же самое
подстановкаinvo*, te?t* — любые символы, ? — один
регулярное выражениеtext:/pass(port)?/ограниченное регулярное выражение Lucene

alpha OR beta gamma означает (alpha OR beta) AND gamma; alpha OR beta AND gamma означает alpha OR (beta AND gamma). Используйте скобки для ясности. Строчные буквы and, or, not — это простые слова. Запрос только с NOT ничего не находит: укажите положительное условие, например kind:group NOT preset:secret. Нечёткий поиск ~, поиск по близости, повышение веса и интервалы отклоняются с ошибкой, а не игнорируются. Опечатки не исправляются: чтобы охватить разные окончания, используйте подстановочный знак, например invo*.

Поля

ПолеЧто находитПример
textслова сообщения (поле по умолчанию)text:invoice
exactточная форма слова или фразыexact:piso, exact:"invoice paid"
bodyвесь исходный текст с учётом регистраbody:/.*invoice.*/
fromотправителя по имени, @username или идентификатору; me — это выfrom:"Alice Synthetic"
chatчат по названию, @username или идентификаторуchat:"Book club"
dateвремя отправкиdate:today, date:7d, date:[2026-01-01 TO 2026-02-01}
kindвид чата: private, group, channel, saved, bot, service, unknownkind:private
hasattachment, link, file, photo, image, video, audio, voice, sticker, contact, location, pollhas:file
topicодну тему форума; нужен один чатchat:"Book club" AND topic:42
inкакие аккаунты: провайдер или botsin:bots
presetтекст, похожий на секрет или контактные данныеpreset:secret
contentпроиндексированный текст вложенийcontent:invoice
filenameполное имя прикреплённого файлаfilename:*.pdf
mimeтип прикреплённого файла; значение без / сравнивается с первой частьюmime:image
sizeразмер прикреплённого файла в байтах или в KB/MB/GB по 1024size>10MB
tagваша локальная метка на сообщении, его чате или отправителеtag:work
phoneномер телефона в тексте, как бы он ни был записанphone:"+34 600 000 000"
emailадрес почты в текстеemail:ana@example.com
urlссылку в тексте, без параметров отслеживанияurl:"https://example.com/a"
domainсайт ссылки или адреса в текстеdomain:example.com
mentionsчеловека, организацию или документ, с которым вы связали найденное упоминаниеmentions:"person:12"

Имена полей чувствительны к регистру. Неизвестное поле, значение или комбинация — это ошибка, а не пустой ответ и никогда не простой текст. Имя, которое архиву неизвестно, не ищется в Telegram.

kind:bot выбирает чат с ботом; in:bots выбирает архивы аккаунтов tg personal bot. topic: требует ровно одного чата в chat:, поскольку номера тем в разных группах повторяются. filename, mime и size подходят сообщению, если подходит хотя бы один из его файлов. / начинает регулярное выражение, поэтому полный тип заключайте в кавычки: mime:"application/pdf".

Упоминания

tg находит в сохранённых сообщениях телефоны, адреса почты, ссылки, документы и имена людей. Эти поля находят сообщения, в которых они есть. Сами находки показывает tg personal mentions list.

tg personal search messages 'phone:"+34 600 000 000"'
tg personal search messages 'email:ana@example.com OR domain:example.com'
tg personal search messages 'mentions:"person:12"'

Значение с + или @ берите в кавычки: оба знака — операторы. Телефон находится, как бы он ни был записан: +34 600 000 000 и 600000000 — один телефон, а номер без + читается по странам из настройки phone_countries. domain: считает docs.example.com тем же, что example.com. mentions: принимает ссылку на человека, организацию или документ и находит сообщения, упоминания в которых вы связали с ним через tg mentions confirm.

Пресеты

Пресет находит текст по его форме. Используйте его, чтобы найти пароль, код или номер карты, который кто-то прислал.

ПресетКандидат — это
passwordподпись пароля, за которой следует значение
codeподпись кода подтверждения и 4–8 цифр
api-keyподпись ключа API и значение
secretподпись пароля, секрета, токена или ключа API и значение
card13–19 цифр, возможно с пробелами или дефисами
bankзначение в формате IBAN
passportзначение с подписью «паспорт» или российский формат 4+6 цифр
phoneмеждународный телефон, начинающийся с плюса
emailадрес электронной почты
telegram-linkссылка t.me или telegram.me
urlссылка HTTP(S)
contactвложение-контакт, либо адрес почты или телефон
locationвложение-место или ссылка geo:

Пресет сообщает о кандидате по его виду. Он не проверяет пароль, карту или документ и может совпасть с чем-то безобидным. Не удаляйте и не пересылайте сообщения автоматически на основании пресета.

Даты

--timezone принимает часовой пояс IANA, например Europe/Madrid; без него используется пояс компьютера, и он возвращается в ответе. Дата без времени — целый календарный день. Включающая верхняя граница охватывает весь этот день, исключающая — не включает его; день перевода часов может длиться 23 или 25 часов.

date:today и date:yesterday — календарные дни. date:7d означает от 7 дней назад до текущего момента (также 30m, 2h); date>=7d и date:[30d TO 7d} работают в сравнениях и диапазонах и отсчитываются от момента запуска запроса. Точное время заключайте в кавычки, с секундами и смещением: date>="2026-01-01T10:00:00+02:00".

Слова, подстановки и регулярные выражения

Перед индексацией и поиском текст нормализуется: нижний регистр, без диакритических знаков. Побочный эффект: некоторые разные слова становятся одинаковыми, например año и ano. Регулярные выражения и подстановки в text: нормализуются так же.

text:/pay/ находит целое слово pay, но не payment. body:/pay/ находит только сообщение, весь текст которого — pay, с учётом регистра; чтобы найти его в любом месте, используйте body:/.*pay.*/. Это синтаксис регулярных выражений Lucene, без проверок окружения JavaScript, обратных ссылок, якорей и флагов.

В большом архиве короткий префикс, такой как a*, может расширяться до более чем 10 000 слов и отклоняется; удлините его. Длинные запросы, глубокая вложенность и большие шаблоны отклоняются с query_limit, а не сокращаются. Поиск, который дольше своего лимита в 2 секунды, останавливается с timeout (причина query.time-limit): запрос верный, поэтому сузьте чат, даты или шаблон.

Ответ

--json возвращает { items, page: { limit, has_more }, next?, missing?, meta }, даже если совпадений нет. --jsonl выводит по одному элементу на строку, затем итоговую запись с полнотой результата и данными о страницах.

  • items: найденные сообщения, сначала лучшие (или сначала новые с --newest). У каждого есть ref (msg:…), timestamp, sender_name, excerpt и matched_in.
  • meta.accounts: какие аккаунты обыскивались.
  • missing: что ответ не смог увидеть, и для каждого пункта шаг, который это восполняет. coverage означает, что некоторые чаты в области ни разу не загружались или загрузка перед поиском остановилась раньше времени (шаг messages.sync); text означает, что индекс слов еще строится (шаг store.migrate, tg personal store migrate).
  • next: шаги, которые нужно выполнить. page.next повторяет запрос для следующей страницы.
  • page.has_more касается страницы, а не того, есть ли больше сообщений в Telegram.

Ошибка указывает место проблемы в запросе и даёт подсказку.

Через MCP

Когда агент выполняет поиск на сервере MCP tg, tg_read (command: "search messages") принимает запрос в query, а timezone для календарной зоны. chat принимает идентификатор или сохраненное имя; source, newest, context и limit работают так же, как и параметры команды; saved запускает сохраненный поиск. thread, thread_hops, thread_messages, thread_bytes, thread_within и sync_first соответствуют опциям --thread… и --sync-first; sync_first предлагается только с messages.sync-first: allow. Ответ имеет те же поля, что и --json. tg_read (command: "stats messages show") считает одни и те же запросы. История запросов следует за сервером: tg personal mcp serve --no-record или record, установленный на false, не записывает свои вызовы.

Дальше