Telegram Message Analyzer

A powerful CLI tool to analyze Telegram result.json exports using AI. It identifies relevant messages based on your custom criteria and generates actionable output (like draft emails or summaries) in both CSV and visual HTML formats.

Note: Currently, this tool exclusively supports Google Gemini models.

🚀 Features

• Dynamic Analysis: Fully customizable analysis criteria and output format via natural language prompts.
• Multimodal Support: Automatically uploads and analyzes photos attached to messages.
• Batch Processing: Groups messages into batches (e.g., 10 at a time) to maximize API throughput and stay within free tier limits.
• Dual Logging:
  • analysis_log.csv: Machine-readable data for further processing or spreadsheet analysis.
  • analysis_log.html: A professional, visual dashboard with image previews, color-coded results, and built-in filtering/sorting capabilities.
• Optimized Rate Limiting: Built-in retry logic and smart handling of 429 Too Many Requests errors, including automatic waits based on API feedback.
• Progress Tracking: Persistent state via resume.json allows the script to pick up exactly where it left off.
• Modular Architecture: Clean, extensible TypeScript codebase.

📁 Project Structure

├── src/
│   ├── services/
│   │   ├── Analyzer.ts   # Core AI logic and batch processing
│   │   └── Logger.ts     # CSV and HTML report generation
│   ├── types.ts          # Centralized TypeScript interfaces
│   └── utils.ts          # Text parsing and escaping helpers
├── index.ts              # CLI entry point and orchestration
├── .env.example          # Template for environment variables
├── package.json          # Dependencies and scripts
└── tsconfig.json         # TypeScript configuration

🛠️ Setup

1. Clone and Install:

   npm install

2. Configure Environment: Create a .env file in the root directory. You can use the following template:

   GOOGLE_GENAI_API_KEY=your_api_key_here
   TELEGRAM_EXPORT_PATH=./DataExport_Chat
   ANALYSIS_PROMPT="Your custom analysis prompt"
   MODEL_NAME=gemini-2.5-flash-lite
   BATCH_SIZE=10
   WAIT_TIME=5000
   CONCURRENCY_LIMIT=1

📋 How to Export Telegram Data

To use this tool, you must export your chat data in JSON format from Telegram Desktop:

1. Open Telegram Desktop (not available on mobile/web).
2. Go to Settings > Advanced > Export Telegram data.
3. In the export settings:
   • Select Personal chats or Groups.
   • Photos: Ensure "Photos" is selected if you want to analyze images.
   • Format (CRITICAL): Change "Format" from "HTML" to JSON.
4. Click Export.
5. The export folder (e.g., ChatExport_2024-01-27) contains result.json. Use this folder path as your TELEGRAM_EXPORT_PATH.

🚀 Usage

The tool accepts configuration via command-line arguments or .env variables. Command-line arguments always take priority.

CLI Syntax

npx tsx index.ts [path] "[prompt]" [api_key] [model_name] [batch_size] [wait_time] [concurrency_limit]

Examples

Option 1: Full CLI Arguments

npx tsx index.ts ./MyChat "Analyze for job openings" MY_API_KEY gemini-2.5-flash-lite 10 5000 2

Option 2: Using .env (Recommended)

npm run analyze

Option 3: Resetting Progress (Start Over) If you want to ignore resume.json and recreate your analysis logs from scratch:

npm run analyze:reset

Note: This will delete your existing resume.json, analysis_log.csv, and analysis_log.html.

Configuration Parameters

Parameter	Env Variable	Mandatory	Description
path	TELEGRAM_EXPORT_PATH	Yes	Path to the Telegram export folder.
prompt	ANALYSIS_PROMPT	Yes	Instructions for the AI.
api_key	GOOGLE_GENAI_API_KEY	Yes	Your Google AI Studio API Key.
model_name	MODEL_NAME	Yes	The Gemini model (e.g., gemini-1.5-flash).
batch_size	BATCH_SIZE	No	Messages per request (Default: 10).
wait_time	WAIT_TIME	No	Delay in ms between batches (Default: 5000).
concurrency_limit	CONCURRENCY_LIMIT	No	Simultaneous batch requests (Default: 1).
--reset	-	No	Ignore progress and recreate log files.

💡 Prompt Engineering Examples

Job Search (Professional)

"Analyze if the message contains job openings for Full Stack Engineer roles. Requirements: Mid-level or higher; Remote only. Generate a draft application email for each role found."

Summarization

"Check if the message contains important technical announcements. If yes, provide a one-sentence summary for a weekly report."

Expense Tracking

"Identify if the message mentions any price or cost. If it does, extract the amount and the item purchased in a format like 'Item: [Item] | Cost: [Amount]'."

🔧 Troubleshooting

• Rate Limits (429 Error): If you hit a rate limit, the script will automatically pause and retry. If you hit your daily quota, the script will save progress and exit.
• Resuming: Progress is saved in resume.json. If you want to restart the analysis from the beginning, delete this file.
• Image Errors: Ensure the photos/ directory is present in your export folder if your prompt requires image analysis.
• JSON Parsing: The script uses robust regex to extract JSON from AI responses, but very complex or malformed AI output might occasionally fail. These failures are logged and the batch is retried up to 3 times.

📄 License

This project is licensed under the ISC License.