Send a Telegram notification when a workflow fails

Catch every Kestra workflow failure with an instant Telegram alert. This system flow listens for FAILED and WARNING executions across the company namespace and all of its nested child namespaces, then pushes a message to a Telegram channel so on-call engineers can react before stakeholders notice. It is the simplest way to centralize pipeline incident alerting without instrumenting each individual flow with notification tasks.

How it works

1. A io.kestra.plugin.core.trigger.Flow trigger named on_failure listens to every execution in the instance.
2. Two conditions filter the stream: io.kestra.plugin.core.condition.ExecutionStatus keeps only FAILED and WARNING outcomes, and io.kestra.plugin.core.condition.ExecutionNamespace with comparison: PREFIX restricts to the company namespace and its children.
3. When a matching execution is detected, the send_notification task of type io.kestra.plugin.telegram.TelegramExecution posts a message to the configured channel, including the failed executionId and the taskrun.startDate.
4. The bot token is injected from a Kestra secret, never hardcoded.

What you get

• Real-time Telegram alerts for every failure or warning across an entire namespace tree.
• One central place to maintain alerting logic instead of per-flow notification tasks.
• Rich payload with execution ID and timestamp, ready to extend with links, owners, or labels.
• Reusable pattern that works for any team or environment by changing the namespace prefix.

Who it's for

• Platform and data engineering teams running production pipelines on Kestra.
• SRE and on-call rotations that already use Telegram for incident channels.
• Small teams that want chat-first alerting without configuring a full incident tool.

Why orchestrate this with Kestra

Telegram has no native concept of pipeline executions, namespaces, or retries. Kestra provides the event source: a Flow trigger evaluates every execution in the instance, applies declarative conditions, and fires the notifier without polling. You get retries on transient Telegram API errors, full lineage on which execution caused the alert, declarative YAML stored in Git, and a single system flow that scales to thousands of monitored workflows. No cron, no glue scripts, no per-flow boilerplate.

Prerequisites

• A Telegram bot created via BotFather with a token.
• The numeric channel or chat ID the bot can post to (the bot must be a member, admin if the channel is private).
• Workflows running under a namespace that starts with company (adjust the prefix to match your tenancy).

Secrets

• TELEGRAM_TOKEN: the Telegram Bot API token used by the TelegramExecution task.

Quick start

1. Create a Telegram bot with BotFather and copy its token.
2. Add the bot to the target channel or chat and grab the numeric channel ID.
3. Store the token as a Kestra secret named TELEGRAM_TOKEN.
4. Update channel in the send_notification task to your own ID.
5. Adjust the ExecutionNamespace prefix if your workflows live under a different root.
6. Deploy the flow and trigger a failing test execution to confirm the alert lands.

How to extend

• Add a second ExecutionStatus condition to alert on KILLED or long-running RUNNING executions.
• Enrich the payload with a link to the execution UI, the flow ID, and the owning team label.
• Fan out to multiple channels by adding more TelegramExecution tasks, one per severity.
• Chain a io.kestra.plugin.core.flow.Switch to route critical namespaces to PagerDuty and informational ones to Telegram only.
• Pair with Slack, email, or Microsoft Teams notifiers in the same system flow for multichannel alerting.

Links

• Plugin docs: https://kestra.io/plugins/plugin-telegram