alerta-contrib/plugins/telegram

Telegram Plugin

Send alerts to Telegram Bot.

For help, join

Installation

Clone the GitHub repo and run:

$ python setup.py install

Or, to install remotely from GitHub run:

$ pip install git+https://github.com/alerta/alerta-contrib.git#subdirectory=plugins/telegram

Note: If Alerta is installed in a python virtual environment then plugins need to be installed into the same environment for Alerta to dynamically discover them.

Configuration

Add telegram to the list of enabled PLUGINS in alertad.conf server configuration file and set plugin-specific variables either in the server configuration file or as environment variables.

PLUGINS = ['telegram']
TELEGRAM_TOKEN = ''  # Required, default="not set"
TELEGRAM_CHAT_ID = ''  # Required, default="not set", specify multiple ID's separated by comma. Get yours in https://t.me/chatid_echo_bot
TELEGRAM_TEMPLATE = '' # default will use hardcoded one (can be a filename to template file)
TELEGRAM_PROXY = '' # default="not set", URL must start from http://, socks5 not supported
TELEGRAM_PROXY_USERNAME = '' # default="not set"
TELEGRAM_PROXY_PASSWORD = '' # default="not set"

Create a new Telegram Bot using a Telegram client.

See https://core.telegram.org/bots#creating-a-new-bot

To ack, close or blackout an alert from the Telegram client set the webhook URL to your Alerta API Telegram endpoint (must be HTTPS):

TELEGRAM_WEBHOOK_URL = 'https://alerta.example.com/api/webhooks/telegram?api-key=[APIKEY_FROM_ALERTA]' # You can get one in https://alerta.example.com/keys
BLACKOUT_DURATION = 86400   # default=3600 ie. 1 hour

To enable/disable sound on notifications(disable_notification) use TELEGRAM_SOUND_NOTIFICATION_SEVERITY:

# Only severities 'security', 'critical' and 'major' have disable_notification=False
# all other severities have disable_notification=True
TELEGRAM_SOUND_NOTIFICATION_SEVERITY = ['security', 'critical', 'major']

If TELEGRAM_SOUND_NOTIFICATION_SEVERITY is unset then all telegram notifications have disable_notification=False

To disable notifications on severity on your chose use TELEGRAM_DISABLE_NOTIFICATION_SEVERITY:

# Severity `warning` is disabled notification in telegram
# all other severeties have notifications
TELEGRAM_DISABLE_NOTIFICATION_SEVERITY = ['warning']

Templating

There can be defined template to send data to telegram it have to be defined in TELEGRAM_TEMPLATE. TELEGRAM_TEMPLATE can be a filename pointing to Jinja2 template file. Template have to be writen in Jinja2 Alert data will be passed to it as context. So you can modify tg message as you wish. Example can be found in Explorer

Troubleshooting

Restart Alerta API and confirm that the plugin has been loaded and enabled.

Set DEBUG=True in the alertad.conf configuration file and look for log entries similar to below:

--------------------------------------------------------------------------------
DEBUG in __init__ [/Users/nsatterl/.virtualenvs/telegram/lib/python2.7/site-packages/alerta/plugins/__init__.py:46]:
Server plug-in 'telegram' found.
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
DEBUG in alerta_telegram [build/bdist.macosx-10.12-x86_64/egg/alerta_telegram.py:21]:
Telegram: {u'username': u'alertaio_bot', u'first_name': u'alerta-bot', u'id': 264434259}
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
INFO in __init__ [/Users/nsatterl/.virtualenvs/telegram/lib/python2.7/site-packages/alerta/plugins/__init__.py:53]:
Server plug-in 'telegram' enabled.
--------------------------------------------------------------------------------

References

• Telegram Bots Intro: https://core.telegram.org/bots
• Telepot Python Client: http://telepot.readthedocs.io/en/latest/
• Jinja2: http://jinja.pocoo.org/docs/2.10/

License

Copyright (c) 2016 Nick Satterly. Available under the MIT License.