n8n-nodes-telegram-grampro

v6.0.4

Published

a month ago

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

Downloads

1,050

🚀 Telegram GramPro for n8n

The ultimate MTProto automation engine for n8n. Enterprise-grade security, high-performance userbot triggers, and seamless Telegram integration.

📖 Operations Guide | 🔐 Auth Guide | 🔧 Troubleshooting | 📝 Logs

🌟 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), mark history as read/seen, edit, delete, pin, forward, copy, create polls and quizzes
Chats: Get chats, dialogs, join/leave, create groups/channels, send live chat actions like typing or uploading
Users: Get user info, full details with bio and common chats, update profile, change username, update online/offline status, 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 🔗
Read/Seen Messages - Mark private, group, supergroup, and channel history as read up to a selected message ID
Chat Actions - Send typing, recording, uploading, choosing sticker/location/contact, game, animation seen, or cancel indicators
Presence Control - Switch your Telegram account status between online and offline from a workflow
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
```
npm install
```
Build the project
```
npm 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
```
npm install
```
Build the project
```
npm 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
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, Read Messages 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, Send Chat Action | | User | Get My Profile, Get Profiles Photo, Update My Profile, Update My Username, Update My Status, 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:

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.