Telegram OSINT Integration: Data Sources and MTProto Configuration in worldmonitor

The worldmonitor Telegram OSINT integration aggregates real-time intelligence from curated public channels via the MTProto API, configured with environment-based credentials and consumed through a dedicated /api/telegram-feed endpoint.

The koala73/worldmonitor repository powers a real-time OSINT dashboard that monitors Telegram channels for breaking intelligence. Its Telegram OSINT integration combines a curated list of public channels with direct MTProto protocol access to stream messages into a unified feed. Understanding the data sources and MTProto configuration reveals how the system maintains real-time situational awareness while handling both web and desktop runtime environments.

Data Sources Powering the Telegram OSINT Feed

The backend exposes a single endpoint /api/telegram-feed that returns a JSON payload conforming to the TelegramFeedResponse interface (lines 17-24 in src/services/telegram-intel.ts). This response contains an array of TelegramItem objects (lines 4-15) representing normalized channel posts.

Curated Telegram Channels

The system aggregates recent posts from a fixed list of public channels relevant to open-source intelligence. Each channel entry transforms into a TelegramItem with standardized fields including channel, channelTitle, url, ts, text, topic, and tags.

The available topic filters are declared in the TELEGRAM_TOPICS constant (lines 26-34) and include:

• all
• breaking
• conflict
• alerts
• osint
• politics
• middleeast

These topics map directly to channel groupings used by the backend to categorize incoming intelligence.

Telegram MTProto API

Unlike standard Bot API implementations, this integration uses the MTProto protocol for real-time message retrieval. The backend (external to the frontend repository) instantiates an MTProto client using standard Telegram API credentials to pull messages directly from the selected channels. The client subscribes to channel updates and streams the latest messages into the JSON payload consumed by the frontend service.

Proxy Handling for Desktop Runtime

When the application runs as a desktop Electron build, requests must avoid browser CORS restrictions. The frontend detects desktop mode via isDesktopRuntime() and rewrites requests through proxyUrl(path) defined in src/services/telegram-intel.ts (line 42). This proxy logic, utilizing utilities from src/utils/proxy.ts, allows the native desktop client to communicate with the MTProto backend locally without cross-origin blocking.

MTProto Configuration Parameters

The backend MTProto client initializes with credentials sourced from environment variables. While the server-side route implementing /api/telegram-feed resides outside this frontend repository, it receives configuration values passed through the proxy or directly from the environment.

Parameter	Description	Configuration Source
api_id	Integer identifier for the Telegram application	process.env.TG_API_ID
api_hash	Hex-encoded hash string paired with api_id	process.env.TG_API_HASH
session	Serialized session file to preserve authentication state across restarts	process.env.TG_SESSION or generated file on disk
datacenter	Optimal data center selection based on channel geography	Auto-determined by the MTProto library at runtime

The backend typically employs a Node.js MTProto wrapper such as telegram-mtproto or mtproto-core, initialized with the three primary values above. After authentication using a phone number or bot token, the client subscribes to the curated channels defined by TELEGRAM_TOPICS.

Frontend Implementation and Data Flow

The frontend consumes the Telegram OSINT feed through a dedicated service layer that handles caching, proxying, and presentation logic.

Fetching the Feed

The fetchTelegramFeed(limit) function in src/services/telegram-intel.ts constructs the request URL /api/telegram-feed?limit=… and executes the fetch. For desktop builds, it routes the request through proxyUrl (lines 40-43), while web builds contact the backend directly.

Caching Strategy

To prevent over-polling the MTProto backend, the service implements a client-side cache with a 30-second TTL (CACHE_TTL = 30_000, lines 36-39). This caching layer resides in src/services/telegram-intel.ts and ensures the UI remains responsive without exceeding API rate limits.

UI Rendering and Timestamp Formatting

The TelegramIntelPanel component (src/components/TelegramIntelPanel.ts, lines 54-92) renders the array of TelegramItem objects. Raw Unix timestamps undergo transformation via formatTelegramTime(ts) (lines 57-68) to produce human-readable relative strings such as "2h" or "15m". The panel registration occurs in src/config/panels.ts, and the component supports filtering messages by the topics defined in TELEGRAM_TOPICS.

Summary

• The Telegram OSINT integration monitors curated public channels categorized under TELEGRAM_TOPICS (all, breaking, conflict, alerts, osint, politics, middleeast).
• MTProto configuration requires TG_API_ID and TG_API_HASH environment variables, with optional persistent sessions via TG_SESSION.
• The frontend consumes normalized data through /api/telegram-feed, implementing a 30-second cache and desktop-specific proxy handling in src/services/telegram-intel.ts.
• Data presentation occurs through the TelegramIntelPanel component with relative timestamp formatting and topic-based filtering capabilities.

Frequently Asked Questions

What environment variables are required to configure the Telegram MTProto integration?

The system requires TG_API_ID and TG_API_HASH as mandatory parameters for MTProto client authentication. An optional TG_SESSION variable can provide a serialized session string to maintain authentication state across application restarts without re-authenticating.

How does the frontend handle CORS when running as a desktop application?

When isDesktopRuntime() detects an Electron environment, the frontend routes requests through proxyUrl(path) defined in src/services/telegram-intel.ts (line 42). This proxy rewrite allows the native desktop client to access the MTProto backend without browser CORS restrictions.

What topics or channel categories does the OSINT integration monitor?

The TELEGRAM_TOPICS constant (lines 26-34) defines seven categories: all, breaking, conflict, alerts, osint, politics, and middleeast. These groupings determine which curated channels populate the feed returned by /api/telegram-feed.

How long does the frontend cache Telegram feed responses?

The implementation caches responses for 30 seconds (CACHE_TTL = 30_000) as defined in src/services/telegram-intel.ts (lines 36-39). This TTL prevents excessive polling of the MTProto backend while maintaining near real-time intelligence updates.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}