Event

trigger.telegram_event

TriggerChat & messagingconnection requiredruns in-engine

Calls setWebhook on the tenant's bot at publish and starts one run per update, verified against the secret token Telegram echoes back. Replaces the bot's existing webhook, because a bot only has one.

Start a run when a Telegram bot receives an update — a message, a button press, a member joining. A bot can drive only one destination, so this takes over the bot's single webhook.

Ask about Telegram All Telegram nodes Provider API docs ↗

Connection

Required: Yes — the node will not save without one
Auth type: API key
Providers: Telegram
Secret shape: the bot token, or {"token": "…"}
Resolved by: config.connection_id, else node.connection_id
Note: One bot per listening workflow: Telegram allows a bot exactly one webhook, so two workflows on one bot fight over it. Publishing needs MANTLE_APP_PUBLIC_BASE_URL set to an https URL on port 443, 80, 88 or 8443 — Telegram refuses any other port.

Configuration

4 fields, none required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.

Field	Type	Required	Default	Constraints	Example
allowed_updates Which kinds of update to receive. Only these are delivered — Telegram drops the rest rather than queueing them — so adding a kind later means publishing again. Every delivered update starts a run, so branch on `update_type` downstream.	array	No	["message"]	1–23 characters; array of string	—
replace_existing_webhook Take the bot over when it already delivers somewhere else. A Telegram bot has exactly one webhook, so publishing with this on stops whatever is currently receiving its updates — another workflow, or a separate integration. Left off, a publish onto a bot in use is refused instead.	boolean	No	false	—	—
drop_pending_updates Discard the updates Telegram has queued for this bot before the webhook is set. Off by default, so a backlog is delivered — which on a busy bot means a run per queued message the moment you publish.	boolean	No	false	—	—
max_connections How many simultaneous connections Telegram may use to deliver updates. Lower it to spare a small deployment; raise it for a high-traffic bot.	number	No	40	1–100	—

Example configuration

Every value below is the contract’s own example or default — nothing invented.

{
  "allowed_updates": [
    "message"
  ],
  "drop_pending_updates": false,
  "max_connections": 40,
  "replace_existing_webhook": false
}

Output

One shape.

telegram update

The flattened Update. `payload` is Telegram's own Update object, whose keys depend on update_type, so the shape is open below the declared fields.

Extra keys beyond the ones listed can appear.

Field	Type	Example
update_id Telegram's own update id — unique for this bot and increasing. It is the idempotency key: Telegram repeats an update until the endpoint answers, and every attempt reuses this number, so a retry joins the run it already started.	number	874927341
update_type Which kind of update this is — message, callback_query, my_chat_member… An Update carries exactly one, so this is what to branch on when the trigger subscribes to more than one kind.	string	message
chat_id The chat the update belongs to, as a string so a large negative supergroup id survives. Feed it straight back to telegram.send_message to reply. Empty on updates with no chat (an inline query, a poll answer).	string	-1001234567890
chat_type private, group, supergroup or channel. Worth checking before replying: a bot may only message a private chat the user started.	string	supergroup
chat_title The group or channel name. Empty for a private chat, which has no title.	string	Acme Support
message_id The message this update is about, as a string. Pass it as reply_to_message_id to answer in thread. Empty on updates that carry no message.	string	4821
text The message text, or a media message's caption, or a callback query's data, or an inline query's search text — whichever this update kind carries. Empty when it carries none of them.	string	Deploy the release please
from_id The Telegram user who caused the update, as a string. Empty on updates Telegram raises on its own (a poll closing, a channel post).	string	99887766
from_username That user's @username without the @. Often empty — a Telegram account is not required to have one.	string	ada
date When the message was sent, epoch seconds, from Telegram's own field. Null on update kinds that carry no date.	number	1789042462
payload The whole Update object exactly as Telegram sent it — entities, photo sizes, reply markup, poll options and everything else the fields above do not lift out.	object	—

{
  "chat_id": "-1001234567890",
  "chat_title": "Acme Support",
  "chat_type": "supergroup",
  "date": 1789042462,
  "from_id": "99887766",
  "from_username": "ada",
  "message_id": "4821",
  "payload": {
    "message": {
      "chat": {
        "id": -1001234567890,
        "title": "Acme Support",
        "type": "supergroup"
      },
      "date": 1789042462,
      "from": {
        "id": 99887766,
        "is_bot": false,
        "username": "ada"
      },
      "message_id": 4821,
      "text": "Deploy the release please"
    },
    "update_id": 874927341
  },
  "text": "Deploy the release please",
  "update_id": 874927341,
  "update_type": "message"
}

Notes

A Telegram bot has exactly one webhook. Publishing sets it; unpublishing, disabling or archiving clears it — but only while the bot is still pointed at this workflow, so a bot somebody else has taken over is left alone.
Setting a webhook stops getUpdates working for that bot until it is cleared; the two cannot be used at the same time.
Deliveries are authenticated by the secret token Telegram echoes in the X-Telegram-Bot-Api-Secret-Token header. Telegram does not sign the body, so this proves who sent the request and not that the bytes are untouched — which is the whole of what the Bot API offers.
One run per update, idempotent on update_id: Telegram repeats an update until the endpoint answers, and a repeat cannot start a second run.
A bot only sees group messages it is allowed to: turn privacy mode off in BotFather, or make it an admin, or it receives commands only.

Related Telegram nodes

See Event run in a workflow.

In a technical demo we add the Telegram connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.

Book a technical demo Talk to sales