diff --git a/README.md b/README.md index 5417e03..c6171c0 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,56 @@ -### Notification by Telegram +# Notification by Telegram Send Icinga 2 notification via Telegram ![Telegram Notification](img/Telegram.png) -Example Notification Object ---------------------------- + +## Prepare + +### Create your bot + +Obviously you need a bot to begin: + +Follow the [official Telegram guide](https://core.telegram.org/bots) and do not forget to grab your bot *API TOKEN* (referred to here as *BOTTOKEN*) afterwards + + +### Get your chat_id(s) + +You can notify a specific TG user account or throw a message to a TG group. + +In order to do so you need to know the corresponding (hidden) ID also called chat_id (-q TELEGRAM_CHATID). + +If you want to notify a **group/channel**: + +1. add your bot to that group/channel +1. send with your favorite client a simple mention msg to your bot (e.g. `hi @mybot`) +1. catch updates for your bot: +`curl https://api.telegram.org/bot/getUpdates` +1. review the output, an example below: + > "message":{"message_id":91, "from":{"id":123456789, "is_bot":false,"first_name":"foo","username":"foobar","language_code":"de"}, "chat":{"id":-987654321, "title":"","type":"group","all_members_are_administrators":true},"date":1563547428,"group_chat_created":true}}]}` + + There are 2 important parts here: + - a) `"from":{"id":123456789` which is the unique user/chat_id of the user who sends a message to your bot (required to send to a notify to that person directly) + - b) `"chat":{"id":-987654321` which is the unique group/channel id of the group where the message has been sent + +If you do not want to notify a group i.e. just **a direct user notification**: + +1. do the same as above, just at step 1 make a direct message to your bot instead +1. as you have done a direct message you will only get a "from" id which is all you need here + + +# Examples + +### Testing a notification + +sending a test notification (replace the token, botname and chat id obviously) + +`sudo -u nagios ./service-by-telegram.sh -4 127.0.0.1 -l myhostname -o testingTGnotifiy -p -q -r "<1234134325:blafasel>" -s CRITICAL -c mycomment -b mycommentuser -i https://myicingaserver/icingaweb2 -n maaaaaaaaaaa -d"$(date +%F-%T)" -e serviceshort -u fullservicename -D` + + +### Icinga2 objects + + +#### Example Notification Object ```ini apply Notification "Host by Telegram" to Host { @@ -19,8 +65,8 @@ apply Notification "Host by Telegram" to Host { } ``` -Command Definitions -------------------- +#### Example Command Definitions + ```ini object NotificationCommand "Notify Host By Telegram" { import "plugin-notification-command" @@ -130,5 +176,6 @@ object NotificationCommand "Notify Service By Telegram" { } } ``` +#### Example Director config ![Icinga Director Config](img/Telegram_Notification_in_Icinga_Director.jpg)