noticed-telegram 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 818bb29f28c5721aa2464aa330b78da51bb99015da403fc14d0688b73d2878f2
+  data.tar.gz: 5f290a6330badbe90b0747bc36f1b04bd1b6cfedd416ddec38983eb064bc018c
+SHA512:
+  metadata.gz: '084477fff5171b9a82b34d020dacba55745955646240aac56518f7168f256a293000b1b3aeaf8cdcdb71a23981d417d2c4675160fa940d275b93fde93ca5a8aa'
+  data.tar.gz: c10396e7c40435ffde0770cef47ad4b94c5327ef01a22c865f9d5ca304d8a8f6ac5a07fc4cb41691a3a015816169672cbeb6f2933356dddd04711540f81d4d65

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-14
+
+- `deliver_by :telegram` and `bulk_deliver_by :telegram` for Noticed 2.x and 3.x.
+- Supports forum topics (`message_thread_id`), formatting, link previews,
+  silent sends, inline keyboards, and any other `sendMessage` field via `json`.
+- A send counts only when Telegram returns 2xx and `"ok": true`; otherwise
+  `Noticed::ResponseUnsuccessful` is raised.
+- The bot token is kept out of logs and error messages.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Yaroslav Shmarov
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,107 @@
+# noticed-telegram
+
+Telegram delivery methods for [Noticed](https://github.com/excid3/noticed).
+
+- `bulk_deliver_by :telegram` sends **one message per event**, to a group, a forum topic, or a channel. Use it for team alerts like "new signup" or "payment failed".
+- `deliver_by :telegram` sends **one message per recipient**, to each user's private chat with your bot.
+
+Both call the Bot API's [`sendMessage`](https://core.telegram.org/bots/api#sendmessage). The bot token is part of Telegram's URL, so this gem keeps it out of Noticed's logs and out of `Noticed::ResponseUnsuccessful` messages, which usually end up in your error tracker.
+
+Works with Noticed 2.x and 3.x on Rails 7.1+.
+
+## Install
+
+```ruby
+# Gemfile
+gem "noticed-telegram"
+```
+
+Nothing else: once the gem is in the bundle, Noticed finds `:telegram`.
+
+## Set up a bot
+
+1. Message [@BotFather](https://t.me/botfather), send `/newbot`, and copy the token.
+2. Store it in credentials, e.g. `telegram: { bot_token: "..." }`.
+3. Find the chat ID:
+   - **Group or forum:** add the bot to the group, send a message there, then open `https://api.telegram.org/bot<TOKEN>/getUpdates` and read `message.chat.id` (it starts with `-100`). In a forum topic, `message.message_thread_id` is the topic ID.
+   - **Channel:** add the bot as an admin and use `@channelname` or the numeric `-100…` ID.
+   - **A user:** the user must message your bot first; their `chat.id` then appears in `getUpdates` (or in your webhook). Store it on the user.
+
+## Team alerts: `bulk_deliver_by :telegram`
+
+```ruby
+class NewSignupNotifier < Noticed::Event
+  bulk_deliver_by :telegram do |config|
+    config.bot_token = Rails.application.credentials.dig(:telegram, :bot_token)
+    config.chat_id = "-1001234567890"
+    config.message_thread_id = 42 # optional: post into one forum topic
+    config.text = -> { "New signup: #{params[:user].email}" }
+  end
+end
+
+NewSignupNotifier.with(user: user).deliver
+```
+
+Procs run in the context of the event, so `params` and `record` are available.
+
+## Per-user messages: `deliver_by :telegram`
+
+```ruby
+class CommentNotifier < Noticed::Event
+  deliver_by :telegram do |config|
+    config.bot_token = Rails.application.credentials.dig(:telegram, :bot_token)
+    config.chat_id = -> { recipient.telegram_chat_id }
+    config.text = -> { "<b>#{params[:comment].author_name}</b> replied to you" }
+    config.parse_mode = "HTML"
+    config.if = -> { recipient.telegram_chat_id.present? }
+  end
+end
+```
+
+Procs run in the context of the notification, so `recipient` is available too.
+
+## Options
+
+| Option | Required | |
+|---|---|---|
+| `bot_token` | yes | From @BotFather. |
+| `chat_id` | yes | Numeric ID or `@channelname`. |
+| `text` | | The message. Telegram rejects a send without text, so set this or put `text` in `json`. |
+| `message_thread_id` | | Forum topic to post into. |
+| `parse_mode` | | `"HTML"`, `"MarkdownV2"`, or `"Markdown"`. Escape user input to match. |
+| `link_preview_options` | | e.g. `{ is_disabled: true }`. |
+| `disable_web_page_preview` | | Older form of the above; Telegram still accepts it. |
+| `disable_notification` | | `true` sends silently. |
+| `protect_content` | | `true` blocks forwarding and saving. |
+| `entities`, `reply_markup` | | Passed through as given. |
+| `json` | | A hash merged over everything above, for any other `sendMessage` field. |
+| `raise_if_not_ok` | | Defaults to `true`. Set `false` to ignore failed sends instead of raising. |
+
+Every option accepts a value, a proc, or a symbol naming a method on the notifier, as in the rest of Noticed. Noticed's own `if`, `unless`, `wait`, and `queue` options work as usual.
+
+## Failures
+
+A send counts as delivered only when Telegram answers with a 2xx status **and** `"ok": true`. Anything else raises `Noticed::ResponseUnsuccessful`, with Telegram's error description in the message and the token shown as `bot[FILTERED]`. Common causes:
+
+- `403 Forbidden: bot was blocked by the user`: the user stopped the bot. Clear their stored chat ID.
+- `400 Bad Request: chat not found`: wrong ID, or the user never messaged the bot.
+- `429 Too Many Requests`: Telegram's [rate limits](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits-how-do-i-avoid-this). Retry with backoff:
+
+```ruby
+# config/initializers/noticed.rb
+ActiveSupport.on_load(:noticed_delivery_methods_telegram) do
+  retry_on Noticed::ResponseUnsuccessful, wait: :polynomially_longer, attempts: 5
+end
+
+ActiveSupport.on_load(:noticed_bulk_delivery_methods_telegram) do
+  retry_on Noticed::ResponseUnsuccessful, wait: :polynomially_longer, attempts: 5
+end
+```
+
+## Why a separate gem
+
+This was [proposed to Noticed](https://github.com/excid3/noticed/pull/568). The maintainer preferred that Telegram support live in its own gem, maintained by someone who uses Telegram.
+
+## License
+
+MIT

data/SECURITY.md

@@ -0,0 +1,8 @@
+# Security policy
+
+Security fixes are released for the latest version.
+
+Please do not open a public issue for a vulnerability. Use
+[GitHub private vulnerability reporting](https://github.com/yshmarov/noticed-telegram/security/advisories/new)
+with the affected version, a minimal reproduction, and the impact. Never include
+a real bot token.

data/lib/noticed/bulk_delivery_methods/telegram.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Noticed
+  module BulkDeliveryMethods
+    # One message per event, e.g. to a team group chat or a channel.
+    class Telegram < BulkDeliveryMethod
+      include Noticed::Telegram::Api
+    end
+  end
+end
+
+ActiveSupport.run_load_hooks :noticed_bulk_delivery_methods_telegram, Noticed::BulkDeliveryMethods::Telegram

data/lib/noticed/delivery_methods/telegram.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Noticed
+  module DeliveryMethods
+    # One message per recipient, e.g. to each user's private chat with your bot.
+    class Telegram < DeliveryMethod
+      include Noticed::Telegram::Api
+    end
+  end
+end
+
+ActiveSupport.run_load_hooks :noticed_delivery_methods_telegram, Noticed::DeliveryMethods::Telegram

data/lib/noticed/telegram/api.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+
+module Noticed
+  module Telegram
+    # sendMessage over the Telegram Bot API, shared by the individual and bulk
+    # delivery methods.
+    #
+    # The request is made here rather than with Noticed's `post_request`
+    # because the bot token is part of the URL path, and `post_request` puts
+    # the full URL into the ResponseUnsuccessful message (and so into error
+    # trackers). Every URL this module logs or raises with has the token
+    # replaced by [FILTERED].
+    module Api
+      API_HOST = 'api.telegram.org'
+      REDACTED_URL = "https://#{API_HOST}/bot[FILTERED]/sendMessage".freeze
+
+      PASSTHROUGH_OPTIONS = %i[
+        text
+        message_thread_id
+        parse_mode
+        entities
+        link_preview_options
+        disable_web_page_preview
+        disable_notification
+        protect_content
+        reply_markup
+      ].freeze
+
+      def self.included(base)
+        base.required_options :bot_token, :chat_id
+      end
+
+      def deliver
+        payload = json_payload
+        response = send_message(payload)
+
+        raise ResponseUnsuccessful.new(response, REDACTED_URL, { json: payload }) if raise_if_not_ok? && !ok?(response)
+
+        response
+      end
+
+      def json_payload
+        payload = { chat_id: evaluate_option(:chat_id) }
+        PASSTHROUGH_OPTIONS.each do |option|
+          payload[option] = evaluate_option(option) if config.key?(option)
+        end
+
+        return payload unless config.key?(:json)
+
+        custom = evaluate_option(:json)
+        custom.is_a?(Hash) ? payload.merge(custom.symbolize_keys) : custom
+      end
+
+      private
+
+      def send_message(payload)
+        logger.debug("POST #{REDACTED_URL}")
+
+        response = Net::HTTP.start(API_HOST, 443, use_ssl: true, open_timeout: 5, read_timeout: 15) do |http|
+          http.post("/bot#{evaluate_option(:bot_token)}/sendMessage", payload.to_json,
+                    'Content-Type' => 'application/json')
+        end
+
+        logger.debug("Response: #{response.code}")
+        response
+      end
+
+      # Telegram answers {"ok": true, ...} on success and {"ok": false, ...}
+      # with a 4xx status on failure, so a send counts only when both agree.
+      def ok?(response)
+        response.is_a?(Net::HTTPSuccess) && JSON.parse(response.body.to_s)['ok'] == true
+      rescue JSON::ParserError
+        false
+      end
+
+      def raise_if_not_ok?
+        config.key?(:raise_if_not_ok) ? evaluate_option(:raise_if_not_ok) : true
+      end
+    end
+  end
+end

data/lib/noticed/telegram/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Noticed
+  module Telegram
+    VERSION = '0.1.0'
+  end
+end

data/lib/noticed/telegram.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'noticed'
+require 'noticed/telegram/version'
+
+# Noticed resolves `deliver_by :telegram` to Noticed::DeliveryMethods::Telegram
+# at delivery time. The classes are autoloaded rather than required because
+# their superclasses inherit from Noticed::ApplicationJob, which only exists
+# once the host app's autoloaders are running.
+module Noticed
+  module Telegram
+    autoload :Api, 'noticed/telegram/api'
+  end
+
+  module DeliveryMethods
+    autoload :Telegram, 'noticed/delivery_methods/telegram'
+  end
+
+  module BulkDeliveryMethods
+    autoload :Telegram, 'noticed/bulk_delivery_methods/telegram'
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: noticed-telegram
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yaroslav Shmarov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: noticed
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+description: |
+  Send Noticed notifications through the Telegram Bot API: one message per
+  recipient with `deliver_by :telegram`, or one message to a group, forum
+  topic, or channel with `bulk_deliver_by :telegram`. The bot token is kept
+  out of logs and error messages.
+email:
+- yaroslav.shmarov@clickfunnels.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- SECURITY.md
+- lib/noticed/bulk_delivery_methods/telegram.rb
+- lib/noticed/delivery_methods/telegram.rb
+- lib/noticed/telegram.rb
+- lib/noticed/telegram/api.rb
+- lib/noticed/telegram/version.rb
+homepage: https://github.com/yshmarov/noticed-telegram
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yshmarov/noticed-telegram
+  source_code_uri: https://github.com/yshmarov/noticed-telegram
+  changelog_uri: https://github.com/yshmarov/noticed-telegram/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/yshmarov/noticed-telegram/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'Telegram delivery methods for Noticed: deliver_by :telegram and bulk_deliver_by
+  :telegram.'
+test_files: []