Zabbix-in-Telegram: alerts with graphs, sent as pictures

The alert arrives with a picture attached

Zabbix-in-Telegram sends Zabbix notifications with graphs to Telegram, and the feature list is short enough to read in one go.

Graphs based on the latest data are sent directly to your messenger. You can send messages both in private and in group or supergroup chats. Channels are supported, though only public ones, with a dirty hack available for private ones. The chat id is saved as a temporary file. Simple markdown and HTML are supported. Emoji can be used instead of a severity, and there is a location map.

The emoji feature has a footnote that matters more than it looks, because it points at a limitation in the other side of the integration: Zabbix does not support utf8mb4 encoding yet. So the emoji that stands in for a severity is a workaround for how the alert script's output is handled, not a free choice.

The TODO list is two items. Simple Zabbix management via the bot's commands, which is in a development state, and the ability to send a complex graph or part of a screen. Both are on the side of the bot being an assistant rather than a notification pipe.

The project is Python, MIT licensed, on the master branch, with a single release, 1.0, tagged Freaking First on 2019-03-18, and the last push on 2026-07-09. So the version numbers will not tell you anything, and the commit history is the only record of what changed.

It installs as an alert script, not as a service

The installation is a set of files dropped into a directory that Zabbix already knows about.

First, install the Python modules, which the README says is required for operation, with pip install -r requirements.txt in your command line.

Then put zbxtg.py in the AlertScriptsPath directory, the path that is set inside your zabbix_server.conf. If you want messages in a group chat, put zbxtg_group.py in the same location, and the README notes this applies to Zabbix 2.x.

Then create zbxtg_settings.py, copying it from zbxtg_settings.example.py, and put your settings in it in the same directory as the script. The example file is the layout reference, so a copy of the example is the intended starting point rather than an empty file.

The remaining steps are about connecting the two systems. Create a bot in Telegram and get its API key. Create a readonly user in the Zabbix web interface, and the reason given is for getting graphs from Zabbix, which is a good sign of how the tool works, because the graph rendering is done by asking the Zabbix frontend rather than by reimplementing the graph code. If you need an internet proxy, set the proxy host and port in the settings file, and socks5 is supported as well, with the wiki to help.

Then add a media type for Telegram in the Zabbix web interface, and the README flags that Zabbix 3.0 has different settings for that step, with a wiki page for the details. That is the kind of version-specific note that decides whether the setup takes ten minutes or an afternoon.

The action body is a small command language

After the media type exists, the last step is an action, and the action body is where the interesting part is. A Zabbix action can carry several lines, and the lines after the message text are the commands:

Last value: {ITEM.LASTVALUE1} ({TIME})
zbxtg;graphs
zbxtg;graphs_period=10800
zbxtg;itemid:{ITEM.ID1}
zbxtg;title:{HOST.HOST} - {TRIGGER.NAME}

The first line is ordinary Zabbix macro text, the last value and the time of the item. The lines that start with zbxtg; are the annotations, and the README lists them all.

zbxtg;graphs enables the attached graphs. zbxtg;graphs_period=10800 sets the graph period, with a default of 3600 seconds. zbxtg;graphs_width=700 sets the graph width, default 900 pixels, and zbxtg;graphs_height=300 sets the height, default 300 pixels. zbxtg;itemid:{ITEM.ID1} defines which item's graph to attach, taken from the trigger, and several item ids can be given as a comma separated list when a complex trigger needs more than one graph. zbxtg;title:{HOST.HOST} - {TRIGGER.NAME} sets the graph title. zbxtg;debug turns on debug mode, in which some logs and images are saved in the temporary directory. zbxtg;channel enables sending to channels. And zbxtg;to:username1,username2,username3 sends to those users without creating dedicated profiles and media for them, with zbxtg;to_group:Group Name One,Group Name Two doing the same for groups.

The formatting of the message itself is Telegram's, and the README links the markdown style and HTML style documentation for the send message API.

Private chats, groups and channels each have their own rule

The details of who receives the message are where the configuration goes wrong, and the README is specific.

The username is CASE-SENSITIVE. If you do not have a username, you can use the chat id directly, and you need to look up how to get it. Group chats do not have URLs, so you need to put the group's name in the media type. Messages for channels should be sent as for private chats, which you do by simply adding the bot to your channel and using the channel's username as if it were a real user.

The bootstrap step is a message to the bot. You send a message to your bot via Telegram, for example /start, and if you are in a group chat you start a conversation with your bot using /start@ZbxTgDevBot.

There is also a command line route to the same script, which is the fastest way to test the whole path before you involve Zabbix at all:

./zbxtg.py "@username" "first part of a message" "second part of a message" --debug

For the @username you substitute your Telegram username, NOT that of your bot, and it is case-sensitive, or you use the chat id. The two message parts are just text, for Telegram it does not matter whether it is a subject and a body, and you can skip the quotes if every parameter is a single word.

That last point is the practical advice in the README: run the script from a shell, with the debug flag, until it delivers a message, and only then wire it into a Zabbix action.

The known issues, and dependencies that have not moved in years

Two known issues are documented, and the first one will surprise you.

MEDIA_CAPTION_TOO_LONG means you have reached the limit of a caption with 200 characters in it, which is a limitation of the Telegram API. Such captions will be automatically cut to 200 characters. So the truncation is silent, and a long trigger name or a long item list will produce a message that ends mid-word without an error. The second known issue is about Zabbix 3.0 and higher, with 3.2, 3.4, 4.0, 4.2 and 4.4 named, and a wiki page for working with Zabbix 3.0.

The requirements file is where the age of the project shows most clearly:

PySocks==1.6.8
requests==2.20.0
requests-oauthlib==0.6.2

All three are pinned exactly, and all three are old enough that a current Python on a current operating system may not accept them. Nothing in the README says the pins are deliberate, and the project has had no tagged release since 2019 even though the commits continue, so the sensible thing for an adopter is to read the pins, try them, and be prepared to relax them.

The other point to check is where the documentation lives. The README is a good summary but the wiki is the real documentation, and the README says so in capitals, with a read the wiki if you have a problem with something.

What the repository actually contains

The top-level listing is seven files and one directory, which is the shape you would expect from a script that is dropped into a Zabbix server rather than installed as an application.

zbxtg.py is the main script that goes into the AlertScriptsPath directory, and zbxtg_group.py is the variant for group chats, which the README ties to Zabbix 2.x. ZbxTgDaemon.py is the third script, and the README does not describe it, so its role has to be read from the source. zbxtg_settings.example.py is the settings template you copy and fill in, and requirements.txt holds the three pinned dependencies. There is a bash-old-version/ directory, which suggests an older installation path kept for reference, and the LICENSE.txt and README.md.

There is no packaging file, no test directory and no service definition, and that is the design. This is a script that Zabbix invokes when a trigger fires, so the whole integration surface is the script, the settings file, the alert script path and the media type in the web interface.

For a monitoring team that wants pictures in their chat rather than a wall of text, that is a small, understandable footprint. The cost is that you are running a script with credentials for a bot and for a Zabbix user on the monitoring server, and that the version you get depends on how recently someone refreshed the pinned requirements.

Editorial conclusion

Adopt Zabbix-in-Telegram if you run Zabbix and want trigger notifications to arrive with the graph attached, because the integration is an alert script rather than a proxy, so it needs no new daemon and no change to how the server delivers media types. Do not adopt it without checking the Python version and the dependencies, because the requirements file still pins requests 2.20.0 and PySocks 1.6.8, which are years old, and the package has only one tagged release, from 2019. Before you deploy it, read the wiki rather than the README, because the settings file, the media type configuration and the Zabbix 3.0 differences are documented there, and remember that the username you put in the media type is case-sensitive and that a caption over 200 characters is cut without warning.

Frequently asked questions

Official sources

1. ableev/Zabbix-in-Telegram on GitHub
2. Issues
3. License: MIT
4. README
5. Releases