TL;DR InfluxDB Tech Tips - Telegram Setup with Kapacitor & Chronograf

By Regan Kuchan / Product, Developer
Mar 02, 2017

Navigate to:

In this post we describe how to set up Kapacitor and Chronograf to send alert messages to Telegram. Check in next week for the most interesting InfluxDB and TICK-stack related issues, workarounds, how-tos and Q&A from GitHub, IRC and the InfluxDB Google Group that you might have missed.

Telegram Setup with Kapacitor

Telegram is a messaging application. Kapacitor is InfluxData’s open source data processing framework that allows you to configure and send alert messages to event handlers (like Telegram!).

Requirements

To send Kapacitor alert messages to a Telegram bot, you need a Telegram bot, an API access token, and your Telegram chat id.

Telegram bot

The following steps describe how to create a new 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 responds:

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’ll create the username in step 5.

@BotFather responds:

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

Your bot’s username must end in bot. For example: mushroomKap_bot.

BotFather responds:

Done! Congratulations on your new bot. You will find it at t.me/<bot-username>.
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:
<API-access-token>

For a description of the Bot API, see this page: https://core.telegram.org/bots/api

6. Begin a conversation with your bot

Click on the t.me/<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.

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 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:
<API-access-token>

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
Telegram chat id

The following steps describe how to identify your 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:

https://api.telegram.org/bot<API-access-token>/getUpdates?offset=0

2. Send a message to your bot

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 chat id

Identify the numerical chat id in the browser. In the example below, the chat id is 123456789.

{"ok":true,"result":[{"update_id":XXXXXXXXX,
"message":{"message_id":2,"from":{"id":123456789,"first_name":"Mushroom","last_name":"Kap"},
"chat":{"id":123456789,"first_name":"Mushroom","last_name":"Kap","type":"private"},
"date":1487183963,"text":"hi"}}]}

Telegram Configuration

In the [telegram] section of Kapacitor’s configuration file (/etc/kapacitor/kapacitor.conf), set the enabled setting to true and set token to your API access token. There are other configuration settings, but they are optional.

Sample configuration file:

[telegram]
  enabled = true
  url = "https://api.telegram.org/bot" # url requires no additional configuration.
  token = "abcdefghi:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  chat-id = "123456789"

Kapacitor TICKscript

In the |alert() section of your Kapacitor TICKscript, include the .telegram() attribute and set the .chatId('<your-chat-id>') attribute to your Telegram chat-id.

Sample TICKscript:

stream
    |from()
        .measurement('cpu')
    |alert()
        .crit(lambda: "usage_idle" <  10)
        .message('')
        .telegram() ?
          .chatId('<your-chat-id>') ?

Next, define and enable your Kapacitor task, and keep an eye on your Telegram bot. That’s it!

Telegram Setup with Chronograf

Chronograf offers a user interface for working with Kapacitor to easily create alert rules and send alert messages to event handlers.

Requirements

Kapacitor instance

Check out Chronograf’s installation guide to how to install and connect Kapacitor to Chronograf.

Telegram information
  • Telegram bot
  • Telegram API access token
  • Telegram chat id

See the list of requirements in the Telegram Setup with Kapacitor section for how to get that information from Telegram.

Chronograf/Kapacitor Configuration

1. Visit the Kapacitor Configuration page in your Chronograf application.

2. In the Configure Alert Endpoints section, select Telegram from the dropdown menu.

3. Enter your Telegram API access token in the Token input.

4. Enter your chat id in the Chat ID input.

5. Click the Save button.

Note that the Telegram URL input requires no additional configuration. The Parse Mode, Disable Web Page Preview, and Disable Notification checkboxes are optional; see the Kapacitor documentation for more information about those settings.

Rule Configuration

When creating or editing a rule on Chronograf’s Kapacitor Rules page, select telegram in the dropdown menu at the bottom of your screen. Kapacitor sends all alert messages associated with that rule to your configured Telegram bot.

What's next:

  • Downloads for the TICK-stack are live on our "downloads" page.
  • Deploy on the Cloud: Get started with a FREE trial of InfluxDB Cloud featuring fully-managed clusters, Kapacitor and Grafana.
  • Deploy on Your Servers: Want to run InfluxDB clusters on your servers? Try a FREE 14-day trial of InfluxDB Enterprise featuring an intuitive UI for deploying, monitoring and rebalancing clusters, plus managing backups and restores. 
  • Tell Your Story: Over 300 companies have shared their story on how InfluxDB is helping them succeed. Submit your testimonial and get a limited edition hoodie as a thank you.