Checkmk Telegram Plus connects Checkmk with Telegram. The bot sends automatic Checkmk alerts, lets you inspect hosts and services directly from Telegram, can trigger rechecks and acknowledgements, fetch service graphs, and optionally use AI features for alert help and Smart Notifications.
The goal is simple: understand monitoring problems faster when you are away from the Checkmk UI, reduce unnecessary clicks, and send important alerts to the right people.
Note: This bot is intended for private Telegram chats, not for groups.
The most important command:
curl -fsSL https://raw.githubusercontent.com/deexno/checkmk-telegram-plus/refs/heads/main/install.sh | sudo bashIf you are already logged in as root:
curl -fsSL https://raw.githubusercontent.com/deexno/checkmk-telegram-plus/refs/heads/main/install.sh | bashYou can optionally preseed the Checkmk site name, Telegram bot token and bot password:
curl -fsSL https://raw.githubusercontent.com/deexno/checkmk-telegram-plus/refs/heads/main/install.sh | sudo bash -s -- <omd_site_name> <telegram_bot_token> <bot_password>The installer still opens the interactive configuration review. Existing values are kept when you press Enter.
- Requirements
- Installation Step By Step
- Create The Checkmk Notification Rule
- First Start In Telegram
- Webapp And Telegram Mini App
- Feature Overview
- Automatic Notifications
- Smart Notifications With AI
- Service Graphs
- Admin Features
- Updates
- Configuration And Paths
- Uninstall
- Troubleshooting
- Support
- Checkmk version 2.1.p25 or newer.
- An existing OMD site, for example
mysite. - Root or sudo access on the Checkmk server.
- A Telegram bot created with BotFather.
- The bot token, for example in the format
123456789:ABC.... - A bot login password. You set this password during installation.
The installer checks the required programs itself. The server should have these tools available:
curlpython3tarmktemprunusersedsystemctl
Depending on your distribution, you may also need the Python venv package, for example python3-venv.
curl -fsSL https://raw.githubusercontent.com/deexno/checkmk-telegram-plus/refs/heads/main/install.sh | sudo bashThe installer will:
- Ask for the Checkmk site name.
- Fetch the latest GitHub Releases and let you choose the version to install.
- Offer the
mainbranch as an additional testing-only option. - Create the external app structure below
/opt/checkmk-telegram-plus. - Install Python dependencies into a dedicated virtual environment.
- Create systemd services for the bot, bridge and webapp.
- Install only a small notification adapter into the Checkmk site.
- Check and repair permissions for the queue, fallback queue, logs and runtime sockets.
- Automatically migrate existing legacy installations where possible.
During installation, you will see a configuration review. The most important fields are:
| Field | Meaning |
|---|---|
Bot language |
Default bot language, for example en or de. |
Telegram API token |
Token from BotFather. |
Bot password |
Password users must enter to authenticate with the bot. |
Allowed Telegram users |
Can stay empty. Users are stored after successful authentication. |
Admin Telegram users |
Optional. Only these users can access admin features. |
OpenAI model |
Optional for AI features. The default is gpt-4o-mini. |
OpenAI API token |
Optional for AI features and Smart Notifications. |
Checkmk Web graph export settings |
Optional, but recommended for reliable service graph rendering. |
Secrets are not printed in clear text. If a value is already configured, press Enter to keep it.
After installation, three systemd services should be running:
omd_site_name=<omd_site_name>
systemctl status checkmk-telegram-plus-$omd_site_name.service
systemctl status checkmk-telegram-plus-bridge-$omd_site_name.service
systemctl status checkmk-telegram-plus-web-$omd_site_name.serviceThe webapp is available on port 8183 by default:
http://<server-ip>:8183
From the server itself:
http://127.0.0.1:8183
After installation, create a Checkmk notification rule so Checkmk can hand alerts to Telegram Plus.
- Open Checkmk.
- Go to the notification rules.
- Create a new rule.
- Select the Telegram Plus notification method.
- Set the first parameter to one of these values:
| Parameter | Behavior |
|---|---|
notifications_loud |
Sends loud Telegram notifications. The device uses the normal notification sound or vibration. |
notifications_silent |
Sends silent Telegram notifications. The message appears in the chat, but without notification sound and usually without vibration. |
notifications_smart |
Sends the alert to the Smart Notification logic. The AI can decide whether the alert should be sent loud, sent silent, or suppressed. |
You can create multiple rules, for example a loud rule for critical production systems and a silent rule for less urgent systems. Alternatively, create one broad notifications_smart rule and let the Smart Notification logic filter duplicate, noisy or follow-up alerts.
Important: Users must enable notifications in the bot or webapp. Notifications are disabled by default.
Open your Telegram bot and start it with:
/start
or:
/menu
The bot does not accept normal commands until you authenticate. Start authentication with:
/authenticate
Then enter the bot password you configured during installation.
After successful authentication, your Telegram user is stored and you can use the bot menus.
Open this menu in the bot:
🔔 NOTIFICATION SETTINGS
There you can enable or disable these subscriptions for your own user:
- Loud Notifications
- Silent Notifications
- Smart Notifications
This setting only affects your Telegram user. Other users manage their own subscriptions independently.
Checkmk Telegram Plus includes a webapp in addition to the Telegram bot. It is not meant to replace Checkmk. It is a compact control center for common mobile and operational workflows.
After installation, the webapp listens on port 8183 by default:
http://<server-ip>:8183
Login uses the normal bot password. Administrative sections require a separate web admin password. Authorized admins can request that password from the Telegram admin menu:
⚙️ ADMIN SETTINGS -> 🔑 GET WEB ADMIN PASSWORD
| Area | Function |
|---|---|
| Dashboard | Shows active users, queue size and the most recent alerts. |
| Monitoring | Browse host groups, open hosts and inspect services with their current state. |
| Alert Log | Shows received notifications, delivery status, errors and alert details. |
| Deliveries | Shows which Telegram users received an alert and whether delivery succeeded. |
| Alert Actions | Shows actions such as recheck, graph request, AI help, reminder or acknowledgement for each event. |
| User Management | Admins can enable or disable users, assign admin rights and manage notification subscriptions. |
| Audit Log | Shows logins, user changes, config changes and critical actions. |
| Config | Admins can edit the active runtime configuration and Smart Notification instructions. |
You can also expose the webapp as a Telegram Mini App / Web App. It then appears directly inside your Telegram bot as a button and opens inside Telegram.
This is useful because:
- Users do not need to open a separate browser.
- Monitoring, alert history and user management are available next to the bot chat.
- The webapp feels like a compact mobile app on phones.
- The team gets one obvious entry point: open the Telegram bot, tap the button, use the control center.
Important: Telegram requires an externally reachable HTTPS URL. A local URL such as http://127.0.0.1:8183 only works on the server itself and cannot be used as a Telegram Mini App for users.
Recommended setup:
Telegram
-> https://monitoring.example.com
-> Reverse proxy with TLS
-> http://127.0.0.1:8183
-> Checkmk Telegram Plus webapp
Example Nginx reverse proxy:
server {
listen 443 ssl;
server_name monitoring.example.com;
ssl_certificate /etc/letsencrypt/live/monitoring.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/monitoring.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8183;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
}Then configure the button in Telegram:
- Open
@BotFather. - Select your bot with
/mybots. - Open the bot settings.
- Depending on the BotFather menu, choose
Menu Button,Configure Mini App, or/setmenubutton. - Set the URL to your HTTPS address, for example
https://monitoring.example.com. - Set the button text, for example
MonitoringorControl Center.
Security note: The current webapp authenticates users with the bot password and protects admin actions with the separate web admin password. The Mini App integration is a convenient entry point inside Telegram, but it does not replace proper exposure controls. If the URL is reachable from the internet, use HTTPS, firewall rules, VPN or an upstream access control layer that fits your environment.
After authentication, the bot provides a menu for common monitoring tasks:
| Menu Item | Description |
|---|---|
⭕ GET HOST STATUS |
Queries the current state of a host. |
📃 GET SERVICES OF HOST |
Lists all services of a host with their current state. |
🔍 GET SERVICE DETAILS |
Shows details for a specific service, including output, state, last check time and metrics. |
🔥 GET ALL HOST PROBLEMS |
Lists current host problems from Checkmk. |
❗ GET ALL SERVICE PROBLEMS |
Lists current service problems from Checkmk. |
🔔 NOTIFICATION SETTINGS |
Enables or disables Loud, Silent and Smart Notifications for your own user. |
📉 GET SERVICE GRAPHS |
Fetches Checkmk service graphs and sends them as images in Telegram. |
🔄 RESCHEDULE CHECK |
Triggers a new check for a host or service. |
⚙️ ADMIN SETTINGS |
Opens administrative features if your user has admin rights. |
Automatic alert messages can include additional inline buttons:
| Button | Description |
|---|---|
RECHECK |
Runs a new check and returns the updated state. |
GET SERVICE GRAPHS |
Sends matching Checkmk graphs for the affected service. |
HELP |
Asks the AI for a short explanation and possible troubleshooting steps. |
ACKNOWLEDGE |
Acknowledges the service problem in Checkmk. |
REMIND |
Creates a reminder so the alert appears again later in Telegram. |
These actions are written to the audit log so it remains clear who did what.
The bot can translate replies into different languages. Admins can change the bot language from the admin menu. The webapp currently supports German and English and includes a language switcher in the navigation.
Checkmk passes alerts to the installed notification adapter. The adapter sends the notification to the external Telegram Plus app. If the app is temporarily unavailable, the adapter writes the alert into a fallback queue. Once the app is running again, it can drain that queue.
This prevents alerts from being lost just because the bot service was restarted briefly.
notifications_loud is meant for important alerts. Telegram treats these messages like normal notifications. This is useful for:
- critical production systems
- host DOWN events
- important service CRITICAL events
- on-call duty
notifications_silent is meant for less urgent information. The message arrives in the chat, but does not create a loud push notification. This is useful for:
- less critical systems
- warnings
- recovery messages
- informational messages that should not wake anyone up
Each user decides which notification types they want to receive. One admin can receive loud messages, while another user receives only silent messages or only Smart Notifications.
Admins can also manage these settings centrally in the webapp.
Smart Notifications are useful in environments where classic notification rules create too much noise.
If you use this parameter in a Checkmk notification rule:
notifications_smart
the alert is not blindly sent to all Smart subscribers. Instead, it is enriched and evaluated first.
The Smart Notification logic can use:
- the current Checkmk alert
- hostname, service, state change and plugin output
- Checkmk parent/child dependency context
- current host and service relationships
- recent notification history from the local SQLite database
- custom rules from
smart-notification-instructions.txt - the OpenAI Responses API when an API key is configured
The AI can decide:
| Decision | Meaning |
|---|---|
| send loud | The alert is important enough for a loud notification. |
| send silent | The alert is relevant, but not urgent enough for a loud notification. |
| suppress | The alert is suppressed, for example because it looks like a duplicate, a follow-up failure or flapping. |
The Smart Notification policy lives here:
/etc/checkmk-telegram-plus/smart-notification-instructions.txt
Edit it directly:
omd_site_name=<omd_site_name>
nano /etc/checkmk-telegram-plus/smart-notification-instructions.txt
systemctl restart checkmk-telegram-plus-$omd_site_name.serviceor use the webapp:
Webapp -> Admin Login -> Config -> Smart Notification Instructions
Open the configuration:
omd_site_name=<omd_site_name>
nano /etc/checkmk-telegram-plus/$omd_site_name.iniSet your API key in the [openai] section:
[openai]
model = gpt-4o-mini
token = YOUR_OPENAI_API_KEYRestart the bot:
systemctl restart checkmk-telegram-plus-$omd_site_name.serviceNote: AI output can be wrong or incomplete. Use it as troubleshooting assistance, not as the only decision source for critical systems.
The AI feature has two main areas.
Automatic alert messages can include a HELP button. When you press it, the AI creates a short assessment:
- What might have happened?
- What does the service output probably mean?
- Which first troubleshooting steps could make sense?
- Which common causes match the error pattern?
The bot can also answer general questions, for example:
- questions about Checkmk
- Linux or network troubleshooting questions
- first analysis ideas for service outputs
- general IT questions
Checkmk Telegram Plus can fetch service graphs from Checkmk and send them in Telegram. This helps you see whether a problem appeared suddenly, developed slowly, or keeps repeating.
The bot tries several methods:
- Checkmk's internal graph renderer, if the installed Checkmk version still provides it.
- Checkmk Web notification graph endpoint
ajax_graph_images.py. - Checkmk Web PNG export endpoint
graph_image.py.
Recommended configuration:
omd_site_name=<omd_site_name>
nano /etc/checkmk-telegram-plus/$omd_site_name.ini[checkmk_web]
base_url = http://127.0.0.1/<omd_site_name>
automation_user = telegram_plus
automation_secret = YOUR_AUTOMATION_SECRET
graph_count = 3
allow_legacy_url_auth = noThe automation user must be allowed to see the requested hosts and services and query graph data. On newer Checkmk versions, the role permission Query metric backend from custom graph editor may be required.
Graph support is optional. If graphs are not available, the bot, alerts and bridge continue running.
Admin features are only intended for users configured as admins in the config or webapp.
Open the configuration:
omd_site_name=<omd_site_name>
nano /etc/checkmk-telegram-plus/$omd_site_name.iniThe [telegram_bot] section contains admin_users:
[telegram_bot]
allowed_users = alice (123456789),bob (987654321),
admin_users = alice (123456789),Restart the bot:
systemctl restart checkmk-telegram-plus-$omd_site_name.serviceYou can also assign admin rights in the webapp:
Webapp -> Admin Login -> Users -> enable Admin -> Save
The Telegram admin menu includes:
| Function | Description |
|---|---|
📖 GET LOGS |
Shows recent bot logs in Telegram. |
🇩🇪 CHANGE LANGUAGE |
Changes the bot language. |
🔓 GET PASSWORD |
The bot password is no longer displayed in clear text for security reasons. |
🔒 CHANGE PASSWORD |
Changes the bot password. |
👥 LIST USERS |
Lists known Telegram users, roles and notification subscriptions. |
🗑️ DELETE USERS |
Removes users from the bot database. |
⬆️ CHECK FOR UPDATES |
Checks whether a newer version is available. |
🔔 LIST NOTIFY QUEUE |
Shows the current notification queue. |
✴ GET OMD STATUS |
Gets the OMD status of the Checkmk site. |
⬆ START OMD SERVICES |
Starts OMD services of the Checkmk site. |
⬇ STOP OMD SERVICES |
Stops OMD services of the Checkmk site. |
🔑 GET WEB ADMIN PASSWORD |
Shows the separate web admin password. |
Critical actions are logged. This includes:
- web logins
- failed logins
- user changes
- config changes
- rechecks
- graph requests
- acknowledgements
- AI help requests
- Smart Notification decisions
The audit log is visible in the webapp.
Checkmk Telegram Plus uses a split architecture.
Checkmk itself should load as few external dependencies as possible. Therefore, only a small notification adapter is installed inside the Checkmk site. The actual app with Telegram, Flask, OpenAI and other Python dependencies runs outside the Checkmk site.
| Component | Responsibility |
|---|---|
| Checkmk notification adapter | Collects NOTIFY_* variables and sends them to the external app. |
| External Telegram app | Handles alerts, bot commands, AI features and Telegram delivery. |
| Checkmk bridge | Runs allowed Checkmk operations as the site user. |
| Webapp | Provides dashboard, monitoring, alert log, user admin, audit and config pages. |
| SQLite state | Stores users, notification history, deliveries and audit entries. |
| Fallback queue | Buffers notifications while the external app is temporarily unavailable. |
More details are available in docs/ARCHITECTURE.md.
To update, run the same installation command again:
curl -fsSL https://raw.githubusercontent.com/deexno/checkmk-telegram-plus/refs/heads/main/install.sh | sudo bashThe installer:
- shows the latest releases
- lets you choose the target version
- backs up existing configuration files
- migrates legacy installations
- keeps existing values when you press Enter
- restarts the bot, bridge and webapp
If fallback queue permissions or group memberships cause problems after an upgrade, rerun the installer and restart the Checkmk site so already-running Checkmk processes pick up the new group membership.
Important paths:
/opt/checkmk-telegram-plus/app
/opt/checkmk-telegram-plus/venv
/etc/checkmk-telegram-plus/<omd_site_name>.ini
/etc/checkmk-telegram-plus/smart-notification-instructions.txt
/var/lib/checkmk-telegram-plus/<omd_site_name>
/var/log/checkmk-telegram-plus
/run/checkmk-telegram-plus/<omd_site_name>.sock
/run/checkmk-telegram-plus/<omd_site_name>-bridge.sock
Important services:
checkmk-telegram-plus-<omd_site_name>.service
checkmk-telegram-plus-bridge-<omd_site_name>.service
checkmk-telegram-plus-web-<omd_site_name>.service
Show logs:
omd_site_name=<omd_site_name>
journalctl -u checkmk-telegram-plus-$omd_site_name.service -f
journalctl -u checkmk-telegram-plus-bridge-$omd_site_name.service -f
journalctl -u checkmk-telegram-plus-web-$omd_site_name.service -fEdit configuration:
omd_site_name=<omd_site_name>
nano /etc/checkmk-telegram-plus/$omd_site_name.ini
systemctl restart checkmk-telegram-plus-$omd_site_name.service
systemctl restart checkmk-telegram-plus-web-$omd_site_name.serviceomd_site_name=<omd_site_name>
systemctl stop checkmk-telegram-plus-$omd_site_name.service
systemctl stop checkmk-telegram-plus-bridge-$omd_site_name.service
systemctl stop checkmk-telegram-plus-web-$omd_site_name.servicerm -f /etc/systemd/system/checkmk-telegram-plus-$omd_site_name.service
rm -f /etc/systemd/system/checkmk-telegram-plus-bridge-$omd_site_name.service
rm -f /etc/systemd/system/checkmk-telegram-plus-web-$omd_site_name.service
systemctl daemon-reloadDelete all Checkmk notification rules that use the Telegram Plus adapter.
rm -f /omd/sites/$omd_site_name/local/share/check_mk/notifications/telegram_plus_notify_listener
rm -rf /omd/sites/$omd_site_name/local/share/checkmk-telegram-plus
rm -f /etc/checkmk-telegram-plus/$omd_site_name.ini
rm -rf /var/lib/checkmk-telegram-plus/$omd_site_nameOnly remove these paths if no other Checkmk site uses this installation:
rm -rf /opt/checkmk-telegram-plus
rm -rf /var/log/checkmk-telegram-plusThe detailed troubleshooting guide is here:
Useful first checks:
omd_site_name=<omd_site_name>
systemctl status checkmk-telegram-plus-$omd_site_name.service
systemctl status checkmk-telegram-plus-bridge-$omd_site_name.service
systemctl status checkmk-telegram-plus-web-$omd_site_name.service
journalctl -u checkmk-telegram-plus-$omd_site_name.service -n 100If notifications do not arrive:
- Is the Checkmk notification rule active?
- Is the first parameter correct, for example
notifications_loud? - Did the Telegram user authenticate with
/authenticate? - Are notification settings enabled for this user?
- Is the bot service running?
- Are there entries in the fallback queue?
If graphs do not work:
- Is
[checkmk_web]configured correctly? - Can the automation user see the host and service in Checkmk?
- Does the user have the required permissions for graph data?
- Is
base_url = http://127.0.0.1/<omd_site_name>reachable locally?
In addition to the features described here, we also develop personalized AI chatbots tailored to specific requirements. These custom solutions can provide more precise and context-aware assistance for support, monitoring and other specialized use cases.
More information and example projects: https://www.dexdot.it/
