alerta_alerta-contrib/plugins/telegram/README.md

Telegram Plugin
===============

Send alerts to Telegram Bot.

![Telegram Message](./images/alerta-telegram-plugin.png)

For help, join [![Slack chat](https://img.shields.io/badge/chat-on%20slack-blue?logo=slack)](https://slack.alerta.dev)

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.

```python
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):

```python
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](https://core.telegram.org/bots/api#sendmessage)) use `TELEGRAM_SOUND_NOTIFICATION_SEVERITY`:
```python
# 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](https://core.telegram.org/bots/api#sendmessage)=False

To disable notifications on severity on your chose use `TELEGRAM_DISABLE_NOTIFICATION_SEVERITY`:
```python
# 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](http://jinja.pocoo.org/docs/2.10/) template file.
Template have to be writen in [Jinja2](http://jinja.pocoo.org/docs/2.10/)
Alert data will be passed to it as context. So you can modify tg message as you wish. Example can be found in [Explorer](http://explorer.alerta.io/#/send)

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.