Telegram Chat Wrapped Bot

A Spotify Wrapped-style statistics bot for Telegram groups. Analyzes chat exports and presents personalized statistics through an engaging 12-card text-based visual experience.

Features

• 📊 Comprehensive Statistics: Message counts, active days, streaks, and more
• 📝 Text-Based Visual Cards: Rich HTML-formatted cards that load instantly
• 🏆 Achievement System: 70+ badges to unlock based on chat behavior
• 📈 Rankings & Percentiles: See how you compare to other group members
• 😊 Personality Analysis: Communication style, emoji personality, and more
• 🔄 Multiple Export Support: Process multiple JSON files for the same chat
• 🚀 High Performance: Handles large chat exports (1M+ messages) efficiently using streaming parsing

Project Structure

lhc-stats-bot/
├── src/
│   ├── bot.py                  # Main Telegram bot with conversation handlers
│   ├── stats_processor.py      # Process Telegram exports → SQLite database
│   ├── achievements.py         # Badge definitions and checking logic
│   ├── wrapped_text_cards.py   # HTML-based card formatters
│   ├── utils.py                # Shared utility functions
│   └── config.py               # Configuration management
├── data/                       # Data directory for DB and exports
├── docs/                       # Documentation
├── scripts/                    # Helper scripts
├── process_data.py             # Unified data processing script
├── requirements.txt            # Python dependencies
├── .env.example                # Environment variables template
└── README.md                   # This file

Installation

1. Requirements

• Python 3.10 or higher
• A Telegram bot token (get from @BotFather)
• Telegram chat export in JSON format

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment

Copy .env.example to .env and fill in your settings:

cp .env.example .env

Edit .env:

TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
DB_PATH=data/chat_stats.db
GROUP_ID=  # Optional: for group membership verification

Usage

Step 1: Export Your Telegram Chat

1. Open Telegram Desktop
2. Go to your group chat
3. Click the three dots menu → Export chat history
4. Select JSON format
5. Uncheck "Photos" and other media to keep file size small
6. Export to your project directory (e.g., inside data/)

You should get a file like result.json.

Step 2: Process the Export

Use the unified processing script to parse data and calculate achievements in one go:

# Single file
python process_data.py data/result.json

# Multiple files (for same chat across different time periods)
python process_data.py data/export1.json data/export2.json

# Or use wildcards
python process_data.py "data/*.json"

This will:

• Parse all messages using efficient streaming (ijson)
• Calculate comprehensive statistics for each user
• Store everything in SQLite (data/chat_stats.db by default)
• Compute rankings and percentiles
• Calculate achievements for all users

Step 3: Run the Bot

Start the Telegram bot:

python -m src.bot

The bot will start polling and respond to commands.

Step 4: Use the Bot

1. Open Telegram and find your bot
2. Send /start to see the menu
3. Click "🎁 Get My Wrapped" to start your personalized experience
4. Tap through all 12 cards to see your stats!

Available Commands

Command	Description
/start	Welcome message with menu buttons
/wrapped	Start the full Wrapped experience (12 cards)
/leaderboard	Top 10 users by message count, consistency, etc.
/cancel	Cancel the current Wrapped session

The Wrapped Experience

Your personalized Wrapped consists of 12 cards presented as rich HTML messages:

1. Welcome Card - "Your Chat Wrapped is ready!"
2. Year Overview - Timeline of your activity
3. Volume Stats - Total messages and daily average
4. Consistency - Active days and streaks
5. Content Mix - Breakdown of message types
6. Communication Style - Your personality (Storyteller, Chatter, etc.)
7. Emoji DNA - Your top emojis and emoji personality
8. Reactions - Reactions given and received
9. Top Words - Your most-used vocabulary
10. Link Behavior - Link sharing stats and top domains
11. Rankings - How you compare to others (percentiles)
12. Achievements - Badges you've earned with rarity %
13. Grand Finale - Summary and celebration

Achievement Categories

The bot features 70+ badges across 8 categories:

• Volume (8 badges): Message count milestones
• Consistency (13 badges): Streaks and dedication
• Communication Style (10 badges): Writing patterns
• Content Type (13 badges): Photos, links, stickers, etc.
• Emoji Expertise (7 badges): Emoji usage
• Reactions (8 badges): Giving and receiving reactions
• Rankings (9 badges): Top positions and percentiles
• Special Behaviors (10 badges): Single-day records, etc.

User Identification

The bot matches users by Telegram user ID. The format in the database is user{telegram_id}.

If users aren't being matched correctly:

1. Check the from_id field in your JSON export
2. The bot automatically handles usernames with special characters by escaping them for HTML.

Customization

Add New Badges

Edit src/achievements.py and add to BADGE_DEFINITIONS:

"my_badge_id": {
    "name": "Badge Name",
    "icon": "🎯",
    "category": "Category",
    "description": "How to earn it",
    "check": lambda s: s.get('some_stat', 0) >= 100
}

Then re-run processing to update the database.

Modify Card Content

Edit src/wrapped_text_cards.py to change the text, emojis, or formatting of the cards. The system uses standard HTML formatting supported by Telegram.

Database Schema

The SQLite database contains:

• user_stats: Main statistics for each user
• daily_activity: Message counts per day per user
• user_rankings: Precomputed percentile rankings
• user_achievements: Earned badges
• badge_stats: Global unlock percentages
• group_stats: Group-level aggregates

Advanced Usage

Automatic Updates

Set up a cron job to:

1. Re-export chat data (if automated)
2. Re-run process_data.py
3. Restart the bot (if needed)

Credit:

Word Exclude list came from @erickhammersmark https://github.com/erickhammersmark/tg_dump_anal/blob/master/exclude.txt