Notification by Telegram

Send Icinga 2 notifications via Telegram.

Preparing

Create your Bot

You need a bot to begin:

Follow the official Telegram guide and do not forget to grab your bot API TOKEN (referred to here as BOT_TOKEN) 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
2. Send with your favorite client a simple mention msg to your bot (e.g. hi @mybot)
3. Catch updates for your bot: curl https://api.telegram.org/bot/getUpdates

4. 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
2. 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 ./alert-by-telegram.sh -4 127.0.0.1 \
-a service \
-d"$(date +%F-%T)" \
-e serviceshort \
-l myhostalias \
-o testing-telegram-notifiy \
-p $BOT_NAME> \
-q $GROUP_CHAT_ID \
-r $BOT_TOKEN \
-c mycomment \
-b mycommentauthor \
-i https://myicingaserver/icingaweb2 \
-n myhostdisplayname \
-s CRITICAL \
-t PROBLEM \
-u fullservicename

Icinga2 objects

Example host objects

Example host template

template Host "Generic Host Template" {
  check_command = "hostalive"
  max_check_attempts = "3"
  check_interval = 1m
  retry_interval = 1m
  check_timeout = 30s
  enable_notifications = true
  enable_active_checks = true
  enable_passive_checks = true
  enable_event_handler = true
  enable_flapping = true
  enable_perfdata = true
  volatile = false
  vars.notification_type = "Telegram"
}

Example host object

object Host "icinga2-master" {
    import "Generic Host Template"
    address = "127.0.0.1"
}

Example user templates

Generic user template

template User "Generic User Template" {
    enable_notifications = true
}

User "telegram_bot"

object User "telegram_bot" {
    import "Generic User Template"

    display_name = "Bot via Telegram"
    email = "you@yourdomain.tld"
    states = [ Critical, Down, OK, Unknown, Up, Warning ]
    types = [ Custom, Problem, Recovery ]
}

Example command definitions

Notification Command: Hosts by Telegram

object NotificationCommand "Notify Host By Telegram" {
    import "plugin-notification-command"
    command = [ "/etc/icinga2/scripts/alert-by-telegram.sh" ]
    arguments += {
        "-4" = {
            required = true
            value = "$address$"
        }
        "-6" = "$address6$"
        "-a" = "host"
        "-b" = "$notification.author$"
        "-c" = "$notification.comment$"
        "-d" = {
            required = true
            value = "$icinga.long_date_time$"
        }
        "-i" = "$icingaweb2url$"
        "-l" = {
            required = true
            value = "$host.name$"
        }
        "-n" = "$host.display_name$"
        "-o" = {
            required = true
            value = "$host.output$"
        }
        "-p" = {
            required = true
            value = "$telegram_bot$"
        }
        "-q" = {
            required = true
            value = "$telegram_chatid$"
        }
        "-r" = {
            required = true
            value = "$telegram_bottoken$"
        }
        "-s" = {
            required = true
            value = "$host.state$"
        }
        "-t" = {
            required = true
            value = "$notification.type$"
        }
        "-v" = "$telegram_notification_logtosyslog$"
    }
}

Notification Command: Services by Telegram

object NotificationCommand "Notify Service By Telegram" {
    import "plugin-notification-command"
    command = [ "/etc/icinga2/scripts/alert-by-telegram.sh" ]
    arguments += {
        "-4" = {
            required = true
            value = "$address$"
        }
        "-6" = "$address6$"
        "-a" = "service"
        "-b" = "$notification.author$"
        "-c" = "$notification.comment$"
        "-d" = {
            required = true
            value = "$icinga.long_date_time$"
        }
        "-e" = {
            required = true
            value = "$service.name$"
        }
        "-i" = "$icingaweb2url$"
        "-l" = {
            required = true
            value = "$host.name$"
        }
        "-n" = "$host.display_name$"
        "-o" = {
            required = true
            value = "$service.output$"
        }
        "-p" = {
            required = true
            value = "$telegram_bot$"
        }
        "-q" = {
            required = true
            value = "$telegram_chatid$"
        }
        "-r" = {
            required = true
            value = "$telegram_bottoken$"
        }
        "-s" = {
            required = true
            value = "$service.state$"
        }
        "-t" = {
            required = true
            value = "$notification.type$"
        }
        "-u" = {
            required = true
            value = "$service.display_name$"
        }
        "-v" = "$telegram_notification_logtosyslog$"
    }
}

Example notification objects

Notification Template: Telegram Generic

template Notification "Template: Telegram (Generic)" {
    vars.telegram_bot = ""
    vars.telegram_bottoken = ""
    vars.telegram_chatid = ""
    vars.telegram_notification_logtosyslog = true
}

Notification Template: Host Notifications

template Notification "Template: Host Notifications via Telegram" {
    import "Template: Telegram (Generic)"

    command = "Notify Host By Telegram"
    interval = 1h
}

Notification Template: Service Notifications

template Notification "Template: Service Notifications via Telegram" {
    import "Template: Telegram (Generic)"

    command = "Notify Service By Telegram"
    interval = 4h
}

Example notification apply rules

Apply rule for host notifications

   apply Notification "Host Alert via @telegram_bot" to Host {
    import "Template: Host Notifications via Telegram"

    interval = 1h
    assign where host.vars.notification_type == "Telegram"
    states = [ Down, Up ]
    types = [ Custom, Problem, Recovery ]
    users = [ "telegram_bot" ]
}

Apply rule for service notifications

apply Notification "Service Alerts via @telegram_bot" to Service {
  import "Template: Service Notifications via Telegram"

  interval = 12h
  assign where host.vars.notification_type == "Telegram"
  users = [ "telegram_bot" ]
}

Example Director screenshot

Notifications by Telegram via Icinga Director

Related Director Baskets

• Just the Commands
• Commands and Notification Templates with fields (requires Director v1.8.0 or a master newer than 80f9ea2)

License

Copyright (C) 2018 Marianne M. Spiller

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see .