TgWitness / Documentation

Repository / docs/SIMILAR-CHANNELS.md

Similar channels

TgWitness / Documentation · Investigation

Investigation

Telegram keeps a list of channels it considers similar to a given channel and offers it to readers. TgWitness can walk that list from one or more starting channels and record what Telegram returned.

A suggestion is produced by Telegram from its own usage signals. Treat the result as a lead list: a shared operator, owner, author or purpose is established from the channels' own records.

Run a walk#

curl -sS -X POST http://127.0.0.1:8000/api/channel-graph \
  -H "Authorization: Bearer $TGWITNESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"seeds": [-1001234567890], "depth": 2, "per_source": 20, "total": 100,
       "min_participants": 500, "require_username": true, "pause_seconds": 1}'

Only the main administrator can start a walk, and the account must be connected. Each seed must be a chat this account has already read, so resolve the channel in the panel first.

Setting Meaning Range
seeds Channels the walk starts from 1–50 chat IDs
depth How many suggestion steps to follow; 1 reads the seeds only 0–4
per_source Suggestions processed from one channel before filters 1–200
total Channels in the whole result, including the seeds 1–2000
min_participants, max_participants Subscriber range to keep any order-consistent pair
require_username Drop channels without a public username off by default
skip_restricted Drop channels Telegram marks as restricted off by default
pause_seconds Wait between requests 0–60

Filters shape the retained node list. The journal keeps each processed suggestion, including suggestions dropped by a filter, and reports the counts. The per_source and whole-run budgets can leave received suggestions unprocessed.

What the journal keeps#

graph.started records the seeds and the settings. One graph.suggestions record per visited channel holds what Telegram returned, how many were kept and the channel IDs and usernames. graph.source_unavailable marks a seed the account cannot read. graph.finished closes the run with the totals and the reason it stopped.

Each suggestion record separates Telegram's reported total from the received channel count (suggested), processed count (returned) and count passing filters (kept). A sliced API response can therefore report a larger total than the list available to this account. response_complete indicates that all reported suggestions were received; complete additionally requires processing the entire received list. These flags describe the response and processing before filters, not a complete map of Telegram channels. The result's sources list retains the same counts and flags for each successfully queried source.

A walk stops early and says so when it reaches total, or when Telegram asks the account to wait. A flood-wait answer is recorded as telegram.backoff, the account-wide pause is honoured, and stopped reads rpc_backoff.

Result#

The answer is a tgwitness-channel-graph-v1 object with nodes (chat ID, title, username, subscriber count, Telegram flags, discovery depth and source) and edges (which channel suggested which). Each node keeps the flags Telegram supplied, including scam, fake, verified and restricted.