Telegram GramPro - n8n Integration

Powerful Telegram automation for n8n workflows with session encryption and rate limiting

🚀 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
• ⚡ Smart Rate Limiting - Prevents API limits with intelligent queuing
• 🛡️ Enhanced Error Handling - Automatic retry for flood waits and timeouts
• 🔗 Connection Management - WebSocket support with automatic cleanup
• 📊 Structured Logging - Production-ready logging with debug support

📦 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

   npm install
   

3. Build the project

   npm 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

   npm install
   

4. Build the project

   npm 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)
• 2FA Code (Optional): Your Telegram 2FA code if enabled

🎯 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
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
• 128-bit initialization vectors
• PBKDF2 key derivation with salt
• Authentication tags for integrity

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
• CHAT_WRITE_FORBIDDEN: Permission error handling
• USER_BANNED_IN_CHANNEL: Channel ban detection

Rate Limiting

Prevents hitting Telegram's API rate limits:

• Minimum 1-second interval between requests (configurable)
• Request queuing with priority support
• Queue length monitoring
• Automatic cleanup

📊 Performance Optimized

Smart Client Management

• Automatic connection validation
• Health checks and reconnection
• Resource cleanup and management
• WebSocket support for reliability

Request Queuing

• Priority-based request handling
• Queue length monitoring
• Automatic cleanup
• Configurable intervals

Memory Efficient

• Proper cleanup prevents memory leaks
• Connection pooling
• Resource management
• Background loop prevention

🚨 Troubleshooting

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

Logging

Set a lower log level to reduce terminal noise:

• GRAMPRO_LOG_LEVEL=error|warn|info|debug
• N8N_LOG_LEVEL=error|warn|info|debug (used if GRAMPRO_LOG_LEVEL is not set)

🎨 Workflow Examples

Basic Message Automation

1. Trigger (Webhook, Schedule, etc.)
2. Telegram GramPro (Send Text)
   ├── Chat ID: @channel_name
   ├── Message: "Automated message from n8n"
   └── Disable Link Preview: true
3. Success/Failure handling

User Management Workflow

1. Trigger (New User Registration)
2. Telegram GramPro (Add Member)
   ├── Channel ID: @your_channel
   └── User ID to Add: {{ $json.username }}
3. Telegram GramPro (Send Welcome Message)
   ├── Chat ID: @your_channel
   └── Message: "Welcome {{ $json.name }}!"
4. Success/Failure handling

Content Moderation Workflow

1. Trigger (Message Received)
2. Telegram GramPro (Get Message Content)
3. Content Analysis (External API)
4. Conditional Logic
   ├── If Spam → Ban User
   ├── If Violation → Delete Message
   └── If Clean → Continue
5. Telegram GramPro (Notify Admins)
6. Success/Failure handling

🤝 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
npm install

# Start development mode
npm run dev

# Build for production
npm 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

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

---

Built with ❤️ for n8n automation workflows