Telegram webhook trigger

Run a workflow on Telegram Bot API updates — your bot gets a message, a user taps an inline button, someone reacts to a message. The update becomes the workflow's input.

For behavior shared by every provider (the delivery URL, testing), see the webhook triggers reference.

Prerequisites

Telegram webhooks are auto-registered: Cotera calls the Telegram Bot API to set your bot's webhook. That requires a connected Telegram bot token. Without one, install fails with telegram_credentials_missing.

Setup

A Telegram bot allows only one webhook URL, so Cotera uses a single endpoint for your bot and routes updates to the triggers that match:

Add a From an app trigger and pick Telegram.
Choose the event (see below).
Save. Cotera calls Telegram's setWebhook for your bot, pointed at the shared endpoint, subscribing to the update types your active triggers need.

Deleting your last Telegram trigger removes the bot's webhook (deleteWebhook); Cotera reconciles the subscribed update types as you add or remove triggers.

Events

Event key	Fires when
`message`	The bot receives a new message
`callback_query`	A user taps an inline keyboard button
`message_reaction`	A user adds or removes an emoji reaction on a message
`message_reaction_count`	Anonymous reaction counts change on a channel message

Payload

The raw Telegram Update object is passed through as the workflow input. A message update looks like:

{
  "update_id": 10000,
  "message": {
    "message_id": 1,
    "from": {
      "id": 123456789,
      "is_bot": false,
      "first_name": "Test",
      "last_name": "User",
      "username": "testuser",
      "language_code": "en"
    },
    "chat": { "id": 123456789, "first_name": "Test", "username": "testuser", "type": "private" },
    "date": 1716111111,
    "text": "Hello from Cotera"
  }
}

Field	Description
`update_id`	The update's unique id, used to deduplicate retries.
`message` / `callback_query` / `message_reaction` / `message_reaction_count`	The update body — exactly one is present, and it determines the event.

Cotera routes each update to the trigger for its type: an update with callback_query runs the callback_query trigger, one with message runs the message trigger, and so on.

Authentication

Telegram doesn't sign deliveries. When Cotera registers the webhook it sets a secret token, and Telegram sends that token back in the X-Telegram-Bot-Api-Secret-Token header on every delivery. Cotera constant-time compares it against the trigger's secret and rejects anything that doesn't match.