Algumas partes desta página ainda estão em inglês: o original em inglês sofreu alterações após ter sido traduzido.
Referência / Arquivo e integrações
Telegram · Linha de comando
Pesquise, leia o contexto, conte atividades e exporte mensagens salvas a partir de scripts e agentes, com saída no formato --json, códigos de saída estáveis e tokens de leitura exclusiva com escopo definido.
MCP somente leitura · Pesquisa de texto completo · 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.
Com --json, a saída padrão (stdout) contém exatamente um documento JSON (export grava linhas JSON).
O progresso, as dicas e os erros são direcionados para o stderr. Os códigos de saída são estáveis:
| Código | Significado |
|---|---|
0 |
Sucesso, incluindo um resultado vazio |
1 |
Falha: painel inacessível, dados ilegíveis, exportação interrompida |
2 |
Erro de uso ou solicitação inválida: data incorreta, opção desconhecida, índice de pesquisa desativado |
3 |
Indisponível no momento: o espaço de trabalho está aberto em um painel em execução, ou o painel solicita que se tente novamente mais tarde (limite de taxa, tempo limite) |
4 |
Acesso negado: token ausente, expirado ou revogado; um chat fora do escopo; uma ferramenta que não permite |
Duas maneiras de ler#
Por meio do painel (--url). O comando utiliza a mesma API de arquivo com escopo que
MCP. Crie uma conexão em Mais ferramentas → Integrações → MCP: escolha espaços de trabalho e chats,
ferramentas e um prazo de validade, depois copie o token uma vez. A conexão é somente para leitura, limitada
a esses chats, com restrição de taxa de 60 solicitações por minuto e pode ser revogada ou
renovada a qualquer momento. Tokens de login do painel e credenciais do Telegram não funcionam aqui.
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
Um painel remoto requer HTTPS; o HTTP simples é aceito apenas para 127.0.0.1,
localhost e ::1. Variáveis de ambiente de proxy são ignoradas e redirecionamentos são
recusados, de modo que o token chegue apenas ao endereço que você fornecer.
Diretamente de um espaço de trabalho parado (--data-dir). Lê o diretório de dados com
acesso local total, sem um token. Use-o em uma cópia de um diretório de dados ou enquanto
a coleta estiver parada. Registros assinados nunca são alterados; assim como no painel, abrir um
espaço de trabalho pode atualizar seus índices derivados. Quando o painel tem o espaço de trabalho aberto, o comando sai com
código 3; leia pelo painel, em vez disso. Sem --data-dir, TGWITNESS_DATA,
./data/live ou o diretório de dados da instalação que está executando o comando é utilizado.
--workspace ID seleciona um espaço de trabalho (padrão default). tgwitness messages
--workspaces lista aqueles que você pode ler.
Comandos#
| Comando | Resultado |
|---|---|
tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N] |
Melhores correspondências primeiro, incluindo formas de palavras, frases exatas entre aspas, domínios e @username (sintaxe) |
tgwitness search QUERY --exact [--before SEQ] |
Texto exato, do mais recente ao mais antigo, sem o índice |
tgwitness context CHAT_ID MESSAGE_ID [--limit N] [--before SEQ] |
Mensagens salvas dentro de dez IDs de mensagem de cada lado |
tgwitness messages [--limit N] [--offset N] |
Conversas que você pode ler |
tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--before SEQ] |
Mensagens salvas do chat, com as mais recentes em primeiro lugar |
tgwitness messages CHAT_ID --message ID |
Cada versão salva e registro de exclusão de uma mensagem |
tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N] |
Estatísticas de atividade, abaixo |
tgwitness export [--chat ID] [--since] [--until] [--output FILE] |
Observações salvas como linhas JSON na ordem do registro |
As datas são 2026-10-01 (meia-noite UTC) ou horários ISO com fuso horário,
2026-10-01T09:00+03:00. Para search, messages e export eles selecionam
a hora da observação. As páginas comportam até 50 registros: siga next_offset (--offset) para
busca por classificação e next_before (--before) em outros lugares.
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.
Cada resultado de mensagem contém untrusted_content: true
, os IDs do espaço de trabalho, do chat e
da mensagem, a sequência do diário, o hash do registro salvo e um link para o painel. Edições,
avisos de exclusão e missing_on_recheck
são registros separados. A cobertura em stats
mostra os períodos aos quais um resultado de pesquisa se refere.
Estatísticas de atividade#
stats Conta as observações salvas para um chat, um remetente ou todos os chats no escopo:
- mensagens por hora UTC e por dia da semana (começando pela segunda-feira), horários e dias de maior movimento;
- editados, excluídos e
missing_on_recheckcompartilhamentos; - remetentes com contagem de mensagens e horários da primeira e da última mensagem;
- os domínios mais frequentes e
@handles, contados uma vez por mensagem em todas as suas versões salvas; - cobertura:
coverage.gapregistros e, para acesso a todo o espaço de trabalho, períodos sem um sinal de vida do coletor conectado (collector_liveness).
O período seleciona a hora da mensagem informada pelo Telegram. As contagens de horas e dias da semana
ajudam a estimar o fuso horário do remetente. Os números são calculados mediante
solicitação do diário e não são armazenados. Cada resultado indica o cabeçalho do diário que
abrange quando seu acesso abrange o espaço de trabalho. A leitura é interrompida após cinco segundos no
painel ou após --timeout segundos localmente (padrão 30); então complete é falso e
partial indica o primeiro registro que não foi lido. Nesse caso, apenas os registros mais recentes são
contados.
Exportar#
export grava um objeto JSON por observação salva (novas mensagens, capturas de tela,
edições, mensagens recuperadas, avisos de exclusão, missing_on_recheck e registros de mídia
salvos) na ordem do diário. Cada linha possui os mesmos campos dos demais resultados, com
o texto completo. Com --output, o arquivo é gravado com um .partial nome e
é renomeado somente após o registro de conclusão do painel; uma exportação interrompida não deixa nenhum
arquivo e encerra com o código 1. --output nunca sobrescreve um arquivo existente. Com
--output e --json, a saída padrão (stdout) exibe um resumo: contagem de registros, última
sequência do diário e, para acesso a toda a área de trabalho, o cabeçalho do diário.
Uma exportação pelo painel requer uma conexão que permita mensagens de exportação
(somente linha de comando)
; essa opção não está selecionada por padrão. Este arquivo é uma cópia de trabalho; para uma
transferência verificável, use a exportação assinada em Exportações
, que é verificada por python -m tgwitness.verify
.
O painel verifica novamente o acesso antes de emitir cada registro, incluindo o registro de conclusão. O acesso revogado ou expirado resulta em uma exportação incompleta. As leituras de página diferidas compartilham o limite do processador de arquivos com outras consultas e têm um tempo de espera limitado.
Index and backup#
These two commands read the data directory directly and take no token or --url.
| Comando | Resultado |
|---|---|
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.
Habilidade do agente#
.agents/skills/tgwitness-cli/SKILL.md
explica a um agente como usar esses comandos, como citar registros e como tratar
o texto capturado. Agentes que leem .agents/skills carregam-no a partir de um checkout
do repositório. Para o Claude Code, copie a tgwitness-cli pasta para .claude/skills/ dentro
do seu projeto ou ~/.claude/skills/.
MCP e a linha de comando#
Ambos utilizam as mesmas conexões, verificações de escopo e limites. Os resultados do MCP estão limitados a
uma página de 64 KiB; portanto, o MCP não oferece exportação em massa; a linha de comando transmite os dados em fluxo contínuo.
get_activity_stats está disponível para ambos.