Initial commit

README.md

@@ -0,0 +1,77 @@
+# 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:
+
+```bash
+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:
+
+```text
+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:
+
+```bash
+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.