Telegram Trigger

Receive Telegram bot messages and updates as workflow triggers.

When to Use

Use Telegram Trigger when:

You want to run a workflow when a user sends a message to your bot
You need to handle bot commands (e.g. /start) or inline button callbacks
Telegram is the event source and your workflow runs asynchronously

For sending messages back to users, pair this with Telegram Send Message.

Output

Handle	Type	Description
`payload`	object	Normalized Telegram update payload

The payload (accessed as {{ telegram.* }}) shape:

Field	Type	Description
`chat_id`	number	Chat ID where the update occurred
`from`	object	Sender object (`id`, `username`, `first_name`, etc.)
`text`	string	Message text content
`message_id`	number	Telegram message ID
`date`	number	Unix timestamp of the message
`reply_to_message`	object	Original message if this is a reply
`update_type`	string	Update type (e.g. `message`, `callback_query`)
`raw_update`	object	Full Telegram update object for advanced use cases

Settings

Events

Setting	Type	Default	Description
`update_types`	multi-select	`message`	Telegram update types to listen for: `message`, `edited_message`, `callback_query`, `inline_query`

Filters

Setting	Type	Default	Description
`command_filter`	string	—	Only trigger for this bot command (e.g. `/start`). Leave empty to accept all messages.

Testing

Setting	Type	Default	Description
`mockPayload`	code editor (JSON)	Sample Telegram update JSON	JSON body to inject when running this workflow locally for testing.

Required Secrets

Configure this on the Env Vars page:

Env Var	Description
`TELEGRAM_BOT_TOKEN`	Bot token from @BotFather (format: `123456:ABC-DEF...`)

Example

Canvas

Handle the /start command and send a welcome message:

Create a bot via @BotFather and copy the bot token
Add TELEGRAM_BOT_TOKEN as an env var
Deploy the workflow and register the webhook with the Telegram Bot API:

https://api.telegram.org/bot{token}/setWebhook?url=https://triggers.tensorify.io/{teamId}/{path}

Set update_types to message and command_filter to /start
Add a Telegram Send Message node — set Chat ID to {{ telegram.chat_id }} and Message Text to your welcome message

Access update data in downstream nodes:

{{ telegram.from.username }}
{{ telegram.text }}
{{ telegram.chat_id }}
{{ telegram.message_id }}
{{ telegram.update_type }}

TSL

import telegram from @tensorify/telegram-trigger:1.0.0
import telegram_send from @tensorify/telegram-send-message:1.0.0

node trigger @tensorify/telegram-trigger:1.0.0 {
    update_types = ["message"]
    command_filter = "/start"
}

node welcome @tensorify/telegram-send-message:1.0.0 {
    chat_id = "{{ telegram.chat_id }}"
    text = "Welcome to the bot, {{ telegram.from.first_name }}!"
}

trigger.payload -> welcome.input

Common Gotchas

One webhook per bot: Telegram allows only one webhook URL per bot. Deploying a new workflow overwrites the previous webhook registration.
HTTPS required: Telegram webhooks must use HTTPS. The triggers.tensorify.io endpoint satisfies this requirement.
Command filter format: Include the leading slash (e.g. /start, not start).
Chat ID types: Private chat IDs are positive numbers; group chat IDs are negative. Use {{ telegram.chat_id }} directly when replying.