<!-- BusyBot node reference — https://busybot.net/tools/telegram-trigger/ -->

> Node: Telegram Trigger (`telegram_trigger`) · Webhook trigger · v1
> Category: Communication · Credentials: Telegram API (`telegramApi`)
> Updated: 2026-08-16

# Telegram Trigger

> Trigger on Telegram bot updates like messages, callbacks, and inline queries.

## 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.

**Category:** Communication  
**Tool Name:** `telegram_trigger`  
**Version:** 1

**Appearance:** Icon: `si-telegram` | Color: `#0088cc`

## 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](https://busybot.net/credentials/telegram-api/) 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 }}`.

## Usage Examples

- Start a workflow when a user sends a message to my Telegram bot
- Trigger on inline keyboard button presses in Telegram
- Listen for new channel posts in Telegram
- React to edited messages in a Telegram chat
- Handle pre-checkout queries for Telegram payments

## Example Configuration

Basic message trigger:

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

All updates, downloading attachments at medium size:

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

Callback queries only — useful for inline keyboard handling:

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

Multiple update types restricted to specific chats and users:

```json
{
  "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:

```json
{
  "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

Receives Telegram bot updates via webhook. Configure which update types to listen for (messages, callbacks, inline queries, polls, etc.). Optionally filter by chat ID or user ID. The full Telegram Update object is passed to the workflow.

### 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.