Telegram GramPro - n8n Integration

Powerful Telegram automation for n8n workflows with enterprise-grade security, performance optimization, and comprehensive error handling

🚀 Transform Your Telegram Automation

Telegram GramPro is a comprehensive n8n custom node that brings the full power of Telegram's MTProto protocol to your automation workflows. Built with GramJS and designed for production use, it offers enterprise-grade features with an intuitive interface.

🌟 Key Features

Core Operations

• Messages: Send, get messages (time-based filters), edit, delete, pin, forward, copy, create polls and quizzes
• Chats: Get chats, dialogs, join/leave, create groups/channels
• Users: Get user info, full details with bio and common chats, update profile, change username, get profile photos
• Media: Download media files with progress tracking
• Channels: Get participants, manage members, ban/promote users

Enterprise Security & Performance

• 🔐 AES-256-GCM Session Encryption - Military-grade security with automatic key derivation
• ⚡ Smart Rate Limiting - Prevents API limits with intelligent queuing and priority handling
• 🛡️ Enhanced Error Handling - Automatic retry for flood waits, timeouts, and connection issues
• 🔗 Connection Management - Advanced client pooling with health checks and auto-reconnection
• 📊 Structured Logging - Production-ready logging with configurable levels and context
• 🧠 Smart Caching - In-memory caching for frequently accessed data with TTL management
• 🎯 Input Validation - Comprehensive validation with detailed error messages and warnings

New Advanced Features

• Copy Restricted Content - Handle media that cannot be forwarded normally
• Edit Message Media - Update media content in existing messages with caption support
• Enhanced Authentication - Improved session management with better error handling
• Memory Optimization - Automatic cleanup and resource management
• Performance Monitoring - Built-in metrics and queue monitoring

📦 Installation

Method 1: n8n Community Nodes (Recommended)

1. Open n8n UI
2. Go to Settings → Community Nodes
3. Add in box "n8n-nodes-telegram-grampro"
4. Click checkbox to allow to use external nodes.
5. Click Install
6. Restart n8n to load the custom node

Method 2: Custom Nodes Directory

1. Clone to n8n custom nodes directory
2. Install dependencies

   pnpm install
   

3. Build the project

   pnpm run build
   

4. Restart n8n to load the custom node

Method 3: GitHub Installation

1. Clone from GitHub

   git clone https://github.com/sadiakant/n8n-nodes-telegram-grampro.git
   

2. Move to n8n custom nodes directory
3. Install dependencies

   pnpm install
   

4. Build the project

   pnpm run build
   

5. Restart n8n to load the custom node

⚙️ Quick Setup

1. Get API Credentials

• Visit my.telegram.org
• Create new application
• Note your API ID and API Hash

2. Create Session String

Use our built-in authentication operations. For detailed step-by-step instructions, see our Authorization Guide.

3. Configure Credentials

In n8n → Settings → Credentials:

• API ID: Your Telegram API ID
• API Hash: Your Telegram API hash
• Session String: Your encrypted session string
• Mobile Number: Your Telegram mobile number with country code (e.g., +1234567890)
• Validation: Save/Test performs real MTProto getMe verification.
• UI Note: n8n may still show the generic label Connection tested successfully on the global credentials page.

🎯 Comprehensive Operations Guide

For detailed documentation of all operations with parameters, examples, and use cases, see our Operations Guide.

🔧 Available Operations

Resource	Operations
Session Generator	Request Code, Sign In & Generate
Message	Send Text, Get Messages, Edit, Delete, Pin, Forward, Copy, Edit Media, Create Poll, Copy Restricted Content
Chat	Get Chat, Get Dialogs, Join Channel/Group, Leave Channel/Group, Create Group/Channel
User	Get User Info, Get Full User Details, Update Profile, Change Username, Get Profile Photo
Media	Download Media Files
Channel	Get Admin & Bots, Get Public Members, Add/Remove Member, Ban/Unban User, Promote to Admin

🛡️ Security Features

Session Encryption

All session strings are automatically encrypted using AES-256-GCM with:

• 256-bit encryption keys derived from your API credentials
• 128-bit initialization vectors with PBKDF2 key derivation
• Authentication tags for integrity verification
• Automatic encryption/decryption transparent to users
• Secure storage prevents session exposure

Input Validation

Comprehensive validation ensures data integrity and security:

• API credentials validation (ID format, Hash length)
• Phone number format validation (international format)
• Session string validation and integrity checks
• Operation-specific parameter validation
• Real-time warnings for potential issues

Enhanced Error Handling

The node handles common Telegram errors gracefully:

• FLOOD_WAIT: Automatic retry with specified wait time
• AUTH_KEY_DUPLICATED: Clear error message about session conflicts
• SESSION_REVOKED: Guidance to re-authenticate
• USER_DEACTIVATED_BAN: Account ban detection
• PEER_FLOOD: Extended wait times for peer flooding
• NETWORK_TIMEOUT: Exponential backoff retries (up to 5 attempts)
• CHAT_WRITE_FORBIDDEN: Permission error handling
• USER_BANNED_IN_CHANNEL: Channel ban detection
• AUTH_KEY_UNREGISTERED: Session is invalid or expired and must be regenerated
• SESSION_EXPIRED: Session expired and must be renewed
• USER_PRIVACY_RESTRICTED: Action blocked by user privacy settings
• CHANNEL_PRIVATE: Channel or group is private/inaccessible
• USERNAME_NOT_OCCUPIED / USERNAME_INVALID: Username does not exist or has invalid format
• INVITE_HASH_INVALID / INVITE_HASH_EXPIRED: Invite link is invalid or expired
• PEER_ID_INVALID / MESSAGE_ID_INVALID: Chat/message identifiers are invalid

⚡ Performance Optimizations

Smart Client Management

• Connection Pooling: Reuses existing TelegramClient instances via Map cache
• Race Condition Prevention: Connection locks prevent multiple simultaneous connections
• Health Monitoring: Automatic connection validation and healing
• Auto-cleanup: 30-minute stale connection detection and cleanup
• Reconnection Logic: Automatic reconnection for failed connections
• Session Encryption: Transparent AES-256-GCM session decryption

Intelligent Rate Limiting

• Configurable request intervals (minimum 1-second)
• Priority-based request queuing with queue length monitoring
• DoS protection with maximum queue size limits (1000 requests)
• Automatic cleanup of stale requests
• Enhanced Telegram API limit compliance

Smart Caching

In-memory caching for frequently accessed data:

• User information caching (5-minute TTL)
• Chat/channel metadata caching
• Dialog lists caching
• Automatic cache cleanup and size management
• Configurable cache TTL and maximum size

Memory Efficient Design

• Proper cleanup prevents memory leaks
• Connection pooling and resource management
• Background loop prevention
• Optimized data structures and algorithms
• Automatic resource cleanup

Enhanced Request Handling

• Binary File Upload: Support for photos, videos, documents with automatic format detection
• Media URL Support: Direct URL upload with fallback to download-and-upload
• Progress Tracking: Real-time download progress for large media files
• Error Recovery: Automatic retry for network timeouts and connection issues

🚨 Troubleshooting

For comprehensive troubleshooting guidance, common issues, and solutions, see our Troubleshooting Guide.

Project Structure

n8n-nodes-telegram-grampro/
|-- .github/                       # GitHub specific configuration & metadata
|   |-- workflows/                 # CI/CD pipelines (Build & Publish)
|   |-- CODE_OF_CONDUCT.md         # Community guidelines
|   |-- CONTRIBUTING.md            # Instructions for developers
|   |-- LICENSE                    # Legal usage rights
|   `-- SECURITY.md                # Security policy and reporting
|-- docs/                          # Extended documentation & manuals
|   |-- AUTHORIZATION_GUIDE.md     # Steps for Telegram API auth
|   |-- OPERATIONS_GUIDE.md        # Detailed node usage instructions
|   |-- TROUBLESHOOTING_GUIDE.md   # Common errors and fixes
|   `-- Workflows-Examples/        # Ready-to-import n8n workflow JSON files
|       |-- Send messages from one user to multiple users.json
|       `-- Send messages from folder chats to user.json
|-- src/                           # Source code
|   |-- core/                      # Core logic (Rate limiting, Encryption, Auth)
|   |-- credentials/               # n8n Credential definitions
|   |-- nodes/                     # n8n Node implementations (Main & Trigger)
|   |   |-- icons/                 # Brand assets
|   |   `-- resources/             # API resource operations (Chat, Media, etc.)
|   |-- types/                     # TypeScript interfaces & types
|   `-- index.ts                   # Library entry point
|-- .gitignore                     # Files excluded from version control
|-- copy-assets.mjs                # Build script for static assets
|-- esbuild.config.mjs             # Fast bundling configuration
|-- package.json                   # Dependencies and pnpm scripts
|-- README.md                      # Project overview and quick start
`-- tsconfig.json                  # TypeScript compiler settings

Workflow Examples

Ready-to-import workflow examples are available in docs/Workflows-Examples:

• Send messages from one user to multiple users.json
• Send messages from folder chats to user.json

How to Import in n8n

1. Open n8n and create a new workflow.
2. Use the workflow menu and select Import from File.
3. Choose one of the JSON files from docs/Workflows-Examples/.
4. Re-map telegramApi credentials to your own Telegram GramPro credential.
5. Replace placeholders such as source/target chats, admin usernames, and sub-workflow IDs.

What These Examples Cover

• Send messages from one user to multiple users.json: Pulls recent messages from one source, filters by recency and keyword/domain, then distributes to multiple target chats with flood-wait and error notifications.
• Send messages from folder chats to user.json: Reads dialogs grouped by folders, filters recent media messages, then forwards matched content to a target user with scheduling and error handling.

Advanced Configuration

Environment Variables

• GRAMPRO_LOG_LEVEL=error|warn|info|debug - Control log verbosity
• N8N_LOG_LEVEL=error|warn|info|debug - Fallback if GRAMPRO_LOG_LEVEL not set

Performance Tuning

• Rate Limiting: Adjust intervals based on your usage patterns
• Cache Size: Configure maximum cache entries for your memory constraints
• Connection Timeout: Set appropriate timeouts for your network conditions
• Retry Attempts: Configure retry logic for your reliability requirements

Security Best Practices

• Always use encrypted session strings
• Keep API credentials secure and never expose them in workflow outputs
• Enable 2FA for your Telegram account
• Regularly rotate session strings
• Monitor logs for security events

🤝 Contributing

We welcome contributions to make Telegram GramPro even better!

Contribution Guidelines

1. Fork the repository
2. Create a feature branch
3. Make your changes with proper TypeScript types
4. Add tests for new functionality
5. Update documentation
6. Submit a pull request

Development Setup

# Clone the repository
git clone https://github.com/sadiakant/n8n-nodes-telegram-grampro.git

# Install dependencies
pnpm install

# Start development mode
pnpm run dev

# Build for production
pnpm run build

Code Standards

• Use TypeScript for type safety
• Follow existing code patterns
• Add comprehensive error handling
• Include proper documentation
• Test thoroughly before submitting

📄 License

MIT License - see LICENSE file for details.

🔗 Resources

• Telegram API Documentation
• GramJS Documentation
• n8n Custom Nodes Guide
• Telegram GramPro GitHub
• NPM Package

👥 Contributors

Core Development Team

Contributor	Role	Expertise & Contributions
Sadiakant	Project Lead & Developer	🔧 Architecture & Development • Overall project architecture and design • Core node implementation and authentication system • TypeScript development and API integration • Production deployment and optimization
DeepSeek AI	Concept & Ideas	💡 Innovation & Strategy • Initial project structure and feature suggestions • Technical concept development • Architecture planning and design patterns • Feature roadmap and enhancement ideas
ChatGPT AI	Implementation Strategy	🏗️ Code Architecture • Code structure guidance and implementation strategy • Best practices and coding standards • Integration patterns and API design • Documentation and code organization
Cline AI	Development & Coding	💻 Code Implementation • Complete codebase development and testing • Performance optimization and debugging • Automated testing and CI/CD integration • Code review and quality assurance
Gemini AI	Quality Assurance	🔍 Testing & Debugging • Error resolution and performance optimization • Code review and quality assurance • Bug detection and fix validation • Security analysis and vulnerability assessment

Technology Stack

Recent Major Improvements

Performance & Reliability Enhancements

• Advanced Client Management: Implemented connection pooling with automatic health checks and reconnection logic
• Smart Rate Limiting: Added priority-based queuing with configurable intervals and DoS protection
• Memory Optimization: Automatic cleanup prevents memory leaks with proper resource management
• Enhanced Error Recovery: Exponential backoff retries for network timeouts and connection issues

Security & Data Protection

• AES-256-GCM Encryption: Military-grade session encryption with automatic key derivation from API credentials
• Comprehensive Input Validation: Multi-layered validation with detailed error messages and security warnings
• Session Management: Secure session handling with integrity checks and automatic cleanup

New Advanced Features

• Copy Restricted Content: Handle media that cannot be forwarded normally with download-and-upload fallback
• Edit Message Media: Update media content in existing messages with caption and formatting support
• Enhanced Authentication: Improved session generation with better error handling and validation
• Smart Caching: In-memory caching for frequently accessed data with TTL management

Developer Experience

• Structured Logging: Configurable log levels with context-rich messages for debugging
• Comprehensive Documentation: Updated guides with new features and troubleshooting
• Type Safety: Full TypeScript implementation with comprehensive type definitions
• Error Handling: Detailed error messages with actionable guidance

Collaboration Excellence

• 🤖 AI-Powered Development: Cutting-edge AI assistance for code generation and optimization
• ✅ Quality Assurance: Multi-layered review process ensuring code quality and security
• 🚀 Innovation: Latest technologies and best practices implementation
• 🔧 Expert Integration: Professional-grade code integration and deployment
• ⚡ Performance Focus: Enterprise-grade performance optimization and monitoring
• 🛡️ Security First: Military-grade security with comprehensive validation
• 📊 Production Ready: Built for enterprise environments with monitoring and logging

---

Built with ❤️ for n8n automation workflows