{"id":13610601,"url":"https://github.com/muety/telepush","last_synced_at":"2025-05-16T18:05:54.840Z","repository":{"id":43493997,"uuid":"96197928","full_name":"muety/telepush","owner":"muety","description":"🤖 A simple bot to translate JSON HTTP requests into Telegram push messages ","archived":false,"fork":false,"pushed_at":"2024-01-10T07:38:51.000Z","size":328,"stargazers_count":492,"open_issues_count":9,"forks_count":40,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-05-02T02:21:47.263Z","etag":null,"topics":["chatbot","chatops","devops","hacktoberfest","telegram","telegram-bot"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/muety.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"muety","liberapay":"muety","custom":["https://www.paypal.com/donate/?hosted_button_id=UMLX3AG4923JJ","https://www.buymeacoffee.com/n1try"]}},"created_at":"2017-07-04T09:01:44.000Z","updated_at":"2024-06-02T20:09:12.571Z","dependencies_parsed_at":"2023-07-14T02:09:08.794Z","dependency_job_id":"dff5cdb4-f0be-4f9b-ae72-880e414f4b23","html_url":"https://github.com/muety/telepush","commit_stats":null,"previous_names":["muety/webhook2telegram","n1try/telegram-middleman-bot"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muety%2Ftelepush","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muety%2Ftelepush/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muety%2Ftelepush/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muety%2Ftelepush/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/muety","download_url":"https://codeload.github.com/muety/telepush/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248597945,"owners_count":21130984,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","chatops","devops","hacktoberfest","telegram","telegram-bot"],"created_at":"2024-08-01T19:01:46.206Z","updated_at":"2025-04-12T16:38:55.780Z","avatar_url":"https://github.com/muety.png","language":"Go","funding_links":["https://github.com/sponsors/muety","https://liberapay.com/muety","https://www.paypal.com/donate/?hosted_button_id=UMLX3AG4923JJ","https://www.buymeacoffee.com/n1try"],"categories":["Go"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"views/static/logo.svg\" height=\"200\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eTelepush\u003c/h1\u003e\n\u003ch3 align=\"center\"\u003eSend Telegram push notifications easily via HTTP\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://badges.fw-web.space/github/license/muety/telepush\"\u003e\n\u003ca href=\"mailto:ferdinand@muetsch.io?subject=Thanks for creating Telepush\" target=\"_blank\"\u003e\u003cimg src=\"https://badges.fw-web.space/badge/say%20thanks-%F0%9F%99%8F-%23159CE4\"\u003e\u003c/a\u003e\n\u003ca href=\"https://wakapi.dev\" target=\"_blank\"\u003e\u003cimg src=\"https://badges.fw-web.space/endpoint?url=https://wakapi.dev/api/compat/shields/v1/n1try/interval:any/project:telepush\u0026color=blue\"\u003e\u003c/a\u003e\n\u003ca href=\"https://sonarcloud.io/dashboard?id=muety_telegram-middleman-bot\"\u003e\u003cimg src=\"https://sonarcloud.io/api/project_badges/measure?project=muety_telegram-middleman-bot\u0026metric=security_rating\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## 📄 Description\n\nA simple [Telegram Bot](https://t.me/MiddleManBot) to translate `POST` requests with JSON payload into Telegram push\nmessages. Similar [Gotify](https://gotify.net/) and [ntfy.sh](https://ntfy.sh/), except without an extra app. Useful for\nserver monitoring, alerting, and anything else.\n\n## ⌨️ How to use?\n\n### Step 1: Get a token\n\nOpen Telegram, start a chat with the [TelepushBot](https://t.me/MiddleManBot) (or your own bot, respectively) and\ntype `/start` to obtain a recipient token.\n\n### Step 2: Send messages\n\nMessages are sent via `POST` to **`https://telepush.dev/api/[[inlets/\u003cinlet_name\u003e]|messages]/\u003crecipient\u003e`**.\n\n```bash\nRECIPIENT_TONEN=... # The token you received using /start.\ncurl -XPOST \\\n     -H 'Content-Type: application/json' \\\n     -d '{ \"text\": \"*Hello World!* (yes, this is Markdown)\" }' \\\n     \"https://telepush.dev/api/messages/${RECIPIENT_TONEN}\"\n```\n\nWhen hosting your own instance, replace the URL respectively.\n\n### ✉️ Message options\n\n| **Key**                             | **Type**         | **Description**                                             |\n|-------------------------------------|------------------|-------------------------------------------------------------|\n| **`text`***                         | string           | Actual message in plain text or Markdown format             |\n| **`origin`**                        | string           | What will be shown as the sender of your message            |\n| **`type`**                          | [`TEXT`, `FILE`] | Message type, i.e. to send text or a file (default: `TEXT`) |\n| **`file`****                        | base64           | Base64-encoded file content                                 |\n| **`filename`****                    | string           | Name of the file to send                                    |\n| **`options`**                       | object           | Additional options to pass                                  |\n| **`options.disable_link_previews`** | bool             | Whether to show previews of links in the chat               |\n\n`*` = required for `type: TEXT`, `**` = required for `type: FILE`\n\nMore details to be found [here](/inlets).\n\n## 🏃‍♀️ How to run?\n\n### ☁️ Option 1: [telepush.dev](https://telepush.dev)\n\nSimply use the official hosted instance. Rate-limited to 240 requests per recipient per day.\n\n### 🌐 Option 2: Self-hosted\n\nWhen hosting your own Telepush instance, you need to create a new bot with [@BotFather](https://t.me/BotFather) first.\nAs a result, you will get a token that you then pass to Telepush when starting the server (see below).\n\n#### 🐳 Option 2.1: With Docker\n\n```bash\n$ docker volume create telepush_data\n$ docker run -d \\\n    -p 8080:8080 \\\n    -v telepush_data:/srv/data \\\n    --name telepush \\\n    ghcr.io/muety/telepush \\\n    -mode webhook \\\n    -token \u003cYOUR_BOTFATHER_TOKEN\u003e\n```\n\n#### 🐋 Option 2.2: With Kubernetes\nSee [here](https://github.com/muety/telepush/issues/68#issue-2073400161).\n\n#### 🛠 Option 2.3: Compile from source\n\n```bash\n# Install\n$ go install github.com/muety/telepush@latest\n\n# Run (webhook mode)\n$ ./telepush -token \u003cYOUR_BOTFATHER_TOKEN\u003e -mode webhook\n```\n\n#### ↔️ Webhook vs. long-polling\n\nYou can either run the bot in long-polling- or webhook mode (`-mode [webhook|poll]`). For production use the latter\noption is recommended for [various reasons](https://core.telegram.org/bots/webhooks). However, you'll need a server with\na static IP and a TLS certificate.\n\nMore details about webhook setup can be found in [__Marvin's Marvellous Guide to All Things Webhook__](https://core.telegram.org/bots/webhooks).\n\n#### 🔓 HTTPS\nIn webhook mode, Telegram requires your [updates endpoint](https://core.telegram.org/bots/api#getting-updates) to use HTTPS. To enable such, either run Telepush **behind a reverse proxy** (like [Caddy](https://caddyserver.com/docs/quick-starts/reverse-proxy)), that terminates TLS.\n\nOr, let Telepush itself handle TLS. You'll need a **certificate** for this, so either get one from [Let's Encrypt](https://letsencrypt.org/) or [create a self-signed one](https://www.linode.com/docs/guides/create-a-self-signed-tls-certificate/), then use `-useHttps` in combination with `-certPath` and `-keyPath` pointed to your certificate and private key files respectively.\n\nFor self-signed certificates, you'll need to pass your public key to Telegram's `setWebhook` method in addition, see [these instructions](https://core.telegram.org/bots/webhooks#how-do-i-set-a-webhook-for-either-type).\n\n## 🔧 Configuration options\n\n* `-address` (`string`) – Network address (IPv4) to bind to. Defaults to `127.0.0.1`.\n* `-address6` (`string`) – Network address (IPv6) to bind to. Defaults to `::1`.\n* `-disableIPv6` (`bool`) – Whether to disable listening on both IPv4 and IPv6 interfaces. Defaults to `false`.\n* `-port` (`int`) – TCP port to listen on. Defaults to `8080`.\n* `-proxy` (`string`) – Proxy connection string to be used for long-polling mode. Defaults to none.\n* `-urlSecret` (`string`) – Random suffix to append to your updates route called by Telegram's servers to prevent spam. Defaults to none.\n* `-useHttps` (`bool`) – Whether to use HTTPS. Defaults to `false`.\n* `-certPath` (`string`) – Path of your SSL certificate when using webhook mode with `useHttp`. Default to none.\n* `-keyPath` (`string`) – Path of your private SSL key when using webhook mode with `useHttp`. Default to none.\n* `-dataDir` (`string`) – File system location where to store persistent data. Defaults to `.`.\n* `-inlets` (`string`) – Path to folder containing config-based inlet definitions in YAML format. Defaults to `./inlets.d`.\n* `-blacklist` (`string`) – Path to a line-separated blacklist file containing user IDs (send `/help` to get your id). Defaults to `blacklist.txt`.\n* `-whitelist` (`string`) – Path to a line-separated whitelist file containing user IDs (send `/help` to get your id). Defaults to `whitelist.txt`.\n* `-rateLimit` (`int`) – Maximum number of messages to be delivered to each recipient per hour. Defaults to `100`.\n* `-truncateMsgs` (`bool`) – Truncate too long messages to 4096 characters instead of rejecting them. Defaults to `false`.\n* `-metrics` (`bool`) – Whether to expose [Prometheus](https://prometheus.io) metrics under `/metrics`. Defaults\n  to `false`.\n\nWhen 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`](docker/entrypoint.sh).\n\n### Whitelist vs. Blacklist\n(aka. allow-list vs. block-list)\n\n\u003cimg src=\".github/message-accept.svg\" width=\"600px\"\u003e\n\n## 📥 Inlets\n\nInlets provide a mechanism to pre-process incoming data that comes in a format different from what is normally expected\nby the bot.\n\nThis is especially useful if data is sent by external, third-party applications which you cannot modify.\n\nFor instance, you might want to deliver alerts\nfrom [Prometheus' Alertmanager](https://prometheus.io/docs/alerting/alertmanager/) as Telegram notifications. However,\nAlertmanager's [webhook requests](https://prometheus.io/docs/alerting/configuration/#webhook_config) look much different\nfrom Telepush's default input format. To still make them fit, you can write an [Inlet](/inlets) to massage the data\naccordingly.\n\nTo directly address an inlet, request `https://telepush.dev/api/inlets/\u003cinlet_name\u003e`. Note that `/api/inlets/default` is\nequivalent to `/api/messages`.\n\nFollowing inlets are currently available:\n\n| Name           | Description                                                                                                                                                                    | Status |\n|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|\n| `default`      | Simply passes the request through without any changes                                                                                                                          | ✅      |\n| `alertmanager` | Consumes [Alertmanager webhook requests](https://prometheus.io/docs/alerting/configuration/#webhook_config)                                                                    | ✅      |\n| `grafana`      | Consumes [Grafana webhook requests](https://grafana.com/docs/grafana/latest/alerting/contact-points/notifiers/webhook-notifier/)                                               | ✅      |\n| `webmentionio` | Accepts [Webmention.io](https://webmention.io/) webhook requests to notify about a new Webmention of one of your articles                                                      | ✅      |\n| `stripe`       | Accepts [Stripe webhooks](https://docs.stripe.com/webhooks) to notify about subscription status changes                                                                        | ✅      |\n| `bitbucket`    | Accepts [Bitbucket webhook requests](https://confluence.atlassian.com/bitbucket/tutorial-create-and-trigger-a-webhook-747606432.html) to notify about a pipeline status change | ⏳      |\n\nYou can also **define your own, custom inlets** in YAML. Further documentation on this and about the individual pre-existing inlets is available [here](/inlets).\n\nFor all inlets, the following options are available to be passed as query parameters:\n\n| Parameter               | Description                                                                       |\n|-------------------------|-----------------------------------------------------------------------------------|\n| `disable_link_previews` | Disable a preview version of web links detected in the message. Default: `false`. |\n| `disable_markdown`      | Disable the message being attempted to be parsed as Markdown. Default: `false`.   |\n\nExample: `POST https://telepush.dev/api/inlets/default?disable_markdown=true\u0026disable_link_previews=true`.\n\n## 📊 Metrics\n\nFundamental [Prometheus](https://prometheus) metrics are exposed under `/metrics`, if the `-metrics` flag gets passed.\nThey include:\n\n* `telepush_messages_total{origin=\"string\", type=\"string\"}`\n* `telepush_requests_total{success=\"string\"}`\n\n## 🐞 Troubleshooting\n### Error: `panic: template: pattern matches no files: *.tpl.html`\nWhen 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.\n\n## 📓 License\n\nMIT @ [Ferdinand Mütsch](https://muetsch.io)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuety%2Ftelepush","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmuety%2Ftelepush","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuety%2Ftelepush/lists"}