webhook2telegram

README

webhook2telegram

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

Why might this be useful?

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.

How to run

Hosted

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.

Self-hosted

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.

Compile from source

1. git clone github.com/muety/webhook2telegram
2. GO111MODULE=on go build
3. Long-polling mode: ./webhook2telegram -token <YOUR_BOTFATHER_TOKEN>
4. Webhook mode: ./webhook2telegram -token <YOUR_BOTFATHER_TOKEN> -mode webhook

Using Docker

$ 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 \
    ghcr.io/muety/webhook2telegram:latest

💡 It is recommended to either use -useHttps or set up a reverse proxy like nginx or Caddy to handle encryption.

Additional parameters

• -address (string) – Network address (IPv4) to bind to. Defaults to 127.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 to false.
• -port (int) – TCP port to listen on. Defaults to 8080.
• -proxy (string) – Proxy connection string to be used for long-polling mode. Defaults to none.
• -useHttps (bool) – Whether to use HTTPS. Defaults to false.
• -certPath (string) – Path of your SSL certificate when using webhook mode with useHttp. Default to none.
• -keyPath (string) – Path of your private SSL key when using webhook mode with useHttp. Default to none.
• -dataDir (string) – File system location where to store persistent data. Defaults to ..
• -blacklist (string) – Path to a user id blacklist file. Defaults to blacklist.txt.
• -rateLimit (int) – Maximum number of messages to be delivered to each recipient per hour. Defaults to 100.
• -metrics (bool) – Whether to expose Prometheus metrics under /metrics. Defaults to false.

How to use

1. You need to get a token from the bot. Send a message with /start to the Webhook2Telegram Bot therefore.
2. 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 can be found here.

Inlets

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.

Metrics

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"}

License

MIT @ Ferdinand Mütsch