n8n-nodes-telegram-grampro

v5.0.1

Published

2 days ago

Telegram GramPro is Advanced n8n node for Telegram MTProto automation using GramJS, featuring user account triggers and 2FA support.

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)

Open n8n UI
Go to Settings → Community Nodes
Add in box "n8n-nodes-telegram-grampro"
Click checkbox to allow to use external nodes.
Click Install
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

Clone to n8n custom nodes directory
Install dependencies
```
pnpm install
```
Build the project
```
pnpm run build
```
Restart n8n to load the custom node

Method 3: GitHub Installation

Clone from GitHub

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

Move to n8n custom nodes directory
Install dependencies
```
pnpm install
```
Build the project
```
pnpm run build
```
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 Login Code, Resend Login Code, Complete Login, Request QR Login, Complete QR Login | | 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/
│   .editorconfig
│   .gitignore
│   .n8nignore
│   .prettierrc.js
│   eslint.config.mjs
│   gulpfile.js
│   LICENSE
│   package.json
│   pnpm-lock.yaml
│   pnpm-workspace.yaml
│   README.md
│   tsconfig.json
│
├───.github
│   │   CODE_OF_CONDUCT.md
│   │   CONTRIBUTING.md
│   │   SECURITY.md
│   │
│   └───workflows
│           build.yml
│           publish.yml
│
├───.vscode
│       settings.json
│
├───docs
│   │   AUTHORIZATION_GUIDE.md
│   │   OPERATIONS_GUIDE.md
│   │   TROUBLESHOOTING_GUIDE.md
│   │
│   ├───assets
│   │   │   n8n-nodes-telegram-grampro.png
│   │   │   n8n_nodes_0.png
│   │   │
│   │   ├───phone-login
│   │   │       phone_workflow_overview.jpg
│   │   │       step1_request_code.jpg
│   │   │       step2_resend_code.jpg
│   │   │       step3_sign_in.jpg
│   │   │
│   │   └───qr-login
│   │           step1_tele_settings.jpg
│   │           step2_tele_link_device.jpg
│   │           step3_n8n_workflow.jpg
│   │           step4_n8n_qr_output.jpg
│   │           step5_n8n_session_output.jpg
│   │
│   └───Workflows-Examples
│           Send messages from folder chats to user.json
│           Send messages from one user to multiple users.json
│
└───src
    │   index.ts
    │
    ├───core
    │       cache.ts
    │       clientManager.ts
    │       floodWaitHandler.ts
    │       logger.ts
    │       operationHelpers.ts
    │       rateLimiter.ts
    │       sessionEncryption.ts
    │       telegramErrorMapper.ts
    │       validation.ts
    │
    ├───credentials
    │       telegram-grampro-credentials.svg
    │       TelegramApi.credentials.ts
    │
    ├───nodes
    │   │   telegram-grampro.svg
    │   │   TelegramMtproto.node.ts
    │   │   TelegramTrigger.node.ts
    │   │
    │   └───resources
    │           authentication.operations.ts
    │           channel.operations.ts
    │           chat.operations.ts
    │           media.operations.ts
    │           message.operations.ts
    │           user.operations.ts
    │
    └───types
            telegram.ts

Workflow Examples

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

How to Import in n8n

Open n8n and create a new workflow.
Use the workflow menu and select Import from File.
Choose one of the JSON files from docs/Workflows-Examples/.
Re-map telegramGramProApi credentials to your own Telegram GramPro credential.
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

Fork the repository
Create a feature branch
Make your changes with proper TypeScript types
Add tests for new functionality
Update documentation
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

👥 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 |