(formerly telegram-middleman-bot)
A Telegram Bot to translate simple JSON HTTP requests into Telegram push messages that you will get on your Smartphone, PC or whatever Telegram client you have. Just like Gotify, but without an extra app.
- Support for Prometheus metrics (#18)
- Official Docker image (
[n1try/webhook2telegram](https://hub.docker.com/repository/docker/n1try/webhook2telegram)
) (#20)
- Project was renamed from telegram-middleman-bot to webhook2telegram
- Integration with Webmention.io
β οΈ alertmanager
inlet was renamed toalertmanager_webhook
and its endpoint has changed accordingly- Docker support, thanks to luza
- Integration with Bitbucket, thanks to luza
- Major code refactorings
- Support for Inlets (see below)
- Integration with Prometheus Alertmanager
Thanks to contributions by peet1993.
- Introduced explicit IPv6 support
- Introduced ability to specify network address to bind to
This is especially useful for developers or sysadmins. Imagine you want some kind of reporting from your application or server, like a daily report including some statistics. You don't want to actively look it up on a website but you want to receive it in a passive fashion. Just like getting an e-mail. But come on, let's be honest. E-Mails are so 2010. And they require your little server-side script to include some SMTP library and connect to a mail server. That's too heavyweight just to get some short information. Personally, I have a Python script running on my server which gathers some statistics from log files and databases and regularly sends me a Telegram message.
If you develop those thoughts further, this could potentially replace any kind of e-mail notifications - be it the message that someone has answered to your forum post, your favorite game is now on sale at Steam, and so on. It's lightweight and easy, unlike e-mails that have way too much overhead.
One option is to simply use the hosted instance running at https://apps.muetsch.io/webhook2telegram. It only allows for a maximum of 240 requests per recipient per day.
If you want to set this up on your own, do the following. You can either run the bot in long-polling- or webhook mode. For production use the latter option is recommended for various reasons. However, you'll need a server with a static IP and s (self-signed) SSL certificate.
git clone github.com/muety/webhook2telegram
GO111MODULE=on go build
- Long-polling mode:
./webhook2telegram -token <YOUR_BOTFATHER_TOKEN>
- Webhook mode:
./webhook2telegram -token <YOUR_BOTFATHER_TOKEN> -mode webhook
$ docker volume create webhook2telegram_data
$ docker run -d -p 8080:8080 \
-v webhook2telegram_data:/srv/data \
-e "APP_TOKEN=<YOUR_BOTFATHER_TOKEN>" \
-e "APP_MODE=webhook" \
--name webhook2telegram \
n1try/webhook2telegram
π‘ It is recommended to either use -useHttps
or set up a reverse proxy like nginx or Caddy to handle encryption.
-address
(string
) β Network address (IPv4) to bind to. Defaults to127.0.0.1
.-address6
(string
) β Network address (IPv6) to bind to. Defaults to::1
.-disableIPv6
(bool
) β Whether to disable listening on both IPv4 and IPv6 interfaces. Defaults tofalse
.-port
(int
) β TCP port to listen on. Defaults to8080
.-proxy
(string
) β Proxy connection string to be used for long-polling mode. Defaults to none.-useHttps
(bool
) β Whether to use HTTPS. Defaults tofalse
.-certPath
(string
) β Path of your SSL certificate when using webhook mode withuseHttp
. Default to none.-keyPath
(string
) β Path of your private SSL key when using webhook mode withuseHttp
. Default to none.-dataDir
(string
) β File system location where to store persistent data. Defaults to.
.-rateLimit
(int
) β Maximum number of messages to be delivered to each recipient per hour. Defaults to100
.-metrics
(bool
) β Whether to expose Prometheus metrics under/metrics
. Defaults tofalse
.
- You need to get a token from the bot. Send a message with
/start
to the Webhook2Telegram Bot therefore. - Now you can use that token to make HTTP POST requests to
http://localhost:8080/api/messages
(replace localhost by the hostname of your server running the bot or mine as shown above) with a body that looks like this.
{
"recipient_token": "3edf633a-eab0-45ea-9721-16c07bb8f245",
"text": "*Hello World!* (yes, this is Markdown)",
"type": "TEXT",
"origin": "My lonely server script"
}
NOTE: If the field type is omitted then the TEXT
type will be used as default, though this is not recommended as this may change in future versions.
More details are available here.
Inlets provide a mechanism to pre-process incoming data that comes in a format different from what is normally expected by the bot.
This is especially useful if data is sent by external, third-party applications which you cannot modify.
For instance, you might want to deliver alerts from Prometheus' Alertmanager as Telegram notifications. However, Alertmanager's webhook requests look much different from WH2TG's default input format. To still make them fit, you can write an Inlet to massage the data accordingly.
To directly address an inlet, request http://localhost:8080/api/inlets/<inlet_name>
. Note that /api/inlets/default
is equivalent to /api/messages
.
Following inlets are currently available:
Name | Description | Status |
---|---|---|
default |
Simply passes the request through without any changes | β |
alertmanager_webhook |
Consumes Alertmanager webhook requests | β |
bitbucket_webhook |
Accepts Bitbucket webhook requests to notify about a pipeline status change | β³ |
webmentionio_webhook |
Accepts Webmention.io webhook requests to notify about a new Webmention of one of your articles | β |
Further documentation about the individual inlets is available here.
Fundamental Prometheus metrics are exposed under /metrics
, if the -metrics
flag gets passed. They include:
webhook2telegram_messages_total{origin="string", type="string"}
webhook2telegram_requests_total{success="string"}
MIT @ Ferdinand MΓΌtsch