Telegram Notifications

Overview

TELEGRAM webhook provides a built-in capability to send alert messages, alert detail tables, and charts to Telegram groups and channels. The integration is based on the Telegram Bot API.

Reference

Prerequisites

Install and configure the Web Driver to send chart screenshots into Telegram.

Create Bot

  • Search for the BotFather user in the Telegram client.

  • Start a conversation with the BotFather user.

  • Send the /newbot command and complete the guided process to create a bot user and obtain its token. The bot username must end with _bot and cannot contain dash - symbol.

Use this token to access the HTTP API:
5555555555:AAHrB1gmYKaSvzsXjhbyDypOJlfu_FgdwrE
  • Copy the API token for future reference.

Add Bot to Group or Channel

If necessary, create a new group or channel.

Add Bot to Group

  • Click Group Settings > Add Members.

  • Specify the name of the newly created bot, for example, @atsd_bot.

  • Click the bot name and click Invite.

To add bot to private/public channel see this instruction.

Get Chat Id

The chat id is required for the outgoing Telegram webhook to function properly.

There are two options to obtain chat id:

View Updates

  • Send any message to the channel (for private/public channel) or start conversation with the bot (for direct message chat). No action is required for the group.

  • Open https://api.telegram.org/botBOT_TOKEN/getUpdates link (replace BOT_TOKEN with the actual value).

  • Review the Chat Object and copy id value.

Configure Webhook in ATSD

  • Open Alerts > Outgoing Webhooks page.

  • Click an existing TELEGRAM template, or click Create and select the TELEGRAM type.

  • Specify the unique Name of the notification.

  • Enter the BOT_TOKEN value into the Bot API Token field.

  • Enter the chat id into the Chat ID field.

  • Select Test Portal to verify screenshot delivery.

  • Click Test.

  • If the test is passed, check Enable, click Save.

Proxy Settings

If the Telegram API server is not accessible from the ATSD server, open the Network Settings and specify proxy parameters.

NGINX API Gateway Path for Telegram:

location /bot {
    proxy_pass https://api.telegram.org/bot;
}

Webhook Settings

Setting Description
Bot API Token Unique authentication token assigned to the bot.
Chat ID Unique identifier for the target chat or the target channel.
Text Message text to be sent. Leave the field blank to make the field editable in the rule editor.
Notifications If enabled, delivers the message with an audio notification.
Web Page Preview If enabled, displays short previews for URLs in the message.
Details Table Format The default format for the alerts detail table.

Note parse mode is set to markdown by default.

Reacting to Bot Messages

The bot account can be used both to deliver notifications to end users, as well as to react to messages addressed to the bot itself.

To process incoming messages, configure an outgoing webhook or set Receive Updates setting to yes and Method to Polling. The webhook integration requires ATSD server to be reachable from Telegram API servers.

Testing Rule

Create/import rule

  • Create a new rule or import an existing rule for a built-in metric as described below.
  • Download the file rules.xml.
  • Open the Alerts > Rules > Import page.
  • Check (enable) Auto-enable New Rules, attach the rules.xml file, click Import.

Configure Webhook

  • Open Alerts > Rules page and select a rule.
  • Open the Webhooks tab.
  • Select Telegram from the Endpoint drop-down.
  • Enable the OPEN, REPEAT, and CANCEL triggers.
  • Customize the alert message using placeholders as necessary, for example:
*[${status}]* ${ruleLink} for ${entity} ${tags}
  • Click Save to save the rule.

  • The rule creates new windows when new commands are received by the database.

It can take a few seconds for the first commands to arrive and to trigger the webhook. You can open and refresh the Alerts > Open Alerts page to verify that an alert is open for your rule.

Test

  • Check channel messages.

Sample alert table file.

Examples