Telegram Copilot

A Python-based Telegram account management system that provides comprehensive control over your Telegram dialogs, messages, and media. Built with Telethon, this tool allows you to manage and analyze your Telegram data programmatically.

Features

• List and filter dialogs (chats, groups, channels)
• Access dialog folders
• Search through messages with various filters
• Handle media messages (photos, videos, documents)
• Date-based message filtering
• Comprehensive dialog and message information

Project Structure

telegram-copilot/
├── src/
│   ├── core/           # Core functionality
│   ├── models/         # Data models
│   ├── services/       # Business logic
│   └── utils/          # Helper functions
├── examples/           # Usage examples
└── tests/             # Test cases

Requirements

• Python 3.8+
• Telegram API credentials (API ID and Hash)

Quick Start

1. Clone the repository:

git clone https://github.com/yourusername/telegram-copilot.git
cd telegram-copilot

2. Create and activate a virtual environment:

python -m venv venv
# On Windows:
venv\Scripts\activate
# On Unix or MacOS:
source venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Create a .env file in the project root with your Telegram API credentials:

TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_2FA_PASSWORD=your_2fa_password  # Only if you have 2FA enabled

To get your Telegram API credentials:

1. Visit https://my.telegram.org/auth
2. Log in with your phone number
3. Go to 'API development tools'
4. Create a new application
5. Copy the API ID and API Hash

Usage

Check out the examples directory for usage demonstrations. Here's a basic example:

from src.core.client import TelegramCopilotClient
from src.services.dialog_service import DialogService
from src.services.message_service import MessageService

async def main():
    async with TelegramCopilotClient() as client:
        dialog_service = DialogService(client)
        message_service = MessageService(client)
        
        # Get all dialogs
        dialogs = await dialog_service.get_all_dialogs()
        for dialog in dialogs:
            print(f"{dialog.dialog_type}: {dialog.name}")
            
        # Get recent messages from a dialog
        if dialogs:
            messages = await message_service.get_messages(dialogs[0].id, limit=10)
            for msg in messages:
                print(f"[{msg.date}] {msg.text}")

if __name__ == "__main__":
    asyncio.run(main())

Run the example script:

python examples/basic_usage.py

Features in Detail

Dialog Management

• List all dialogs
• Filter by type (user, group, channel, bot)
• Search dialogs by name
• Access dialog folders
• Get unread message counts

Message Management

• Fetch messages with pagination
• Filter by date range
• Search message content
• Handle different media types
• Access message metadata (forwards, replies, edits)

Filtering Capabilities

• Dialog filters:

  • By type (user/group/channel/bot)
  • By name
  • By unread status
  • By archived status

• Message filters:

  • By date range
  • By media type
  • By content
  • By sender
  • With/without media

Security

• Never commit your .env file or share your API credentials
• The .gitignore file is configured to exclude sensitive files
• Session files are stored locally and are also excluded from git

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Future Plans

• Web UI for easier interaction
• Message statistics and analytics
• Bulk message management
• Enhanced media handling
• Export/backup functionality