Receive Message

Listens for incoming messages from Telegram in real-time. This is a trigger node that starts new flow executions whenever a message is received.

Common Properties

• Name - The custom name of the node.
• Color - The custom color of the node.
• Delay Before (sec) - Waits in seconds before executing the node.
• Delay After (sec) - Waits in seconds after executing node.
• Continue On Error - Automation will continue regardless of any error. The default value is false.

info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Options

• Bot Token - The Telegram bot token credential used to authenticate with Telegram. Required.
• Filter Chat Id - (Optional) Only process messages from this specific chat. Set to 0 to receive from all chats. Default: 0 (all chats).
• Filter Sender Id - (Optional) Only process messages from this specific sender. Set to 0 to receive from all senders. Default: 0 (all senders).
• Omit Empty Values - Removes null and empty values from the message object for cleaner output. Default: true.
• Auto Download Files - Automatically downloads received files (photos, documents, voice, video notes) to the system temp directory. Default: true.

Output

• Client Id - A unique identifier for the bot client connection that can be used in other Telegram nodes within the same flow execution.
• Message - The complete message object received from Telegram, containing:
  • message_id - Unique message identifier
  • from - Sender information (id, first_name, last_name, username)
  • chat - Chat information (id, type, title)
  • date - Message timestamp (Unix time)
  • text - Message text content (for text messages)
  • photo - Photo information (for photo messages)
  • document - Document information (for document messages)
  • voice - Voice message information
  • video_note - Video note information
  • And many other fields depending on message type

How It Works

The Receive Message node establishes a long-polling connection to Telegram and continuously listens for new messages. When a message is received, the node:

1. Connects to Telegram using the provided Bot Token
2. Starts a long-polling session (60-second timeout)
3. Waits for incoming messages
4. Filters messages based on Chat Id and Sender Id if specified
5. If Auto Download is enabled, downloads any files to the temp directory
6. Removes empty values from the message if Omit Empty Values is enabled
7. Triggers a new flow execution with the message data
8. Continues listening for more messages

The node runs continuously while the flow is active and will trigger a new execution for each matching message received.

Requirements

• A valid Telegram bot token
• The bot must be able to receive messages:
  • For private chats: Users must start a conversation with the bot first
  • For groups: The bot must be added as a member
  • For channels: The bot must be an administrator
• Sufficient storage space if Auto Download is enabled

Error Handling

The node will return errors in the following cases:

• Empty or invalid bot token
• Invalid token format
• Network connectivity issues
• Telegram API errors
• Bot is blocked by the user
• Bot was removed from the group/channel
• File download failures (with retry logic)

Usage Examples

Simple Message Receiver:

Receive Message → Log Message → Send Message (Reply)

Filtered by Chat:

Receive Message (Filter Chat Id: 123456789)
  → Process User Messages
  → Send Response

Command Bot:

Receive Message
  → If (message.text starts with "/start")
    → Send Message ("Welcome!")
  → Else If (message.text starts with "/help")
    → Send Message ("Help info")

File Processor:

Receive Message (Auto Download: true)
  → If (message.document exists)
    → Process Document
    → Send Document (processed file)

Message Object Structure

{
  "message_id": 123,
  "from": {
    "id": 987654321,
    "is_bot": false,
    "first_name": "John",
    "last_name": "Doe",
    "username": "johndoe"
  },
  "chat": {
    "id": 987654321,
    "first_name": "John",
    "last_name": "Doe",
    "username": "johndoe",
    "type": "private"
  },
  "date": 1699876543,
  "text": "Hello bot!"
}

File Download Behavior

When Auto Download Files is enabled:

Supported File Types:

• Photos (.jpg)
• Documents (original extension)
• Voice messages (.ogg)
• Video notes (.mp4)

Download Location:

• Files are saved to the system temp directory
• File naming: telegram_{type}_{timestamp}.{ext}
• Example: telegram_photo_1699876543000.jpg

Retry Logic:

• Automatic retry on temporary failures
• 3 retry attempts with exponential backoff
• 2, 4, 6 second delays between retries

File Information in Message:

{
  "document": {
    "file_id": "BQACAgIAA...",
    "file_unique_id": "AgAD...",
    "file_name": "report.pdf",
    "file_size": 52428,
    "file_path": "/tmp/telegram_document_1699876543000.pdf"
  }
}

Use Cases

Customer Support Bot:

Receive Message
  → Extract Question
  → Query Knowledge Base
  → Send Message (Answer)

File Backup Bot:

Receive Message
  → If (message has document)
    → Upload to Cloud Storage
    → Send Message ("Backed up!")

Command Handler:

Receive Message
  → Parse Command
  → Switch (command)
      Case "/start": Welcome Flow
      Case "/status": Status Check
      Case "/report": Generate Report

Group Moderator:

Receive Message (Filter Chat Id: group_id)
  → If (contains spam keywords)
    → Delete Message
    → Ban User

Best Practices

• Filter strategically - Use Chat Id and Sender Id filters to reduce unnecessary executions
• Handle all message types - Check for text, photos, documents, etc.
• Validate input - Always validate user input before processing
• Implement rate limiting - Prevent spam by tracking message frequency
• Use Try/Catch - Wrap message processing in error handlers
• Clean up files - Delete downloaded files after processing to save space
• Test with privacy mode - Enable/disable privacy mode based on your needs
• Log important events - Track received messages for debugging

Filtering Examples

Single User Bot:

Receive Message:
  Filter Sender Id: 123456789  // Only respond to this user

Group-Specific Bot:

Receive Message:
  Filter Chat Id: -987654321  // Only process messages from this group

Admin Commands:

Receive Message
  → If (message.from.id in adminList AND text starts with "/admin")
    → Execute Admin Command

Common Patterns

Echo Bot:

Receive Message → Send Message (Chat Id: message.chat.id, Message: message.text)

Command Parser:

let text = message.text;
if (text.startsWith('/')) {
  let parts = text.split(' ');
  let command = parts[0];
  let args = parts.slice(1);
  // Process command
}

File Type Handler:

Receive Message
  → If (message.photo)
    → Process Image
  → Else If (message.document)
    → Process Document
  → Else If (message.text)
    → Process Text

Troubleshooting

Bot Not Receiving Messages:

• Verify the bot token is correct
• Check that users have started a conversation with the bot
• Ensure the bot is a member of the group/channel
• Disable privacy mode in @BotFather if needed

Missing Messages:

• Check Filter Chat Id and Filter Sender Id settings
• Verify the bot has necessary permissions
• Check network connectivity

File Download Failures:

• Ensure sufficient disk space
• Check temp directory permissions
• Verify file IDs are valid
• Check network connection

High Memory Usage:

• Disable Auto Download if not needed
• Delete downloaded files after processing
• Use Omit Empty Values to reduce message size
• Monitor the number of concurrent executions

Tips

• This is a trigger node - it has no input connectors and starts new executions
• Each message creates a new, independent flow execution
• The Client Id is unique per message execution
• Privacy mode affects which messages bots can see in groups
• Use the message_id for replying to specific messages
• The chat.id is needed for sending responses back to the sender
• File downloads include retry logic for reliability
• Omit Empty Values makes message objects easier to work with
• The node automatically handles long-polling reconnections