# Mastros.online — Telegram Data Extractor

> Mastros.online is a Chrome extension (Manifest V3) that extracts Telegram group members, chat messages, recent contacts, and mutual groups from Telegram Web. It operates entirely client-side in the user's browser, with an optional "Power Mode" that connects directly to Telegram's MTProto API via GramJS for deeper and more complete data extraction. No user data is sent to external servers for processing.

## Product Overview

Mastros.online is built for marketers, researchers, OSINT analysts, community managers, and growth operators who need structured data from Telegram. It works by injecting a sidebar UI into web.telegram.org and extracting data either from the visible DOM (Web Mode) or directly via the Telegram API (Power Mode).

The extension does not require a separate app install — it runs entirely as a Chrome extension. It does not work on Telegram Desktop, Telegram mobile apps, or third-party Telegram clients. It only works on https://web.telegram.org.

Mastros.online is not affiliated with, endorsed by, or partnered with Telegram. Users are solely responsible for complying with Telegram's Terms of Service when using this tool.

### How It Works

1. Install the Chrome extension from the Chrome Web Store
2. Open Telegram Web (web.telegram.org) in Chrome
3. The extension automatically injects a collapsible sidebar on the right side of the page
4. Choose an extraction mode (Group Members, Chat Messages, Recent Contacts, or Mutual Groups)
5. Follow the on-screen instructions for each mode — each tells you exactly what to do in Telegram first
6. Click Start to begin extraction
7. View progress in real-time with live activity feeds
8. Export your data as CSV, JSON, or JSONL from the Export tab

### Architecture

- **Content Script** (`content.js`, `powerModeBridge.js`): Injected into web.telegram.org. Handles DOM-based extraction (Web Mode), sidebar injection, and bridges communication between the page and the extension iframe
- **Sidebar** (`sidebar.html`, `sidebar.js`, `sidebar.css`): The main UI, rendered as an iframe injected into the Telegram Web page. Contains mode selection, configuration, progress display, export controls, and settings
- **Power Mode** (`powerMode.js`, `gramjs.bundle.js`): Runs inside the sidebar iframe (chrome-extension:// origin). Uses GramJS to establish a direct MTProto WebSocket connection to Telegram's data centers. This bypasses web.telegram.org's CSP restrictions because extension pages have their own origin
- **Background Service Worker** (`background.js`): Handles account sync, quota management, Stripe billing integration, usage tracking, and analytics relay
- **Analytics** (`analytics.js`): Anonymized usage telemetry via PostHog

---

## Extraction Modes — Detailed

### Group Members (Power Mode Only)

Extracts full member profiles from one or multiple Telegram groups using the Telegram API.

**Requirements**: Power Mode must be connected (user provides their own api_id and api_hash from https://my.telegram.org)

**Three selection sub-modes**:
- **Current Group**: Extracts from whichever group is currently open in Telegram Web
- **Manual Input**: Paste @handles or t.me links for one or more groups. The API resolves and extracts them
- **Browse Groups**: Click "Load my groups" to fetch your group list via API, then select which groups to extract with checkboxes. Filters for groups only vs. all chats

**Data collected per member**: name, username (@handle), telegram_user_id, role (admin/member/creator), bio, phone number (if visible to the user), source_group, scraped_at timestamp, source_mode (always "api")

**Options**:
- Fetch full profile info (bio, phone) — makes additional API calls per user
- Deduplication across multiple groups
- Configurable sleep intervals to respect Telegram rate limits

**How it works internally**: Uses GramJS `iter_participants` equivalent to page through the group's member list. For full profiles, it calls `GetFullUser` on each participant. Handles FLOOD_WAIT errors automatically with exponential backoff.

### Chat Messages (Web Mode + Power Mode)

Extracts message history and sender information from any open chat conversation.

**Web Mode** (no API credentials needed):
- Scrolls through the message area in Telegram Web's DOM
- Extracts: message text, sender name, sender user ID, timestamp, reply/forward metadata
- Content-based deduplication using fingerprints from text + sender + timestamp
- Limited to what's loaded in the browser — older messages require scrolling

**Power Mode** (requires Pro plan + API credentials):
- Fetches message history directly via the Telegram API
- Faster and more complete than DOM scrolling
- Includes participant profiles in the response

**Data collected per message**: message_id, timestamp, text, sender_id, sender_name, sender_handle, sender_bio, sender_phone, source_chat, scraped_at, source_mode

**Options**:
- Message count limit (default: 5,000)
- Include sender info (name, handle)
- Include timestamps
- Include reply/forward metadata

### Recent Contacts (Web Mode + Power Mode)

Extracts profile information from your most recently active chat conversations.

**Web Mode**:
- Reads the chat list sidebar in Telegram Web
- Extracts profile cards for each recent chat
- Limited to what's visible and loaded in the DOM

**Power Mode** (requires Pro plan + API credentials):
- Reads recent dialogs directly via the Telegram API
- Provides a truer recent ordering and richer profile data

**Options**:
- Number of recent chats to scan (default: 20)
- Ignore pinned chats
- Exclude bots

**Data collected**: name, username, telegram_user_id, bio, source_chat, scraped_at, source_mode

### Mutual Groups (Power Mode Only)

Discovers shared groups between the user and a target Telegram user, then optionally extracts members from those groups.

**Requirements**: Power Mode must be connected

**Two-step process**:
1. **Step 1 — Find Mutual Groups**: Enter a target user's @handle. The extension calls `GetCommonChats` via the API to find all groups you share with that user
2. **Step 2 — Extract Members**: Select which mutual groups to scrape, then extract all members from the selected groups

**Data collected**: Same as Group Members mode, plus the mutual group context

---

## Export System

### Supported Formats

- **CSV**: Comma-separated values with quoted fields. Compatible with Excel, Google Sheets, and data analysis tools
- **JSON**: Pretty-printed JSON array of objects. One file per export
- **JSONL**: Newline-delimited JSON (one JSON object per line). Compatible with streaming data pipelines and tools like jq

### Profile Export Fields

| Field | Description |
|---|---|
| name | Display name of the Telegram user |
| handle | Username (@handle) |
| telegram_user_id | Numeric Telegram user ID |
| role | Role in group (member, admin, creator) |
| bio | User's bio/about text |
| phone | Phone number (if visible to the user) |
| source_group | Name of the group the profile was extracted from |
| source_chat | Name of the chat context |
| scraped_at | ISO 8601 timestamp of when the data was extracted |
| source_mode | "web" or "api" depending on extraction method |

### Message Export Fields

| Field | Description |
|---|---|
| message_id | Telegram message ID |
| timestamp | Message timestamp |
| text | Message text content |
| sender_id | Numeric sender user ID |
| name | Sender display name |
| handle | Sender username |
| bio | Sender bio |
| phone | Sender phone (if visible) |
| source_chat | Chat name where message was extracted |
| scraped_at | ISO 8601 extraction timestamp |
| source_mode | "web" or "api" |

---

## Plans & Pricing

### Free Plan
- 500 profiles per month
- 1,000 messages per month
- 500 API calls per month
- Power Mode available for: Group Members, Mutual Groups
- Power Mode locked for: Chat Messages, Recent Contacts (requires Pro)
- No credit card required
- Works in guest mode (no email needed)

### Pro Plan
- 5,000 profiles per month
- 10,000 messages per month
- 5,000 API calls per month
- Power Mode for all extractors including Chat Messages and Recent Contacts
- Best for active operators and researchers
- Billed via Stripe

### Scale Plan
- 100,000 profiles per month
- 500,000 messages per month
- 100,000 API calls per month
- Power Mode for all extractors
- Designed for high-volume extraction and data collection operations
- Billed via Stripe

### Billing
- Payments processed securely via Stripe
- Monthly billing cycle with automatic renewal
- Quota resets monthly
- Plan can be changed or cancelled from the extension's Settings tab
- If you change devices or browsers, use the "Restore" feature with your billing email to re-link your plan

---

## Power Mode — Technical Deep Dive

Power Mode is the extension's direct Telegram API integration. It lets users bypass the limitations of DOM-based extraction and access Telegram's data directly via the MTProto protocol.

### Setup

1. Go to https://my.telegram.org and log in with your Telegram account
2. Navigate to "API development tools"
3. Create an application to get your `api_id` and `api_hash`
4. In the extension sidebar, go to Settings → Power Mode
5. Enter your api_id and api_hash
6. Click Connect — you'll receive a login code via Telegram
7. Enter the code (and 2FA password if enabled)
8. Power Mode is now connected

### How It Works

- GramJS (a JavaScript MTProto client) runs inside the extension's sidebar iframe
- The iframe has a chrome-extension:// origin, which is exempt from web.telegram.org's Content Security Policy
- GramJS opens a WebSocket connection directly to Telegram's data centers (DCs)
- The session string is encrypted and stored in chrome.storage.local
- No session data leaves the browser — there is no server-side session storage
- This mirrors the architecture of Python's Telethon library but runs entirely in the browser

### API Methods Used

- `client.iter_participants(entity)` — Page through group members
- `Api.users.GetFullUser({id: user})` — Fetch full user profile (bio, phone)
- `Api.messages.GetCommonChats({user_id, max_id, limit})` — Find mutual groups
- `Api.messages.GetHistory(...)` — Fetch message history
- `client.getDialogs()` — List user's recent conversations

### Rate Limiting

Power Mode handles Telegram's FLOOD_WAIT errors automatically:
- Detects FLOOD_WAIT responses and extracts the wait duration
- Implements automatic exponential backoff
- Configurable sleep intervals between API calls (default: 200ms)
- Users can adjust sleep times to be more conservative if they experience rate limits

---

## Privacy & Security

- **Client-side operation**: All data extraction happens in the user's browser. Extracted profiles and messages are stored in the browser's local storage (chrome.storage) and are never sent to Mastros servers for processing
- **No data collection**: Mastros does not collect, store, or have access to the Telegram data you extract
- **API credentials**: Power Mode requires the user's own Telegram API credentials. Mastros does not provide, share, or have access to your api_id, api_hash, or session strings
- **Analytics**: Anonymized usage telemetry (feature usage, error counts) is sent to PostHog for product improvement. No personally identifiable information or extracted Telegram data is included
- **Backend API**: The Cloudflare Workers backend (telegram-scraper-api.mastros.workers.dev) handles only: account creation/sync, quota tracking, Stripe billing webhooks, and plan management. It does not process or store Telegram data

---

## Technical Specifications

- **Platform**: Google Chrome (Chromium-based browsers)
- **Extension Standard**: Manifest V3
- **Current Version**: 4.0.0
- **Supported Telegram Web versions**: web.telegram.org/k (Web K), web.telegram.org/z (Web Z), web.telegram.org/a (Web A)
- **MTProto Client**: GramJS (JavaScript browser bundle)
- **Backend**: Cloudflare Workers
- **Payments**: Stripe
- **Analytics**: PostHog

---

## FAQ

**Q: Does this work on Telegram Desktop or mobile?**
A: No. It only works on Telegram Web (web.telegram.org) in a Chrome or Chromium-based browser.

**Q: Do I need to provide my Telegram password?**
A: For Web Mode, no. For Power Mode, you need your Telegram API credentials (api_id and api_hash from my.telegram.org) and will authenticate via a code sent to your Telegram account.

**Q: Can I extract from private groups or channels I'm not a member of?**
A: No. The extension can only extract data from chats and groups you already have access to in your own Telegram account.

**Q: Is my extracted data sent to any server?**
A: No. All extracted data stays in your browser. The only server communication is for account/billing sync and anonymized usage analytics.

**Q: What happens if I hit a rate limit?**
A: Power Mode automatically detects Telegram's FLOOD_WAIT errors and pauses extraction for the required duration before resuming.

**Q: Can I use this with multiple Telegram accounts?**
A: Power Mode connects to one Telegram account at a time. You can disconnect and reconnect with different credentials.

---

## Contact & Links

- **Website**: https://mastros.online
- **Support Email**: admin@mastros.online
- **Privacy Policy**: https://mastros.online/privacy
- **Terms of Service**: https://mastros.online/terms