Telegram trigger

Overview

Triggers a workflow when a Telegram bot receives updates via webhook. Supports filtering by update type (message, edited_message, channel_post, edited_channel_post, inline_query, callback_query, shipping_query, pre_checkout_query, poll). Can optionally filter by chat ID or user ID. Receives the full Telegram Update object as output.

Node Type

Trigger — webhook (receives incoming HTTP callbacks)

Input / Output

Direction	Port(s)
Input	None (trigger node)
Output	Output

Credentials

This tool requires Telegram API credentials. See the Credentials Guide for setup instructions.

Parameters

Parameter	Type	Required	Default	Description
Bot Token	string	Yes	—	Telegram Bot API token from @BotFather.
Trigger On	multiOptions	Yes	[]	Which update types to listen for.
				Options: * (all updates), callback_query, channel_post, edited_channel_post, edited_message, inline_query, message, poll (only stopped polls and polls sent by the bot), pre_checkout_query, shipping_query
Additional Fields	collection	No	{}	Optional download and filtering settings.
— Download Images/Files	boolean	No	false	Telegram delivers the image in multiple sizes. By default, just the large image would be downloaded. If you want to change the size, set the field Image Size.
— Image Size	options	No	large	The size of the image to be downloaded (shown when Download Images/Files is true)
				Options: small, medium, large, extraLarge
— Restrict to Chat IDs	string	No	—	The chat IDs to restrict the trigger to. Multiple can be defined separated by comma.
— Restrict to User IDs	string	No	—	The user IDs to restrict the trigger to. Multiple can be defined separated by comma.

Output Data

Each accepted update produces one output item containing the complete Telegram Update object exactly as Telegram sent it — so message, callback_query, channel_post and the other update objects appear at the top level — plus:

• _trigger — always telegram_webhook
• _timestamp — ISO 8601 timestamp of when the update was received
• _webhookEvent — the detected update type, e.g. message, callback_query, or unknown when the update carries none of the recognised types

Updates that fall outside your Trigger On selection, or outside the chat/user ID restrictions, are acknowledged to Telegram but do not start the workflow.

Reference the payload downstream by expression, e.g. {{ $json.message.text }}.

Example Configuration

Basic message trigger:

{
  "type": "telegram_trigger",
  "parameters": {
    "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    "updates": ["message"]
  }
}

All updates, downloading attachments at medium size:

{
  "type": "telegram_trigger",
  "parameters": {
    "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    "updates": ["*"],
    "additionalFields": {
      "download": true,
      "imageSize": "medium"
    }
  }
}

Callback queries only — useful for inline keyboard handling:

{
  "type": "telegram_trigger",
  "parameters": {
    "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    "updates": ["callback_query"]
  }
}

Multiple update types restricted to specific chats and users:

{
  "type": "telegram_trigger",
  "parameters": {
    "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    "updates": ["message", "callback_query", "inline_query"],
    "additionalFields": {
      "download": false,
      "chatIds": "123456789",
      "userIds": "111111111,222222222"
    }
  }
}

Channel management — posts and their edits:

{
  "type": "telegram_trigger",
  "parameters": {
    "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    "updates": ["channel_post", "edited_channel_post"],
    "additionalFields": {
      "download": false,
      "chatIds": "987654321"
    }
  }
}

Trigger Behavior

• Activation: When the workflow is activated, a webhook endpoint is registered with the service.
• Deactivation: The webhook is automatically unregistered when the workflow is deactivated.
• Payload: The incoming webhook payload is parsed and output as workflow items.
• Verification: Supports signature verification where applicable.

Tips

This tool receives updates for a Telegram bot, such as messages, callbacks, and inline queries. It is ideal when a workflow needs to start based on specific interactions with a Telegram bot, rather than sending messages or managing chats. The tool produces the full Telegram Update object, containing all details of the received event.

Important Notes

1. Single Bot Limitation: Due to Telegram API restrictions, only one Telegram trigger can be active per bot at any time.

2. Attachment Handling: Each attachment in a media group triggers a separate event. Use the media_group_id field to identify attachments belonging to the same group.

3. Filtering: Use chatIds and userIds in additionalFields to limit which chats or users can trigger the workflow.

4. Download Behavior: When download is enabled, attachments are automatically downloaded. The imageSize parameter only applies when downloading is enabled.