checkmk-telegram-notifications/README.md

cmk_telegram - Checkmk Telegram Notifications

Telegram notification plugin for the Checkmk monitoring platform.

This is a Telegram adaptation of Berghmans/cmk_discord. It keeps the same notification semantics as far as Telegram allows:

• emoji per Checkmk notification type
• state highlighting via colored status marker
• state transition (previous -> current)
• service fields for host and service
• host/service output
• acknowledgement/downtime comments
• footer with check command, Checkmk site and timestamp
• inline button linking to the failed host/service when a Checkmk site URL is configured

Telegram does not support Discord-style embeds, embed sidebars/colors, webhook usernames or webhook avatars. Those parts are represented with message formatting, colored emoji markers and an inline button.

Installation

Manual installation

On the Checkmk server, switch into the site user and install the notification script:

sudo su - <site-name>
mkdir -p ~/local/share/check_mk/notifications
cp cmk_telegram.py ~/local/share/check_mk/notifications/cmk_telegram.py
chmod +x ~/local/share/check_mk/notifications/cmk_telegram.py

Then restart/refresh Checkmk if needed and create a notification rule.

Package source layout

The src/ folder follows the same source layout as the original MKP-style repository:

src/
  info.json
  notifications/
    cmk_telegram.py

On a Checkmk site you can copy the notification file manually, or use the src directory as the basis for creating an MKP on your Checkmk instance.

Configuration in Checkmk

Go to Setup → Notifications → Add rule and select Telegram Notification.

Parameters:

1. Telegram bot token — mandatory, e.g. 123456789:ABCDEF...
2. Telegram chat ID — mandatory, e.g. 123456789, -1001234567890, or @channelusername
3. Checkmk site URL — optional, e.g. https://checkmkhost.mycompany.com/my_monitoring
4. Telegram message thread ID — optional, for forum topics in supergroups
5. Disable notification sound — optional; use true, 1, yes, on to send silently

Getting Telegram values

1. Create a bot via @BotFather and copy the token.
2. Add the bot to your target chat/group/channel.
3. Send a message to the target chat.
4. Retrieve the chat ID with https://api.telegram.org/bot<TOKEN>/getUpdates, or use an ID helper bot in private chats.

For channels, the bot usually must be an administrator and the chat ID can also be the public channel username, e.g. @my_channel.

Quick local smoke test

This will not contact Telegram, but it verifies that the script builds a Telegram payload:

python3 examples/render_payload.py

License and attribution

This work is derived from Berghmans/cmk_discord, which is licensed under GPL-2.0. Keep GPL-2.0 attribution when redistributing modified versions.