Awesome
<p align="center"> <img src="views/static/logo.svg" height="200"> </p> <h1 align="center">Telepush</h1> <h3 align="center">Send Telegram push notifications easily via HTTP</h3> <p align="center"> <img src="https://badges.fw-web.space/github/license/muety/telepush"> <a href="mailto:ferdinand@muetsch.io?subject=Thanks for creating Telepush" target="_blank"><img src="https://badges.fw-web.space/badge/say%20thanks-%F0%9F%99%8F-%23159CE4"></a> <a href="https://wakapi.dev" target="_blank"><img src="https://badges.fw-web.space/endpoint?url=https://wakapi.dev/api/compat/shields/v1/n1try/interval:any/project:telepush&color=blue"></a> <a href="https://sonarcloud.io/dashboard?id=muety_telegram-middleman-bot"><img src="https://sonarcloud.io/api/project_badges/measure?project=muety_telegram-middleman-bot&metric=security_rating"></a> </p>π Description
A simple Telegram Bot to translate POST
requests with JSON payload into Telegram push
messages. Similar Gotify and ntfy.sh, except without an extra app. Useful for
server monitoring, alerting, and anything else.
β¨οΈ How to use?
Step 1: Get a token
Open Telegram, start a chat with the TelepushBot (or your own bot, respectively) and
type /start
to obtain a recipient token.
Step 2: Send messages
Messages are sent via POST
to https://telepush.dev/api/[[inlets/<inlet_name>]|messages]/<recipient>
.
RECIPIENT_TONEN=... # The token you received using /start.
curl -XPOST \
-H 'Content-Type: application/json' \
-d '{ "text": "*Hello World!* (yes, this is Markdown)" }' \
"https://telepush.dev/api/messages/${RECIPIENT_TONEN}"
When hosting your own instance, replace the URL respectively.
βοΈ Message options
Key | Type | Description |
---|---|---|
text * | string | Actual message in plain text or Markdown format |
origin | string | What will be shown as the sender of your message |
type | [TEXT , FILE ] | Message type, i.e. to send text or a file (default: TEXT ) |
file ** | base64 | Base64-encoded file content |
filename ** | string | Name of the file to send |
options | object | Additional options to pass |
options.disable_link_previews | bool | Whether to show previews of links in the chat |
*
= required for type: TEXT
, **
= required for type: FILE
More details to be found here.
πββοΈ How to run?
βοΈ Option 1: telepush.dev
Simply use the official hosted instance. Rate-limited to 240 requests per recipient per day.
π Option 2: Self-hosted
When hosting your own Telepush instance, you need to create a new bot with @BotFather first. As a result, you will get a token that you then pass to Telepush when starting the server (see below).
π³ Option 2.1: With Docker
$ docker volume create telepush_data
$ docker run -d \
-p 8080:8080 \
-v telepush_data:/srv/data \
--name telepush \
ghcr.io/muety/telepush \
-mode webhook \
-token <YOUR_BOTFATHER_TOKEN>
π Option 2.2: With Kubernetes
See here.
π Option 2.3: Compile from source
# Install
$ go install github.com/muety/telepush@latest
# Run (webhook mode)
$ ./telepush -token <YOUR_BOTFATHER_TOKEN> -mode webhook
βοΈ Webhook vs. long-polling
You can either run the bot in long-polling- or webhook mode (-mode [webhook|poll]
). For production use the latter
option is recommended for various reasons. However, you'll need a server with
a static IP and a TLS certificate.
More details about webhook setup can be found in Marvin's Marvellous Guide to All Things Webhook.
π HTTPS
In webhook mode, Telegram requires your updates endpoint to use HTTPS. To enable such, either run Telepush behind a reverse proxy (like Caddy), that terminates TLS.
Or, let Telepush itself handle TLS. You'll need a certificate for this, so either get one from Let's Encrypt or create a self-signed one, then use -useHttps
in combination with -certPath
and -keyPath
pointed to your certificate and private key files respectively.
For self-signed certificates, you'll need to pass your public key to Telegram's setWebhook
method in addition, see these instructions.
π§ Configuration options
-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.-urlSecret
(string
) β Random suffix to append to your updates route called by Telegram's servers to prevent spam. 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.
.-inlets
(string
) β Path to folder containing config-based inlet definitions in YAML format. Defaults to./inlets.d
.-blacklist
(string
) β Path to a line-separated blacklist file containing user IDs (send/help
to get your id). Defaults toblacklist.txt
.-whitelist
(string
) β Path to a line-separated whitelist file containing user IDs (send/help
to get your id). Defaults towhitelist.txt
.-rateLimit
(int
) β Maximum number of messages to be delivered to each recipient per hour. Defaults to100
.-truncateMsgs
(bool
) β Truncate too long messages to 4096 characters instead of rejecting them. Defaults tofalse
.-metrics
(bool
) β Whether to expose Prometheus metrics under/metrics
. Defaults tofalse
.
When using the Docker image, you can alternatively set most of the above config options via environment variables (passed to docker run
using -e
), e.g. APP_USE_HTTPS=true
, APP_CERT_PATH=/etc/telepush.crt
, etc. For details, see entrypoint.sh
.
Whitelist vs. Blacklist
(aka. allow-list vs. block-list)
<img src=".github/message-accept.svg" width="600px">π₯ 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 Telepush'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 https://telepush.dev/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 | Consumes Alertmanager webhook requests | β |
grafana | Consumes Grafana webhook requests | β |
webmentionio | Accepts Webmention.io webhook requests to notify about a new Webmention of one of your articles | β |
stripe | Accepts Stripe webhooks to notify about subscription status changes | β |
bitbucket | Accepts Bitbucket webhook requests to notify about a pipeline status change | β³ |
You can also define your own, custom inlets in YAML. Further documentation on this and about the individual pre-existing inlets is available here.
For all inlets, the following options are available to be passed as query parameters:
Parameter | Description |
---|---|
disable_link_previews | Disable a preview version of web links detected in the message. Default: false . |
disable_markdown | Disable the message being attempted to be parsed as Markdown. Default: false . |
Example: POST https://telepush.dev/api/inlets/default?disable_markdown=true&disable_link_previews=true
.
π Metrics
Fundamental Prometheus metrics are exposed under /metrics
, if the -metrics
flag gets passed.
They include:
telepush_messages_total{origin="string", type="string"}
telepush_requests_total{success="string"}
π Troubleshooting
Error: panic: template: pattern matches no files: *.tpl.html
When running Telepush as a single executable, you must not use dev mode unless Telepush's source code is located inside the same directory. Make sure to not pass -env dev
in this case.
π License
MIT @ Ferdinand MΓΌtsch