n8n-nodes-n8ntools-telegram

v1.0.3

Published

3 months ago

N8N Tools Telegram Enhanced node with comprehensive Telegram Bot API support

0High
0Medium
0Low

n8ntools.oficial

n8n-community-node-package telegram bot messaging channels groups webhooks

N8N Tools - Telegram Enhanced

Complete Telegram integration with 60+ operations covering the full Telegram Bot API ecosystem. This N8N community node provides comprehensive access to Messages, Media, Chats, Users, Inline queries, Payments, and Advanced Bot features that are missing from the official Telegram node.

✨ Features

📨 Advanced Messaging: Send, edit, delete messages with rich formatting, keyboards, and media
🎯 Inline Mode: Handle inline queries and results for seamless bot interactions
💰 Payments Integration: Process payments through Telegram's payment system
👥 Chat Management: Manage groups, channels, and private chats with full admin controls
📊 Poll System: Create, manage, and analyze polls with detailed results
🎮 Game Integration: Manage Telegram games and high scores
📎 File Handling: Upload, download, and manage files up to 50MB
🎯 Callback Queries: Handle button presses and interactive elements
🔐 User Management: Manage chat members, permissions, and restrictions
🔒 Secure API: Powered by N8N Tools platform with usage tracking and validation

🚀 Quick Start

Installation

Install this node in your N8N instance:

Via Community Nodes (Recommended)

Go to Settings > Community Nodes in your N8N interface
Click Install a community node
Enter n8n-nodes-n8ntools-telegram-enhanced
Click Install

Via npm

npm install n8n-nodes-n8ntools-telegram-enhanced

Setup Credentials

Sign up at N8N Tools and get your API key
In N8N, create new N8N Tools API credentials
Enter your API URL: https://api.n8ntools.io
Enter your API key

📋 Available Resources

📨 Messages (12 Operations)

Advanced message handling beyond the official node:

| Operation | Description | Official Node | Enhanced | |-----------|-------------|---------------|----------| | Send Message | Send text messages | ✅ Basic | ✅ Full API | | Send Photo | Send photo messages | ✅ Basic | ✅ Full API | | Send Video | Send video messages | ✅ Basic | ✅ Full API | | Send Audio | Send audio files | ❌ | ✅ | | Send Document | Send any file type | ❌ | ✅ | | Send Animation | Send GIF animations | ❌ | ✅ | | Send Voice | Send voice messages | ❌ | ✅ | | Send Video Note | Send circular video messages | ❌ | ✅ | | Send Media Group | Send multiple media as album | ❌ | ✅ | | Edit Message | Modify sent messages | ❌ | ✅ | | Delete Message | Remove messages | ❌ | ✅ | | Forward Message | Forward messages between chats | ❌ | ✅ |

💬 Chats (10 Operations)

Comprehensive chat management:

Get Chat: Retrieve chat information and settings
Set Chat Title: Change group/channel titles
Set Chat Description: Update chat descriptions
Set Chat Photo: Change chat profile photos
Delete Chat Photo: Remove chat photos
Pin Message: Pin important messages
Unpin Message: Unpin messages
Leave Chat: Bot leaves group/channel
Get Chat Administrators: List chat admins
Get Chat Member Count: Get member statistics

👥 Members (8 Operations)

Advanced member management:

Get Chat Member: Get member information and permissions
Kick Chat Member: Remove members from chat
Unban Chat Member: Unban previously banned members
Restrict Chat Member: Apply restrictions to members
Promote Chat Member: Grant admin privileges
Set Administrator Title: Set custom admin titles
Export Chat Invite Link: Generate invite links
Create Chat Invite Link: Create custom invite links

📊 Polls (5 Operations)

Complete polling system:

Send Poll: Create polls with multiple options
Stop Poll: End active polls
Send Quiz: Create quiz-style polls with correct answers
Get Poll Results: Retrieve detailed poll statistics
Send Dice: Send animated dice, darts, or other games

🎯 Inline Mode (6 Operations)

Inline query handling:

Answer Inline Query: Respond to inline queries
Answer Callback Query: Handle button press callbacks
Set Chat Menu Button: Customize bot menu button
Get Chat Menu Button: Retrieve menu button settings
Set My Commands: Set bot command list
Get My Commands: Retrieve bot commands

💰 Payments (7 Operations)

Telegram payments integration:

Send Invoice: Create payment invoices
Answer Shipping Query: Handle shipping calculations
Answer Pre Checkout Query: Validate pre-checkout data
Create Invoice Link: Generate payment links
Get Star Transactions: View Telegram Stars transactions
Refund Star Payment: Process refunds
Set Passport Data Errors: Handle passport verification

🎮 Games (4 Operations)

Game management system:

Send Game: Send game messages
Set Game Score: Update player scores
Get Game High Scores: Retrieve leaderboards
Answer Game Query: Handle game callbacks

📎 Files (5 Operations)

File management operations:

Get File: Retrieve file information
Download File: Download files from Telegram
Upload File: Upload files to Telegram
Set Sticker Set Thumb: Set sticker pack thumbnails
Delete Sticker From Set: Remove stickers from sets

🔧 Bot Management (8 Operations)

Bot configuration and settings:

Get Me: Get bot information
Log Out: Log out bot session
Close: Close bot session
Set Webhook: Configure webhook endpoint
Delete Webhook: Remove webhook configuration
Get Webhook Info: Check webhook status
Get Updates: Get pending updates
Set My Name: Set bot name and description

💡 Usage Examples

Send Rich Message with Inline Keyboard

// Configuration
Resource: "Messages"
Operation: "Send Message"
Chat ID: "123456789"
Request Body: {
  "text": "Choose your subscription plan:",
  "reply_markup": {
    "inline_keyboard": [[
      {
        "text": "Basic - $9.99",
        "callback_data": "plan_basic"
      },
      {
        "text": "Pro - $19.99",
        "callback_data": "plan_pro"
      }
    ], [{
      "text": "Premium - $29.99",
      "callback_data": "plan_premium"
    }]]
  },
  "parse_mode": "Markdown"
}

// Output
{
  "resource": "messages",
  "operation": "sendMessage",
  "success": true,
  "message_id": 123,
  "chat": {
    "id": 123456789,
    "type": "private"
  },
  "text": "Choose your subscription plan:",
  "creditsUsed": 1,
  "creditsRemaining": 99
}

Create Interactive Poll

// Send Poll
Resource: "Polls"
Operation: "Send Poll"
Chat ID: "@mychannel"
Request Body: {
  "question": "What's your favorite programming language?",
  "options": ["Python", "JavaScript", "TypeScript", "Go", "Rust"],
  "is_anonymous": false,
  "allows_multiple_answers": true,
  "open_period": 86400
}

// Send Quiz with Correct Answer
Resource: "Polls"
Operation: "Send Quiz"
Chat ID: "123456789"
Request Body: {
  "question": "What is the capital of France?",
  "options": ["London", "Berlin", "Paris", "Madrid"],
  "correct_option_id": 2,
  "explanation": "Paris is the capital and largest city of France.",
  "explanation_parse_mode": "Markdown"
}

Handle Payment Processing

// Send Invoice
Resource: "Payments"
Operation: "Send Invoice"
Chat ID: "123456789"
Request Body: {
  "title": "Premium Subscription",
  "description": "Get access to premium features for 1 month",
  "payload": "premium_monthly_001",
  "provider_token": "YOUR_PAYMENT_PROVIDER_TOKEN",
  "currency": "USD",
  "prices": [{
    "label": "Premium Plan",
    "amount": 999
  }],
  "photo_url": "https://example.com/premium-badge.png",
  "need_email": true,
  "send_email_to_provider": true
}

// Answer Pre-checkout Query
Resource: "Payments"
Operation: "Answer Pre Checkout Query"
Request Body: {
  "pre_checkout_query_id": "query_id_from_webhook",
  "ok": true
}

Manage Chat Members

// Promote User to Admin
Resource: "Members"
Operation: "Promote Chat Member"
Chat ID: "-100123456789"
User ID: "987654321"
Request Body: {
  "can_manage_chat": true,
  "can_post_messages": true,
  "can_edit_messages": true,
  "can_delete_messages": true,
  "can_manage_video_chats": true,
  "can_restrict_members": true,
  "can_promote_members": false
}

// Restrict User Permissions
Resource: "Members"
Operation: "Restrict Chat Member"
Chat ID: "-100123456789"
User ID: "987654321"
Request Body: {
  "permissions": {
    "can_send_messages": false,
    "can_send_media_messages": false,
    "can_send_polls": false,
    "can_send_other_messages": false,
    "can_add_web_page_previews": false,
    "can_change_info": false,
    "can_invite_users": false,
    "can_pin_messages": false
  },
  "until_date": 1640995200
}

Handle Media and Files

// Send Media Group (Album)
Resource: "Messages"
Operation: "Send Media Group"
Chat ID: "123456789"
Request Body: {
  "media": [{
    "type": "photo",
    "media": "https://example.com/photo1.jpg",
    "caption": "First photo"
  }, {
    "type": "photo",
    "media": "https://example.com/photo2.jpg",
    "caption": "Second photo"
  }, {
    "type": "video",
    "media": "https://example.com/video.mp4",
    "caption": "A cool video"
  }]
}

// Upload and Send Document
Resource: "Messages"
Operation: "Send Document"
Chat ID: "123456789"
Request Body: {
  "document": "https://example.com/report.pdf",
  "caption": "Monthly report",
  "reply_markup": {
    "inline_keyboard": [[{
      "text": "Download PDF",
      "url": "https://example.com/download/report.pdf"
    }]]
  }
}

⚙️ Configuration Options

Message Formatting

Parse Mode: HTML, Markdown, or MarkdownV2
Disable Web Page Preview: Control link previews
Disable Notifications: Silent message delivery
Protect Content: Prevent message forwarding
Reply Parameters: Reply to specific messages

Bot Settings

Webhook URL: Real-time updates endpoint
Allowed Updates: Filter specific update types
Drop Pending Updates: Clear pending updates
Secret Token: Secure webhook validation

Advanced Request Options

Request Body: JSON payload for operations
Chat ID: Target chat identifier
User ID: Target user identifier
Additional Options: Polling, file handling, and formatting

🛠️ Example Workflows

Customer Support Bot

[User Message] → [Telegram Enhanced: Get Updates] → [Process Intent] → [Telegram Enhanced: Send Message] → [Log Conversation]

E-commerce Bot

[Product Inquiry] → [Show Catalog] → [Telegram Enhanced: Send Invoice] → [Process Payment] → [Order Confirmation]

Group Management

[New Member] → [Telegram Enhanced: Get Chat Member] → [Verify User] → [Set Permissions] → [Send Welcome Message]

Poll Analytics

[Create Poll] → [Telegram Enhanced: Send Poll] → [Collect Responses] → [Analyze Results] → [Generate Report]

📊 Comparison with Official Telegram Node

| Feature Category | Official Node | Telegram Enhanced | Improvement | |------------------|---------------|-------------------|-------------| | Messages | 4 operations | 12 operations | +200% | | Chats | 0 operations | 10 operations | ∞ (new) | | Members | 0 operations | 8 operations | ∞ (new) | | Polls | 0 operations | 5 operations | ∞ (new) | | Inline Mode | 0 operations | 6 operations | ∞ (new) | | Payments | 0 operations | 7 operations | ∞ (new) | | Games | 0 operations | 4 operations | ∞ (new) | | Files | 0 operations | 5 operations | ∞ (new) | | Bot Management | 1 operation | 8 operations | +700% | | Total Operations | 5 operations | 65 operations | +1200% |

🔧 API Endpoints

All operations are routed through N8N Tools API for consistent authentication and usage tracking:

| Resource | Base Endpoint | |----------|---------------| | Messages | /api/v1/telegram-enhanced/messages/ | | Chats | /api/v1/telegram-enhanced/chats/ | | Members | /api/v1/telegram-enhanced/members/ | | Polls | /api/v1/telegram-enhanced/polls/ | | Inline Mode | /api/v1/telegram-enhanced/inline/ | | Payments | /api/v1/telegram-enhanced/payments/ | | Games | /api/v1/telegram-enhanced/games/ | | Files | /api/v1/telegram-enhanced/files/ | | Bot Management | /api/v1/telegram-enhanced/bot/ |

🚨 Error Handling

The node provides comprehensive error handling with detailed messages:

{
  "error": "CHAT_NOT_FOUND",
  "success": false,
  "resource": "messages",
  "operation": "sendMessage",
  "details": {
    "issue": "The specified chat ID does not exist or bot was blocked",
    "field": "chat_id",
    "value": "INVALID_CHAT_ID",
    "error_code": 400
  }
}

💸 Pricing & Limits

Standard Operations: 1 credit per API call
Complex Operations: 2-3 credits (media uploads, payment processing)
List Operations: 1 credit per page
Monthly Quotas: Based on your N8N Tools subscription plan
Rate Limits: Based on your subscription tier
Usage Tracking: Real-time credit monitoring

🔧 Troubleshooting

Common Issues

Authentication Errors

Verify N8N Tools API key is valid and active
Check API URL is set to https://api.n8ntools.io
Ensure sufficient credits in your account

Bot Token Issues

Verify bot token is valid and active
Check bot permissions for target chats
Ensure bot is added to groups/channels

Message Delivery Errors

Verify chat ID exists and is accessible
Check if bot was blocked by user
Ensure message content follows Telegram guidelines

File Upload Limits

Telegram limits files to 50MB for bots
Use appropriate file types for media
Ensure URLs are publicly accessible

📈 Performance Tips

Batch Operations: Use media groups for multiple files
Webhook Usage: Use webhooks instead of polling for real-time updates
Message Caching: Cache frequently sent messages and media
Error Handling: Implement retry logic for temporary failures
Rate Limiting: Respect Telegram's rate limits (30 messages/second)

🆘 Support

Documentation: docs.n8ntools.io
API Reference: api.n8ntools.io/docs
Community: Discord
Email: [email protected]

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by N8N Tools