Telegram event handler

Telegram is a messaging app built with a focus on security and speed. Kapacitor can be configured to send alert messages to a Telegram bot.


Configuration as well as default option values for the Telegram alert handler are set in your kapacitor.conf. Below is an example configuration:

  enabled = false
  url = ""
  token = ""
  chat-id = ""
  parse-mode  = "Markdown"
  disable-web-page-preview = false
  disable-notification = false
  global = false
  state-changes-only = false


Set to true to enable the Telegram event handler.


The Telegram Bot URL. _This should not need to be changed.


Telegram bot token. Contact @BotFather to obtain a bot token.


Default recipient for messages. Contact @myidbot on Telegram to get an ID.


Specifies the syntax used to format messages. Options are Markdown or HTML which allow Telegram apps to show bold, italic, fixed-width text or inline URLs in alert message.


Disable link previews for links in this message.


Sends the message silently. iOS users will not receive a notification. Android users will receive a notification with no sound.


If true, all alerts will be sent to Telegram without explicitly specifying Telegram in the TICKscript.


If true, alerts will only be sent to Telegram if the alert state changes. This only applies if the global is also set to true.


The following Telegram event handler options can be set in a handler file or when using .telegram() in a TICKscript.

chat-idstringTelegram user/group ID to post messages to. If empty uses the chati-d from the configuration.
parse-modestringParse node, defaults to Markdown. If empty uses the parse-mode from the configuration.
disable-web-page-previewboolWeb Page preview. If empty uses the disable-web-page-preview from the configuration.
disable-notificationboolDisables Notification. If empty uses the disable-notification from the configuration.

Example: handler file

topic: topic-name
id: handler-id
kind: telegram
  chat-id: '123456789'
  parse-mode: 'Markdown'
  disable-web-page-preview: false
  disable-notification: false

Example: TICKscript

  // ...  

Telegram Setup


To configure Kapacitor with Telegram, the following is needed:

  • a Telegram bot
  • a Telegram API access token
  • a Telegram chat ID

Create a Telegram bot

  1. Search for the @BotFather username in your Telegram application

  2. Click Start to begin a conversation with @BotFather

  3. Send /newbot to @BotFather. @BotFather will respond:

    Alright, a new bot. How are we going to call it? Please choose a name for your bot.

    @BotFather will prompt you through the rest of the bot-creation process; feel free to follow his directions or continue with our version of the steps below. Both setups result in success!

  4. Send your bot’s name to @BotFather. Your bot’s name can be anything.

    Note that this is not your bot’s Telegram @username. You will create the username in step 5.

    @BotFather will respond:

    Good. Now let’s choose a username for your bot. It must end in bot. Like this, for example: TetrisBot or tetris_bot.

  5. Send your bot’s username to @BotFather. BotFather will respond:

    Done! Congratulations on your new bot. You will find it at You can now add a description, about section and profile picture for your bot, see /help for a list of commands. By the way, when you’ve finished creating your cool bot, ping our Bot Support if you want a better username for it. Just make sure the bot is fully operational before you do this.

    Use this token to access the HTTP API:

    For a description of the Bot API, see this page:

  6. Begin a conversation with your bot. Click on the<bot-username> link in @BotFather’s response and click Start at the bottom of your Telegram application. Your newly-created bot will appear in the chat list on the left side of the application.

Get a Telegram API access token

Telegram’s @BotFather bot sent you an API access token when you created your bot. See the @BotFather response in step 5 of the previous section for where to find your token. If you can’t find the API access token, create a new token with the following steps below.

  1. Send /token to @BotFather

  2. Select the relevant bot at the bottom of your Telegram application. @BotFather responds with a new API access token:

    You can use this token to access HTTP API:

    For a description of the Bot API, see this page:

Get your Telegram chat ID

  1. Paste the following link in your browser. Replace <API-access-token> with the API access token that you identified or created in the previous section:<API-access-token>/getUpdates?offset=0
  2. Send a message to your bot in the Telegram application. The message text can be anything. Your chat history must include at least one message to get your chat ID.

  3. Refresh your browser.

  4. Identify the numerical chat ID by finding the id inside the chat JSON object. In the example below, the chat ID is 123456789.


Using the Telegram event handler

With the Telegram event handler enabled and configured in your kapacitor.conf, use the .telegram() attribute in your TICKscripts to send alerts to your Telegram bot or define a Telegram handler that subscribes to a topic and sends published alerts to your Telegram bot.

To avoid posting a message every alert interval, use AlertNode.StateChangesOnly so only events where the alert changed state are sent to Telegram.

The examples below use the following Telegram configuration defined in the kapacitor.conf:

Telegram settings in kapacitor.conf

  enabled = true
  url = ""
  token = "mysupersecretauthtoken"
  chat-id = ""
  parse-mode  = "Markdown"
  disable-web-page-preview = false
  disable-notification = false
  global = false
  state-changes-only = false

Send alerts to a Telegram bot from a TICKscript

The following TICKscript uses the .telegram() event handler to send the message, “Hey, check your CPU” to a Telegram bot whenever idle CPU usage drops below 10%. It uses the default Telegram settings defined in the kapacitor.conf.


    .crit(lambda: "usage_idle" < 10)
    .message('Hey, check your CPU')

Send alerts to the Telegram bot from a defined handler

The following setup sends the message, “Hey, check your CPU” to a Telgram bot with the 123456789 chat-ID.

Create a TICKscript that publishes alert messages to a topic. The TICKscript below sends an alert message to the cpu topic any time CPU idle usage drops below 10% (or CPU usage is above 90%).


    .crit(lambda: "usage_idle" < 10)
    .message('Hey, check your CPU')

Add and enable the TICKscript:

kapacitor define cpu_alert -tick cpu_alert.tick
kapacitor enable cpu_alert

Create a handler file that subscribes to the cpu topic and uses the Telegram event handler to send alerts to the 123456789 chat-ID in Telegram.


id: telegram-cpu-alert
topic: cpu
kind: telegram
  chat-id: '123456789'

Add the handler:

kapacitor define-topic-handler telegram_cpu_handler.yaml

Was this page helpful?

Thank you for your feedback!

Introducing InfluxDB Clustered

A highly available InfluxDB 3.0 cluster on your own infrastructure.

InfluxDB Clustered is a highly available InfluxDB 3.0 cluster built for high write and query workloads on your own infrastructure.

InfluxDB Clustered is currently in limited availability and is only available to a limited group of InfluxData customers. If interested in being part of the limited access group, please contact the InfluxData Sales team.

Learn more
Contact InfluxData Sales

The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Flux is going into maintenance mode and will not be supported in InfluxDB 3.0. This was a decision based on the broad demand for SQL and the continued growth and adoption of InfluxQL. We are continuing to support Flux for users in 1.x and 2.x so you can continue using it with no changes to your code. If you are interested in transitioning to InfluxDB 3.0 and want to future-proof your code, we suggest using InfluxQL.

For information about the future of Flux, see the following:

State of the InfluxDB Cloud Serverless documentation

InfluxDB Cloud Serverless documentation is a work in progress.

The new documentation for InfluxDB Cloud Serverless is a work in progress. We are adding new information and content almost daily. Thank you for your patience!

If there is specific information you’re looking for, please submit a documentation issue.