Язык поисковых запросов 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 beta | alpha обязательно, 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*.
Поля
Имена полей чувствительны к регистру. Неизвестное поле, значение или комбинация — это ошибка, а не пустой ответ и никогда не простой текст. Имя, которое архиву неизвестно, не ищется в 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 и значение |
card | 13–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, не записывает свои вызовы.
Дальше
- Поиск сообщений: ежедневные поиски, сохраненные поиски и подсчет.
- Поиск по теме: найдите обсуждение по его смыслу, если вы не знаете его слов.