Module · Notification
Telegram
Short, timely Wintertrace notifications over Telegram to drivers, customers and admins — consent-based, queued through an outbox, no paid gateway.
- Version
- 1.0.4
- Released
- 25 Jun 2026
- Languages
- German, English
The right message to the right person
A winter service runs on timing. This module sends short, timely notifications over Telegram to the three groups that actually need telling — without a paid gateway and without routing data through a marketing platform.
Drivers
The operational nudge — a shift about to start, a route assigned — on the phone they already carry.
Customers
The “your site was serviced” confirmation, reaching someone on the move where an email would wait unread.
Admins
The things that need a person — a delivery that failed, a recipient who dropped off.
Consent before any message
Nobody is messaged because their number landed in a spreadsheet. Telegram cannot reach a person until that person opts in — the module leans into that rather than working around it. It lines up with the rest of the data-protection tooling.
How does someone connect?
Each recipient links their own account once. The comfortable way is a QR code or a deep link: the admin generates a one-time, time-limited link, the recipient scans it on their phone, and Telegram opens the bot and consumes the link. There is also a manual path — paste an identifier, confirm with a test message.
Who actually receives messages?
Only recipients who are genuinely connected and active. The connection is stored with a timestamp, and a recipient who is pending, deactivated, or has blocked the bot does not receive anything.
Is the bot token kept safely?
The token is stored encrypted and never appears in plain text in logs, error messages, or responses. Disconnecting the bot removes the webhook at Telegram’s end first, then deletes the token locally — recipients and templates are preserved.
How delivery works
The module does not call Telegram during a web request. Messages go to an outbox; a scheduled job drains it a moment later. This is what lets it run on ordinary shared hosting, with no background worker.
Sending never blocks the person who clicked. A brief outage at Telegram’s end does not lose a message — it is retried with a back-off, and a recipient who has blocked the bot is marked rather than retried forever. Every attempt is written to a delivery log, the same way the built-in email channel logs every send.
One thing to know: delivery depends on the cron job — the same scheduled task that already drives weather fetches and updates. Without it, messages sit in the outbox and are not sent. The setup guide is blunt about this, because a silent non-delivery is the worst kind of bug.
Set up in four steps
From an empty bot to delivered notifications.
- 1
Create a bot
Message @BotFather on Telegram, send
/newbot, and copy the token it gives you. - 2
Store the token
Paste it in the admin area. The module validates it, stores it encrypted, and registers the webhook automatically.
- 3
Connect recipients
Send each driver, customer, or admin a QR code or deep link. They opt in on their own phone — no message goes out before that.
- 4
Configure the cron job
One line in the server’s crontab drains the outbox every minute. The same line Wintertrace already uses for its other scheduled work.
For module authors
This module owns Telegram for the whole installation. Other modules send through it instead of learning the Bot API themselves.
There are two extension points. A direct call returns a result — was the message queued, was there no active recipient, was it a duplicate — for modules that want to react. A decoupled event needs no hard dependency at all: a module can dispatch it unconditionally, and if the Telegram module is not installed, nothing happens — no error, no exception.
That second path matters on self-hosted software, where you cannot assume which modules an operator has chosen to install.
Developer documentation ships inside the module
package. Download and unpack the archive — the
copy-paste examples for both extension points are in
docs/en/developers.md
(German: docs/de/developers.md),
alongside the setup and reference guides.
File integrity
Every published module is signed against the same Ed25519 root key used for Wintertrace core updates. The values below come straight from the catalogue API.
- Size
- 217 KB
- SHA-256
- 93965057133b…b1826504
- Released
- 25 Jun 2026
- Languages
- German, English
Install this module
The same two paths as any Wintertrace add-on.
From the admin area
Open the Modules menu inside a running Wintertrace installation. Pick Telegram from the catalogue and install with one click.
Manually via FTP
Download the archive, unpack it, and upload the folder to
modules/ inside your installation.
New here? The installation page walks through a fresh setup first.
Download
The module is served from the Wintertrace add-on registry at
jenni.noschmarrn.dev — the same source
the admin area pulls from.
External link — the download is served from the maintainer's registry at jenni.noschmarrn.dev and verified against the SHA-256 above.