n8n-nodes-telegram-userbot

n8n community node for Telegram User Bot (MTProto) using GramJS.

This package allows you to send messages, import contacts, and receive messages using your Telegram account (not a bot).

Features

• Send Messages: Send text messages to any Telegram chat
• Import Contacts: Import contacts by phone number and get their Telegram ID
• Get Dialogs: List your chats and conversations
• Receive Messages: Trigger workflows on incoming messages (with filters)

Installation

In n8n (Docker)

# Add to your n8n docker-compose.yml environment
N8N_COMMUNITY_PACKAGES=n8n-nodes-telegram-userbot

In n8n (npm)

cd ~/.n8n
npm install n8n-nodes-telegram-userbot

Development Install (from source)

cd ~/.n8n/custom
git clone <repository-url>
cd n8n-nodes-telegram-userbot
npm install
npm run build

Setup

1. Get Telegram API Credentials

1. Go to my.telegram.org
2. Log in with your phone number
3. Click on "API development tools"
4. Create a new application
5. Save your API ID and API Hash

2. Generate Session String

The session string authenticates your Telegram account. Generate it once and use it in n8n:

cd n8n-nodes-telegram-userbot
npm install
npm run login

You'll be prompted for:

• Your phone number (e.g., +989123456789)
• Verification code (sent to your Telegram)
• 2FA password (if enabled)

Copy the session string from the output.

3. Configure n8n Credentials

1. In n8n, go to Credentials > New Credential
2. Search for "Telegram User Bot API"
3. Enter:
   • API ID: From my.telegram.org
   • API Hash: From my.telegram.org
   • Session String: From the login script

Usage

Send Message Node

Sends a text message to a Telegram chat.

Parameters:

• Chat ID: Telegram chat ID (numeric) or @username
• Message: Text message to send

Import Contact Node

Imports a contact by phone number and returns their Telegram ID.

Parameters:

• Phone Number: Phone with country code (e.g., +989123456789)
• First Name: Contact's first name
• Last Name: Contact's last name (optional)

Returns:

• userId: The Telegram user ID
• success: Whether the contact was found on Telegram
• username: Their username (if public)

Get Dialogs Node

Lists your recent chats.

Parameters:

• Limit: Maximum number of chats to return

Trigger Node

Triggers on incoming messages.

Filters:

• All Messages: Trigger on everything
• Private Messages Only: Only direct messages
• Group Messages Only: Only group/channel messages
• Specific Chat: Only from one chat ID

Example Workflow: Phone to Telegram ID

[Manual Trigger]
    → [Telegram User Bot: Import Contact]
        → [IF: Check if imported]
            → [Postgres: Update lead with telegram_id]

Security Notes

⚠️ Keep your session string secure! Anyone with this string can access your Telegram account.

• Store credentials in n8n's encrypted credential store
• Never commit session strings to git
• Generate new session if compromised (old sessions auto-invalidate)

Troubleshooting

"User not found on Telegram"

The phone number is not registered on Telegram or uses a different number.

"AUTH_KEY_UNREGISTERED"

Your session has expired. Generate a new one with npm run login.

"FLOOD_WAIT_X"

You're sending too many requests. Wait X seconds before retrying.

License

MIT