# 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.