stockmind/telegram-middleman-bot repository overview

⁠telegram-middleman-bot

I'm the @MiddleMan⁠ bot! I sit in the middle between whatever you want to send yourself as a message and your Telegram.

I translate simple JSON HTTP requests into Telegram push messages that you will get on your Smartphone, PC or whatever Telegram client you have.

⁠What's new (2019-11-06) ?

Thanks to contributions by peet1993⁠.

• Introduced explicit IPv6 support
• Introduced ability to specify network address to bind to

⁠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 it?

You can either set up your own instance or use mine, which is running at https://apps.muetsch.io/middleman⁠. The hosted instance only allows for a maxmimum 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.

1. Make sure u have the latest version of Go installed.
2. go get github.com/n1try/telegram-middleman-bot
3. cd <YOUR_GO_WORKSPACE_PATH>/src/github.com/n1try/telegram-middleman-bot
4. go get ./...
5. go build .

⁠Using long-polling mode

1. ./telegram-middleman-bot --token <TOKEN_YOU_GOT_FROM_BOTFATHER> --port 8080 (of course you can use a different port)

⁠Using webhook mode

1. If you don't have an official, verified certificate, create one doing openssl req -newkey rsa:2048 -sha256 -nodes -keyout middleman.key -x509 -days 365 -out middleman.pem (the CN must match your server's IP address)
2. Tell Telegram to use webhooks to send updates to your bot. curl -F "url=https://<YOUR_DOMAIN_OR_IP>/api/updates" -F "certificate=@<YOUR_CERTS_PATH>.pem" https://api.telegram.org/bot<TOKEN_YOU_GOT_FROM_BOTFATHER>/setWebhook
3. ./telegram-middleman-bot --token <TOKEN_YOU_GOT_FROM_BOTFATHER> --mode webhook --certPath middleman.pem --keyPath middleman.key --port 8443 --useHttps (of course you can use a different port)

Alternatively, you can also use a reverse proxy like nginx or Caddy⁠ to handle encryption. In that case you would set the mode to webhook, but useHttps to false and your bot wouldn't need any certificate.

⁠Additional parameters

• --address (string) – Network address (IPv4) to bind to. Default to 127.0.0.1.
• --address6 (string) – Network address (IPv6) to bind to. Default to ::1.
• --disableIPv6 (bool) – Whether or not to disable listening on both IPv4 and IPv6 interfaces. Default to false.
• --proxy (string) – Proxy connection string to be used for long-polling mode. Defaults to none.
• --rateLimit (int) – Maximum number of messages to be delivered to each recipient per hour. Defaults to 10.

⁠How to use it?

1. You need to get a token from the bot. Send a message with /start to the @MiddleManBot⁠ 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.

1. If you want to attach a file in the HTTP POST request you need to encode it to a Base64 string and send it in the body as follows.

{
	"recipient_token": "3edf633a-eab0-45ea-9721-16c07bb8f245",
	"file": "SGVsbG8gV29ybGQhCg==",
	"filename": "file.txt",
	"type": "FILE",
	"origin": "My lonely server script"
}

⁠License

MIT @ Ferdinand Mütsch⁠