Довідка / Архів та інтеграції

Telegram · Командний рядок

Здійснюйте пошук, читайте контекст, підраховуйте активність та експортуйте збережені повідомлення зі скриптів та агентів із виведенням у форматі --json, стабільними кодами завершення та токенами з обмеженим доступом, призначеними лише для читання.

TgWitness / Документація

Інтеграції з архівами

MCP тільки для читання · Повнотекстовий пошук · Вікі

Попередній перегляд. tgwitness search, context, messages, stats та export читати збережені спостереження для скриптів та агентів штучного інтелекту. Вони не можуть надсилати нічого до Telegram, змінювати налаштування або модифікувати підписаний журнал.

При цьому --json, stdout передає саме один документ JSON (export записує рядки у форматі JSON). Інформація про хід виконання, підказки та помилки виводяться у stderr. Коди завершення є стабільними:

Код	Значення
`0`	Успіх, включаючи порожній результат
`1`	Помилка: недоступна панель, нечитабельні дані, перерваний експорт
`2`	Помилка використання або недійсний запит: неправильна дата, невідома опція, індекс пошуку вимкнено
`3`	Наразі недоступно: робоча область відкрита в активній панелі, або панель пропонує спробувати пізніше (обмеження частоти запитів, перевищення часу очікування)
`4`	Доступ відхилено: відсутній, прострочений або скасований токен; чат поза межами сфери дії; інструмент, який це не дозволяє

Два способи читання#

Через панель (--url). Команда використовує той самий API архіву з обмеженою областю дії, що й MCP. Створіть з’єднання в розділі «Інтеграції» → «MCP»: виберіть робочі простори та чати, інструменти та термін дії, а потім скопіюйте токен один раз. З’єднання є лише для читання, обмежене цими чатами, має обмеження швидкості до 60 запитів на хвилину та може бути скасоване або оновлене в будь-який час. Токени входу в панель та облікові дані Telegram тут не працюють.

export TGWITNESS_URL=https://panel.example.org      # default http://127.0.0.1:8787
export TGWITNESS_MCP_TOKEN=tgw_mcp_...              # or --token-file path
tgwitness search 'перевод карта' --json

Віддалена панель вимагає HTTPS; звичайний HTTP допускається лише для 127.0.0.1, localhost та ::1. Змінні середовища проксі ігноруються, а перенаправлення відхиляються, тому токен надходить лише на вказану вами адресу.

Безпосередньо з зупиненого робочого простору (--data-dir). Зчитує каталог даних із повним локальним доступом, без токена. Використовуйте його на копії каталогу даних або під час зупинки збору даних. Підписані записи ніколи не змінюються; як і у випадку з панеллю, відкриття робочого простору може призвести до оновлення похідних індексів. Коли панель має відкритий робочий простір, команда завершується з кодом 3; замість цього читайте через панель. Якщо --data-dir, TGWITNESS_DATA, ./data/live або використовується каталог даних тієї інсталяції, в якій виконується команда.

--workspace ID вибирає робочу область (за замовчуванням default). tgwitness messages --workspaces виводить список тих, які ви можете читати.

Команди#

Команда	Результат
`tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N]`	Спочатку відображаються найкращі збіги, включаючи словоформи, точні фрази в лапках, домени та `@username` (синтаксис)
`tgwitness search QUERY --exact [--before SEQ]`	Точний текст, спочатку найновіші записи, без індексу
`tgwitness context CHAT_ID MESSAGE_ID`	Збережені повідомлення в межах десяти ідентифікаторів повідомлень з обох боків
`tgwitness messages`	Чати, які ви можете читати
`tgwitness messages CHAT_ID [--since] [--until] [--before SEQ]`	Збережені повідомлення чату, найновіші першими
`tgwitness messages CHAT_ID --message ID`	Кожна збережена версія та запис про видалення одного повідомлення
`tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N]`	Статистика активності наведена нижче
`tgwitness export [--chat ID] [--since] [--until] [--output FILE]`	Збережені спостереження у форматі JSON Lines у порядку записів у журналі

Дати вказано у форматі 2026-10-01 (північ за UTC) або час у форматі ISO із зазначенням часового поясу, 2026-10-01T09:00+03:00. Щодо search, messages та export вони вибирають час спостереження. Сторінки вміщують до 50 записів: дотримуйтесь next_offset (--offset) для пошуку за рейтингом та next_before (--before) в інших розділах.

Ранжований пошук зупиняється на 1,000 результатах. Остання сторінка може бути коротшою, ніж --limit; звузьте запит, чат або період, якщо існує більше відповідних спостережень.

Кожен результат повідомлення містить untrusted_content: trueідентифікатори робочого простору, чату та повідомлення, порядковий номер у журналі, хеш збереженого запису та посилання на панель. Редагування, повідомлення про видалення та missing_on_recheck — це окремі записи. Відсутність запису не доводить, що подія ніколи не відбувалася.

Статистика активності#

stats підраховує збережені спостереження для одного чату, одного відправника або всіх чатів у межах обстеження:

повідомлення за годинами за UTC та за днями тижня (починаючи з понеділка), години та дні з найбільшою активністю;
відредаговані, видалені та missing_on_recheck поширення;
відправники з кількістю повідомлень та часом надсилання першого та останнього повідомлення;
найпоширеніші домени та @handles, що підраховуються один раз на повідомлення у всіх його збережених версіях;
Обсяг: coverage.gap записи та, для доступу до всього робочого простору, періоди без сигналу життя підключеного колектора (collector_liveness).

Період визначає час повідомлення, зазначений Telegram. Кількість годин та днів тижня може допомогти оцінити часовий пояс відправника, але не встановлює його остаточно. Цифри обчислюються за запитом із журналу та не зберігаються. Кожен результат вказує на заголовок журналу, який він охоплює, якщо ваш доступ охоплює робочу область. Читання зупиняється через п’ять секунд після прокрутки панелі або --timeout секунд на локальному комп’ютері (за замовчуванням — 30); після цього complete має значення false, а partial вказує перший запис, який не було прочитано. У цьому випадку враховуються лише найсвіжіші записи .

Експорт#

export Записує один об’єкт JSON на кожне збережене спостереження (нові повідомлення, знімки екрана, редагування, відновлені повідомлення, повідомлення про видалення, missing_on_recheck та збережені мультимедійні записи) у порядку їхнього внесення до журналу. Кожен рядок містить ті самі поля, що й інші записи, а також повний текст. При --outputфайл записується під .partial іменем і перейменовується лише після запису про завершення роботи панелі; перерваний експорт не залишає файлу та завершується з кодом 1. --output ніколи не перезаписує існуючий файл. З --output та --json, у stdout виводиться зведена інформація: кількість записів, остання послідовність журналу та, у разі доступу до всього робочого простору, початок журналу.

Для експорту через панель потрібне з’єднання, яке дозволяє експортувати повідомлення (лише з командного рядка); за замовчуванням ця опція не вибрана. Цей файл є робочою копією, а не доказом: для перевіреної передачі даних використовуйте підписаний експорт у розділі «Експорт», який python -m tgwitness.verifyперевіряється.

Панель повторно перевіряє доступ перед виведенням кожного запису, включаючи запис про завершення. Скасований або прострочений доступ призводить до неповного експорту. Ліниве читання сторінок поділяє ліміт архівного модуля з іншими запитами та має обмежений час очікування.

Навички агента#

.agents/skills/tgwitness-cli/SKILL.md розповідає агенту, як використовувати ці команди, як цитувати записи та як обробляти захоплений текст. Агенти, які читають .agents/skills завантажують його з репозиторію чеку. Для Claude Code скопіюйте tgwitness-cli папку у .claude/skills/ у ваш проєкт або ~/.claude/skills/.

MCP та командний рядок#

Обидва використовують ті самі з’єднання, перевірки області дії та обмеження. Результати MCP обмежуються однією сторінкою розміром 64 Кбайт, тому MCP не підтримує масовий експорт; командний рядок передає дані потоком. get_activity_stats доступна для обох.