🌟 Why Telegram GramPro?

Most Telegram n8n nodes use the standard Bot API, which is restricted by Telegram's bot policies. GramPro uses the MTProto protocol (via Teleproto), allowing you to automate User Accounts and Channels with the full power of a native Telegram client.

🚀 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 Teleproto 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

• Deleted Message Trigger - Catch deletions with content recovery via snapshot memory 🗑️

• User Update Trigger - Monitor real-time online/offline status and bio changes 👤

• Teleproto Engine - Migrated to a more stable core to handle massive supergroups 📡

• Topic Support - Get History now supports direct Thread/Topic URLs 🔗

• 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

Note: If you have trouble updating the node in the n8n UI, uninstall (remove) the GramPro node first, then perform a fresh install to resolve the issue.

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
• Validation: Save/Test performs real MTProto getMe verification.

🎯 Comprehensive Operations Guide

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

🔧 Available Operations

Resource	Operations
Auth	Request Login Code, Resend Login Code, Sign in, Request QR Login, Complete QR Login
Message	Send Message, Get Chat History, Edit, Delete, Pin, Forward, Copy, Edit Media, Create Poll, Copy Restricted Content, Clear History, Unpin Message
Chat	Get Chat Info, Get Chats List, Join Channel/Group, Leave Channel/Group, Create Group/Channel
User	Get My Profile, Get Profiles Photo, Update My Profile, Update My Username, Get User Profile (Bio & Common Chats)
Media	Download Media Files
Channel	Add Member, Remove Member, Ban User, Unban User, Promote to Admin, Get Members

🛡️ 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 text-aware send flows plus photos, videos, documents, and other file types where applicable
• 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/
├── 📄 Root Files
│   ├── .gitignore, .prettierrc.js, eslint.config.mjs
│   ├── LICENSE, README.md
│   ├── package.json, package-lock.json
│   └── tsconfig.json
│
├── 🐙 .github/
│   ├── CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md
│   └── workflows/
│       ├── build.yml
│       └── publish.yml
│
├── 🔐 credentials/
│   ├── TelegramGramProApi.credentials.ts
│   └── telegram-grampro-credentials.svg
│
├── 📚 docs/
│   ├── AUTHORIZATION_GUIDE.md
│   ├── CHANGE_LOG.md
│   ├── OPERATIONS_GUIDE.md
│   └── TROUBLESHOOTING_GUIDE.md
│
└── ⚡ nodes/
    ├── 📦 TelegramGramPro/
    │   ├── TelegramGramPro.node.ts
    │   ├── telegram-grampro.svg
    │   ├── core/
    │   │   ├── cache.ts, clientManager.ts, fileSizeUtils.ts, 
    │   │   ├── floodWaitHandler.ts, logger.ts,  
    │   │   ├── messageFormatting.ts, operationHelpers.ts,
    │   │   ├── payloadBuilders.ts, qrPng.ts, 
    │   │   ├── rateLimiter.ts, sessionEncryption.ts,
    │   │   └── telegramErrorMapper.ts, types.ts, validation.ts
    │   │
    │   └── resources/
    │       ├── authentication.operations.ts
    │       ├── channel.operations.ts
    │       ├── chat.operations.ts
    │       ├── media.operations.ts
    │       ├── message.operations.ts
    │       └── user.operations.ts
    │
    └── 🔔 TelegramGramProTrigger/
        ├── TelegramGramProTrigger.node.ts
        ├── trigger.shared.ts
        └── telegram-grampro.svg

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 telegramGramProApi credentials to your own Telegram GramPro credential.
5. Replace placeholders such as source/target chats, admin usernames, and sub-workflow IDs.

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

👥 Contributors

⭐ Star History

Publishing Status

NPM Status

GitHub Status

Dependency Status

📄 License

MIT License - see LICENSE file for details.

🔗 Resources

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

---

Built with ❤️ for n8n automation workflows