Certaines parties de cette page sont encore en anglais : le texte original en anglais a été modifié après sa traduction.
Référence / Archives et intégrations
Telegram · Ligne de commande
Rechercher, lire le contexte, compter les activités et exporter les messages enregistrés à partir de scripts et d'agents, avec une sortie au format --json, des codes de sortie stables et des jetons en lecture seule à portée limitée.
MCP en lecture seule · Recherche en texte intégral · Wiki
Preview. tgwitness search, context, messages, stats and export read
saved observations for scripts and AI agents. They cannot send anything to
Telegram, change settings or modify the signed journal. tgwitness index and
tgwitness backup (below) work on a local data directory and
need no token.
Avec --json, la sortie standard (stdout) contient exactement un document JSON (export écrit des lignes JSON).
La progression, les conseils et les erreurs sont envoyés vers stderr. Les codes de sortie sont stables :
| Code | Signification |
|---|---|
0 |
Succès, y compris en cas de résultat vide |
1 |
Échec : panneau inaccessible, données illisibles, exportation interrompue |
2 |
Erreur d'utilisation ou requête non valide : date incorrecte, option inconnue, index de recherche désactivé |
3 |
Indisponible pour le moment : l'espace de travail est ouvert dans un panneau en cours d'exécution, ou le panneau demande de réessayer plus tard (limite de débit, délai d'attente) |
4 |
Accès refusé : jeton manquant, expiré ou révoqué, discussion hors de son champ d'application, outil non autorisé |
Deux façons de lire#
Via le panneau (--url). La commande utilise la même API d’archivage à portée que
MCP. Créez une connexion dans Plus d’outils → Intégrations → MCP : choisissez des espaces de travail et des discussions,
des outils et une date d’expiration, puis copiez le jeton une seule fois. La connexion est en lecture seule, limitée
à ces discussions, plafonnée à 60 requêtes par minute et peut être révoquée ou
renouvelée à tout moment. Les jetons de connexion au panneau et les identifiants Telegram ne fonctionnent pas ici.
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
Un panneau distant nécessite le protocole HTTPS ; le protocole HTTP simple n'est accepté que pour 127.0.0.1,
localhost et ::1. Les variables d’environnement de proxy sont ignorées et les redirections sont
refusées, de sorte que le jeton n’atteigne que l’adresse que vous indiquez.
Directement à partir d’un espace de travail arrêté (--data-dir). Lit le répertoire de données avec
un accès local complet, sans jeton. À utiliser sur une copie d’un répertoire de données ou lorsque
la collecte est arrêtée. Les enregistrements signés ne sont jamais modifiés ; comme dans le panneau, l’ouverture d’un
espace de travail peut mettre à jour ses index dérivés. Lorsque le panneau a l’espace de travail ouvert, la commande se termine avec le
code 3; lisez plutôt via le panneau. En l’absence de --data-dir, TGWITNESS_DATA,
./data/live ou le répertoire de données de l’installation exécutant la commande est utilisé.
--workspace ID sélectionne un espace de travail (par défaut default). tgwitness messages
--workspaces affiche la liste de ceux que vous pouvez consulter.
Commandes#
| Commande | Résultat |
|---|---|
tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N] |
Résultats les plus pertinents en premier, avec les formes des mots, les expressions exactes entre guillemets, les domaines et @username (syntaxe) |
tgwitness search QUERY --exact [--before SEQ] |
Texte exact, du plus récent au plus ancien, sans l'index |
tgwitness context CHAT_ID MESSAGE_ID [--limit N] [--before SEQ] |
Messages enregistrés dans un intervalle de dix identifiants de message de part et d'autre |
tgwitness messages [--limit N] [--offset N] |
Discussions que vous pouvez lire |
tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--before SEQ] |
Messages enregistrés de la conversation, les plus récents en premier |
tgwitness messages CHAT_ID --message ID |
Chaque version enregistrée et chaque enregistrement de suppression d'un message |
tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N] |
Statistiques d'activité, ci-dessous |
tgwitness export [--chat ID] [--since] [--until] [--output FILE] |
Observations enregistrées sous forme de lignes JSON dans l'ordre du journal |
Les dates sont exprimées en 2026-10-01 (minuit UTC) ou exprimées selon le format ISO avec un fuseau horaire,
2026-10-01T09:00+03:00. Pour search, messages et export ils sélectionnent
l'heure de l'observation. Les pages peuvent contenir jusqu'à 50 enregistrements : suivez next_offset (--offset) pour la
recherche par classement et next_before (--before) ailleurs.
Ranked search stops at 1,000 results. The final page may be shorter than --limit. When more observations match, the last page says so (truncated: true with --json); narrow the query, chat or period.
Chaque résultat de message comporte untrusted_content: true
, les identifiants de l’espace de travail, de la discussion et
du message, la séquence du journal, le hachage de l’enregistrement sauvegardé et un lien vers le panneau. Les modifications,
les notifications de suppression et missing_on_recheck
constituent des enregistrements distincts. La couverture dans stats
indique les périodes couvertes par un résultat de recherche.
Statistiques d'activité#
stats Compte le nombre d'observations enregistrées pour une conversation, un expéditeur ou toutes les conversations concernées :
- messages par heure UTC et par jour de la semaine (en commençant par le lundi), heures et jours les plus chargés ;
- modifiés, supprimés et
missing_on_recheckpartages ; - les expéditeurs avec le nombre de messages ainsi que les heures du premier et du dernier message ;
- les domaines les plus fréquents et
@handles, comptés une fois par message parmi ses versions enregistrées ; - Couverture :
coverage.gapenregistrements et, pour l'accès à l'ensemble de l'espace de travail, périodes sans signal de présence du collecteur connecté (collector_liveness).
La période sélectionne l’heure du message indiquée par Telegram. Le nombre d’heures et de jours de la semaine
permet d’estimer le fuseau horaire de l’expéditeur. Les chiffres sont calculés sur
demande à partir du journal et ne sont pas stockés. Chaque résultat indique l’en-tête du journal qu’il
couvre lorsque votre accès s’étend sur l’espace de travail. La lecture s’arrête après cinq secondes via
le panneau, ou après --timeout secondes en local (30 par défaut) ; alors complete est faux et
partial désigne le premier enregistrement qui n’a pas été lu. Seuls les enregistrements les plus récents sont
pris en compte dans ce cas.
Exporter#
export Il génère un objet JSON par observation enregistrée (nouveaux messages, captures d’écran,
modifications, messages récupérés, notifications de suppression, missing_on_recheck et les enregistrements de médias
sauvegardés) dans l’ordre du journal. Chaque ligne comporte les mêmes champs que les autres résultats, avec
le texte intégral. Avec --output, le fichier est enregistré sous un .partial nom et
n'est renommé qu'après l'enregistrement de la fin du panneau ; une exportation interrompue ne laisse aucun
fichier et se termine avec le code 1. --output ne remplace jamais un fichier existant. Avec
--output et --json, stdout affiche un résumé : nombre d’enregistrements, dernière
séquence du journal et, pour l’accès à l’ensemble de l’espace de travail, l’en-tête du journal.
Une exportation via le panneau nécessite une connexion autorisant les messages d’exportation
(ligne de commande uniquement)
; cette option n’est pas sélectionnée par défaut. Ce fichier est une copie de travail ; pour un transfert vérifiable,
utilisez l’exportation signée dans la section Exportations
, que la commande python -m tgwitness.verify
vérifie.
Le panneau vérifie à nouveau les droits d'accès avant d'émettre chaque enregistrement, y compris l'enregistrement de fin . Un accès révoqué ou expiré entraîne une exportation incomplète. Les lectures de pages différées partagent la limite du processeur d'archivage avec d'autres requêtes et sont soumises à un délai d'attente limité.
Index and backup#
These two commands read the data directory directly and take no token or --url.
| Commande | Résultat |
|---|---|
tgwitness index status [--workspace ID] [--data-dir DIR] [--json] |
Search index state of one workspace or, by default, every workspace: mode, ready, building or not built, indexed and journal head sequence. Works while the panel runs |
tgwitness index rebuild [--workspace ID] [--data-dir DIR] [--json] |
Rebuilds the index from the first journal record. Rewrites only the derived index, never the signed journal. Exits with code 3 while the panel has the workspace open. Nothing is built when the workspace keeps its index in memory or has search off |
tgwitness backup FOLDER [--data-dir DIR] [--json] |
Copies the whole data directory into a new or empty folder outside it while the panel keeps running, and writes backup-manifest.json with every file's SHA-256 and the journal heads |
index accepts --workspace default or a workspace ID; the default is all. The
backup skips temporary exports, SQLite sidecar files and lock files. The folder
holds the Telegram session and signing keys, so keep it as private as the data
directory. Backup, restore, and capacity
describes restoring and what the next start records.
Compétences de l'agent#
.agents/skills/tgwitness-cli/SKILL.md
explique à un agent comment utiliser ces commandes, comment citer les enregistrements et comment traiter
le texte capturé. Les agents qui lisent .agents/skills le chargent à partir d’un dépôt
de code. Pour Claude Code, copiez le tgwitness-cli dossier dans .claude/skills/ dans
votre projet ou ~/.claude/skills/.
MCP et la ligne de commande#
Les deux utilisent les mêmes connexions, les mêmes vérifications de portée et les mêmes limites. Les résultats de MCP sont limités à
une page de 64 KiB ; MCP ne propose donc pas d’exportation en masse ; la ligne de commande les transmet en continu.
get_activity_stats est disponible pour les deux.