telegram_bot_engine 0.3.4 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b900a886aae0dea9b6c84313b705eca2c2b435758b6346ecc3ee036cb690647
-  data.tar.gz: df9102d007d39d35dc3c7ef5b00c56b9f432fcf6e1e1a5efcf76830e5a0bc393
+  metadata.gz: d27dbf5fec7cb1c9192332eca34672baea537c79d75ae46df0f6b7cfd13e576a
+  data.tar.gz: 188cc7fa3fb070f8b090f3bcc4b91cddbca17dbbe94354186752c612ba7e0d3d
 SHA512:
-  metadata.gz: 18ac6b1549b2d00871a2f323b537f996d85fb879e8570d342ec7ff290ecbc0943c5f1a009547736ee8569582860ab551620a65919aafba15502a90b64f452b48
-  data.tar.gz: 3f8046235e8b1e15e72a1ef0e82e1a2cdfee2ae8165327823ccb31c4ce5b1b90480e7c66aa5d3efb7d021f5b5584c706fb3aaaabc6b2960a8670b9bffed1019e
+  metadata.gz: fe5cc14a578d95d084f9ca21adee8b201fc3763100d0e32814e15938c31e1a0e8cbb2b25813636457501f0ea6ed021ed6bf308176cf4a8bfcb57be284c901297
+  data.tar.gz: 1e3bac86d76c1a1e871eee18d68b884c41ced5500ad718c5eb9fa98b18a9253dbfd547533825eeebc291c3edf4b88060f55d4b9b6148747607a435b71a9ae604

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+While the gem is pre-1.0, minor bumps may widen the API in backward-compatible ways.
+
+## [0.6.0] - 2026-06-25
+
+### Added
+- **Inbound dispatcher** (`TelegramBotEngine::Dispatch`) — a single Rack endpoint, mounted once at `config.webhook_mount_path`, that routes `POST <mount>/:webhook_id` to the resolved bot's `UpdatesController`. Validates the `X-Telegram-Bot-Api-Secret-Token` header with a constant-time compare (which `telegram-bot` 0.16 does not do).
+- **Webhook registrar** (`TelegramBotEngine::WebhookRegistrar`) — registers/removes each bot's Telegram webhook with a per-bot secret; auto-(un)registers on `Bot` save/destroy when `config.webhook_base_url` is set.
+- Configuration keys: `webhook_base_url`, `webhook_mount_path`, `dispatch_controller`, `auto_register_webhooks`.
+- `webhook_id` (non-secret routing id, carried in the URL) and `webhook_secret` (bearer credential, header only) on `Bot`, with backfill for existing rows.
+
+### Fixed
+- `DeliveryJob` now inherits an engine-local `TelegramBotEngine::ApplicationJob` instead of the host app's `::ApplicationJob`, so the engine installs cleanly into API-only or non-standard hosts that don't define one.
+
+## [0.5.0] - 2026-06-25
+
+### Added
+- **Per-bot subscribers and allowlist** — `Subscription` and `AllowedUser` are scoped to a bot via `bot_id` and the `for_bot` scope; composite and partial-unique indexes keep per-bot and global rows distinct.
+- **Bots admin UI** — index / new / edit, plus a bot column across the subscriptions, events, and allowlist views.
+- Bot-aware `Authorizer` and `SubscriberCommands` so inbound `/start`·`/stop` scope to the bot the update arrived for.
+
+## [0.4.0] - 2026-06-25
+
+### Added
+- **`Bot` model** (`telegram_bot_engine_bots`) — a first-class, persisted Telegram bot identity, with an auto-seeded default-bot anchor for backward compatibility.
+- **Client `Registry`** — a per-bot `Telegram::Bot::Client` cache keyed by bot id (token-rotation safe).
+- **Bot-aware delivery** — `broadcast` and `notify` accept a `bot:` argument and deliver through that bot's own client; omitting `bot:` targets the default bot, preserving existing single-bot behavior.
+
+## [0.3.4] and earlier
+
+Single-bot baseline: subscriber management, authorization, broadcasting, an event log, and an admin UI on top of the [`telegram-bot`](https://github.com/telegram-bot-rb/telegram-bot) gem.
+
+[0.6.0]: https://github.com/landovsky/telegram-bot-channels-gem/releases/tag/v0.6.0
+[0.5.0]: https://github.com/landovsky/telegram-bot-channels-gem/releases/tag/v0.5.0
+[0.4.0]: https://github.com/landovsky/telegram-bot-channels-gem/releases/tag/v0.4.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tomáš Landovský
+
+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

@@ -91,6 +91,8 @@ Rails.application.routes.draw do
 end
 ```
 
+> Running more than one bot? Replace `telegram_webhook` with the engine's inbound dispatcher — see [Multiple bots](#multiple-bots).
+
 ### Set webhook
 
 These rake tasks come from the `telegram-bot` gem:
@@ -183,6 +185,71 @@ TelegramBotEngine::Event.purge_old!
 
 Disable event logging entirely with `config.event_logging = false`.
 
+## Multiple bots
+
+The engine manages many Telegram bots from one Rails host. Everything keyed by a Telegram bot identity — subscribers, allowlist, delivery, and inbound routing — is scoped per bot. Existing single-bot setups keep working unchanged: every call without a `bot:` argument targets the **default bot**, which is seeded automatically from your existing `telegram.bot` credentials (or `TELEGRAM_BOT_TOKEN`).
+
+### The Bot model
+
+Each bot is a persisted `TelegramBotEngine::Bot` record (token, slug, and per-bot webhook credentials). Manage them in the admin UI, a seed, or the console:
+
+```ruby
+TelegramBotEngine::Bot.create!(
+  name: "Support bot",
+  slug: "support",
+  token: Rails.application.credentials.dig(:telegram, :support_bot, :token),
+  active: true
+)
+
+TelegramBotEngine::Bot.default            # the back-compat anchor (auto-seeded on first use)
+TelegramBotEngine::Bot.resolve("support") # look up by slug
+bot.client                                # this bot's memoized Telegram::Bot::Client
+```
+
+`webhook_id` (the non-secret id that appears in the webhook URL) and `webhook_secret` (the bearer credential, sent only in the `X-Telegram-Bot-Api-Secret-Token` header) are generated automatically.
+
+### Bot-aware delivery
+
+```ruby
+support = TelegramBotEngine::Bot.resolve("support")
+
+# Broadcast / notify through a specific bot's own client
+TelegramBotEngine.broadcast("Support is online", bot: support)
+TelegramBotEngine.notify(chat_id: 123456789, text: "Ticket updated", bot: support)
+
+# Omit bot: to target the default bot (unchanged single-bot behavior)
+TelegramBotEngine.broadcast("Deployment complete!")
+```
+
+Subscribers and allowlist entries are scoped per bot: a user who blocks the support bot is deactivated only for that bot, and a per-bot allowlist entry never escalates into a global one.
+
+### Inbound updates for multiple bots
+
+`telegram-bot`'s `telegram_webhook` route serves a single bot. For multiple bots, mount the engine's inbound dispatcher **once** — it resolves the target bot from the URL, validates the secret-token header, then hands off to your `UpdatesController`:
+
+```ruby
+# config/initializers/telegram_bot_engine.rb
+TelegramBotEngine.configure do |config|
+  config.webhook_base_url    = "https://app.example.com"     # host public HTTPS base
+  config.webhook_mount_path  = "/telegram/bot"               # must match the mount below
+  config.dispatch_controller = "TelegramWebhookController"    # your UpdatesController (incl. SubscriberCommands)
+  config.auto_register_webhooks = true                       # (un)register webhooks on Bot save/destroy
+end
+```
+
+```ruby
+# config/routes.rb
+mount TelegramBotEngine::Dispatch, at: "/telegram/bot"
+```
+
+With `webhook_base_url` set and `auto_register_webhooks` enabled, saving an active `Bot` registers its Telegram webhook (`<base_url>/telegram/bot/<webhook_id>`, secret in the header) and deactivating it removes the webhook — no manual `set_webhook` per bot. You can also (re)register explicitly:
+
+```ruby
+TelegramBotEngine::WebhookRegistrar.register(TelegramBotEngine::Bot.resolve("support"))
+```
+
+Unlike `telegram-bot` 0.16, the dispatcher validates the `X-Telegram-Bot-Api-Secret-Token` header (constant-time) on every inbound request, so only Telegram can drive your bots.
+
 ## Requirements
 
 - Ruby >= 3.3.0

data/app/controllers/telegram_bot_engine/admin/allowlist_controller.rb

@@ -6,7 +6,9 @@ module TelegramBotEngine
       before_action :require_database_mode!
 
       def index
-        @allowed_users = AllowedUser.order(:username)
+        @bots = Bot.order(:name)
+        @allowed_users = AllowedUser.includes(:bot).order(:username)
+        @allowed_users = @allowed_users.where(bot_id: params[:bot_id]) if params[:bot_id].present?
       end
 
       def create
@@ -25,7 +27,8 @@ module TelegramBotEngine
       private
 
       def allowed_user_params
-        params.require(:allowed_user).permit(:username, :note)
+        # bot_id blank ⇒ a global allow entry that applies to every bot (docs/0001 §3.5).
+        params.require(:allowed_user).permit(:username, :note, :bot_id)
       end
 
       def require_database_mode!

data/app/controllers/telegram_bot_engine/admin/bots_controller.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  module Admin
+    # CRUD + token rotation + webhook status for bots-as-data (docs/0001 §3.8).
+    class BotsController < BaseController
+      before_action :set_bot, only: %i[edit update destroy rotate_token]
+
+      def index
+        @bots = Bot.order(:name)
+      end
+
+      def new
+        @bot = Bot.new(active: true)
+      end
+
+      def create
+        @bot = Bot.new(create_params)
+        if @bot.save
+          redirect_to admin_bots_path, notice: "Bot \"#{@bot.name}\" created."
+        else
+          flash.now[:alert] = @bot.errors.full_messages.to_sentence
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def edit; end
+
+      def update
+        # Token is never touched here — it is rotated through #rotate_token so a normal
+        # edit can't blank it. See update_params.
+        if @bot.update(update_params)
+          redirect_to admin_bots_path, notice: "Bot \"#{@bot.name}\" updated."
+        else
+          flash.now[:alert] = @bot.errors.full_messages.to_sentence
+          render :edit, status: :unprocessable_entity
+        end
+      end
+
+      def destroy
+        if @bot.default?
+          redirect_to admin_bots_path, alert: "Cannot delete the default bot. Promote another bot to default first."
+        else
+          @bot.destroy
+          redirect_to admin_bots_path, notice: "Bot \"#{@bot.name}\" deleted."
+        end
+      end
+
+      def rotate_token
+        if params[:token].present?
+          @bot.update!(token: params[:token])
+          redirect_to admin_bots_path, notice: "Token rotated for \"#{@bot.name}\"."
+        else
+          redirect_to edit_admin_bot_path(@bot), alert: "Enter a new token to rotate."
+        end
+      end
+
+      private
+
+      def set_bot
+        @bot = Bot.find(params[:id])
+      end
+
+      def create_params
+        params.require(:bot).permit(:name, :slug, :purpose, :token, :active, :default)
+      end
+
+      def update_params
+        params.require(:bot).permit(:name, :slug, :purpose, :active, :default)
+      end
+    end
+  end
+end

data/app/controllers/telegram_bot_engine/admin/dashboard_controller.rb

@@ -4,9 +4,15 @@ module TelegramBotEngine
   module Admin
     class DashboardController < BaseController
       def show
+        @bots = Bot.order(:name)
+        @bot_active_counts = @bots.index_with { |bot| Subscription.active.for_bot(bot).count }
+
         @total_subscriptions = Subscription.count
         @active_subscriptions = Subscription.active.count
         @inactive_subscriptions = @total_subscriptions - @active_subscriptions
+
+        # Legacy single-bot fallback (docs/0001 §3.8): only shown until bots-as-data
+        # rows exist, so pre-multi-bot installs still render their bot identity.
         @bot_username = bot_username
       end
 

data/app/controllers/telegram_bot_engine/admin/events_controller.rb

@@ -20,10 +20,12 @@ module TelegramBotEngine
           return
         end
 
+        @bots = Bot.order(:name)
         @events = Event.recent
         @events = @events.by_type(params[:type]) if params[:type].present?
         @events = @events.by_action(params[:action_name]) if params[:action_name].present?
         @events = @events.by_chat_id(params[:chat_id]) if params[:chat_id].present?
+        @events = @events.by_bot(params[:bot_id]) if params[:bot_id].present?
 
         @total_count = @events.count
         @page = [params[:page].to_i, 1].max
@@ -39,6 +41,7 @@ module TelegramBotEngine
                   id: e.id,
                   event_type: e.event_type,
                   action: e.action,
+                  bot_id: e.bot_id,
                   chat_id: e.chat_id,
                   username: e.username,
                   details: e.details,

data/app/controllers/telegram_bot_engine/admin/subscriptions_controller.rb

@@ -4,7 +4,9 @@ module TelegramBotEngine
   module Admin
     class SubscriptionsController < BaseController
       def index
-        @subscriptions = Subscription.order(created_at: :desc)
+        @bots = Bot.order(:name)
+        @subscriptions = Subscription.includes(:bot).order(created_at: :desc)
+        @subscriptions = @subscriptions.where(bot_id: params[:bot_id]) if params[:bot_id].present?
       end
 
       def update

data/app/jobs/telegram_bot_engine/application_job.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module TelegramBotEngine
+  # Engine-local base job so DeliveryJob doesn't depend on the host app defining a
+  # top-level ::ApplicationJob — an API-only or non-standard host may not have one,
+  # which would otherwise raise NameError when the job is loaded. Inheriting
+  # ActiveJob::Base directly keeps the engine self-contained.
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/telegram_bot_engine/delivery_job.rb

@@ -5,8 +5,14 @@ module TelegramBotEngine
     queue_as :default
     retry_on StandardError, wait: :polynomially_longer, attempts: 3
 
-    def perform(chat_id, text, options = {})
-      Telegram.bot.send_message(
+    # Delivers through the chosen bot's own client (resolved via the registry),
+    # not the process-global Telegram.bot (docs/0001 §3.3). `bot_id` is resolved
+    # to a Bot record; a missing/blank id falls back to the default bot so an
+    # in-flight job enqueued before a rollback still delivers.
+    def perform(bot_id, chat_id, text, options = {})
+      bot = TelegramBotEngine::Bot.find_by(id: bot_id) || TelegramBotEngine::Bot.default
+
+      TelegramBotEngine.client_for(bot).send_message(
         chat_id: chat_id,
         text: text,
         **options.symbolize_keys
@@ -14,18 +20,19 @@ module TelegramBotEngine
 
       TelegramBotEngine::Event.log(
         event_type: "delivery", action: "delivered",
-        chat_id: chat_id,
-        details: { text_preview: text.to_s[0, 100] }
+        chat_id: chat_id, bot_id: bot.id,
+        details: { bot: bot.slug, text_preview: text.to_s[0, 100] }
       )
     rescue Telegram::Bot::Forbidden
-      # User blocked the bot - deactivate subscription
-      TelegramBotEngine::Subscription.where(chat_id: chat_id).update_all(active: false)
+      # User blocked this bot - deactivate only *this bot's* subscription for the chat,
+      # not the chat's subscriptions to other bots (docs/0001 §3.4).
+      TelegramBotEngine::Subscription.for_bot(bot).where(chat_id: chat_id).update_all(active: false)
       Rails.logger.info("[TelegramBotEngine] Deactivated subscription for blocked chat: #{chat_id}")
 
       TelegramBotEngine::Event.log(
         event_type: "delivery", action: "blocked",
-        chat_id: chat_id,
-        details: { text_preview: text.to_s[0, 100] }
+        chat_id: chat_id, bot_id: bot&.id,
+        details: { bot: bot&.slug, text_preview: text.to_s[0, 100] }
       )
     end
   end

data/app/models/telegram_bot_engine/allowed_user.rb

@@ -4,6 +4,12 @@ module TelegramBotEngine
   class AllowedUser < ActiveRecord::Base
     self.table_name = "telegram_bot_engine_allowed_users"
 
-    validates :username, presence: true, uniqueness: true
+    belongs_to :bot, class_name: "TelegramBotEngine::Bot", optional: true
+
+    # Entries authorizing inbound commands for a bot: a nil bot_id is a GLOBAL allow
+    # that applies to every bot, layered with that bot's own entries (docs/0001 §3.5).
+    scope :for_bot, ->(bot) { bot ? where(bot_id: [nil, bot.id]) : all }
+
+    validates :username, presence: true, uniqueness: { scope: :bot_id }
   end
 end

data/app/models/telegram_bot_engine/bot.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module TelegramBotEngine
+  # A Telegram bot identity, persisted as data (docs/0001 §3.1). This is the gem's
+  # next first-class entity beside Subscription/AllowedUser/Event: everything keyed
+  # by a *Telegram bot identity* lives here; only source/channel routing keyed by an
+  # *app source name* stays in the host app.
+  class Bot < ActiveRecord::Base
+    self.table_name = "telegram_bot_engine_bots"
+
+    # `token` becomes encrypted at rest via ActiveRecord Encryption once the host app
+    # provisions encryption keys (docs/0001 §6). Until keys are live it is seeded from
+    # ENV as a plain column; the public API is identical either way. To enable:
+    #   encrypts :token
+
+    # Destroying a bot removes its own subscribers and allow-entries so they can't
+    # leak: nullifying subscriptions would silently fold them into the default
+    # audience, and nullifying allow-entries would escalate a per-bot allow to a
+    # global one. Global entries (nil bot_id) belong to no bot and are untouched.
+    has_many :subscriptions, class_name: "TelegramBotEngine::Subscription", dependent: :destroy
+    has_many :allowed_users, class_name: "TelegramBotEngine::AllowedUser", dependent: :destroy
+
+    scope :active, -> { where(active: true) }
+
+    # Transient: set on the implicit ensure_default! seed so a no-`bot:` broadcast/notify
+    # never triggers a synchronous setWebhook from inside the back-compat path.
+    attr_accessor :skip_webhook_autoregister
+
+    validates :name, presence: true
+    validates :slug, presence: true, uniqueness: true
+    validates :token, presence: true
+    # webhook_secret is the bearer credential — it goes ONLY in the X-Telegram-Bot-Api-Secret-Token
+    # header, never in a URL. webhook_id is the stable, NON-secret routing id that appears in the
+    # webhook URL path (so request/SQL logs never leak the secret). See docs/0001 §3.1/§3.6/§3.7.
+    validates :webhook_secret, presence: true, uniqueness: true
+    validates :webhook_id, presence: true, uniqueness: true
+    # "exactly one row true" has two halves: at most one (demote_other_defaults) and
+    # at least one. Without the second half an admin could uncheck "Default" on the
+    # only default bot, leaving zero defaults — which makes every no-`bot:` broadcast/
+    # notify call (the mandatory back-compat path) raise once Bot.default re-seeds onto
+    # the still-present "default" slug. So refuse to clear the last default.
+    validate :keep_at_least_one_default
+
+    before_validation :ensure_inbound_credentials, on: :create
+    before_save :demote_other_defaults, if: -> { default? && will_save_change_to_default? }
+    after_save :invalidate_client_cache
+    after_save :sync_webhook
+    after_destroy :invalidate_client_cache
+    after_destroy :remove_webhook
+
+    class << self
+      # The default Bot — the back-compat anchor every no-`bot:` call site resolves to.
+      # Seeds one on first use so the host's existing single-bot config keeps working.
+      def default
+        find_by(default: true) || ensure_default!
+      end
+
+      # A Bot by its stable slug handle (e.g. "default", "assistant").
+      def resolve(slug)
+        find_by!(slug: slug)
+      end
+
+      # Idempotently seed the default bot from the host's existing single-bot config/ENV
+      # so nothing breaks on first boot (docs/0001 §4, §6). Safe to call repeatedly.
+      def ensure_default!
+        existing = find_by(default: true)
+        return existing if existing
+
+        bot = new(
+          name: default_seed_name,
+          slug: "default",
+          token: default_seed_token,
+          active: true,
+          default: true
+        )
+        # This is a lazy seed reachable from the back-compat broadcast/notify path; keep it
+        # free of synchronous Telegram I/O. The host registers the default's webhook explicitly
+        # (admin save, or WebhookRegistrar.register(Bot.default)) — see docs/0001 §3.6.
+        bot.skip_webhook_autoregister = true
+        bot.save!
+        bot
+      end
+
+      private
+
+      def default_seed_token
+        ENV["TELEGRAM_BOT_TOKEN"].presence ||
+          telegram_default_config[:token].presence ||
+          raise(ArgumentError, "Cannot seed the default Bot: set ENV['TELEGRAM_BOT_TOKEN'] " \
+                               "or configure telegram.bot in the host app before broadcasting.")
+      end
+
+      def default_seed_name
+        telegram_default_config[:username].presence || "default"
+      end
+
+      def telegram_default_config
+        (Telegram.bots_config[:default] || {}).to_h.symbolize_keys
+      rescue StandardError
+        {}
+      end
+    end
+
+    # The memoized Telegram::Bot::Client for this bot's token, resolved via the registry.
+    def client
+      TelegramBotEngine.client_for(self)
+    end
+
+    private
+
+    def ensure_inbound_credentials
+      self.webhook_secret = SecureRandom.hex(16) if webhook_secret.blank?
+      self.webhook_id = SecureRandom.hex(16) if webhook_id.blank?
+    end
+
+    # "exactly one row true": promoting a bot to default demotes whoever held it.
+    def demote_other_defaults
+      self.class.where(default: true).where.not(id: id).update_all(default: false)
+    end
+
+    # Reject demoting the only default bot — promote another first (closes the UI hole
+    # where unchecking "Default" then deleting would strand the back-compat anchor).
+    def keep_at_least_one_default
+      return if default?            # staying/becoming default is always fine
+      return if new_record?         # creating a non-default bot is fine
+      return unless default_changed? # an edit that doesn't touch `default` is fine
+      return if self.class.where(default: true).where.not(id: id).exists?
+
+      errors.add(:default, "can't be unset on the only default bot — promote another bot to default first")
+    end
+
+    def invalidate_client_cache
+      TelegramBotEngine::Registry.invalidate(self)
+    end
+
+    # Auto-(un)register the Telegram webhook on save (docs/0001 §3.6): an active bot gets a
+    # webhook, an inactive one has it removed. Best-effort — a Telegram hiccup is logged, never
+    # raised, so an admin save can't 500. Gated on a configured base_url so the gem's own suite
+    # (and any host without webhook config) makes no network calls.
+    def sync_webhook
+      return unless webhook_autoregister?
+
+      if active?
+        TelegramBotEngine::WebhookRegistrar.register(self)
+      else
+        TelegramBotEngine::WebhookRegistrar.remove(self)
+      end
+    rescue StandardError => e
+      log_webhook_failure(e)
+    end
+
+    def remove_webhook
+      return unless webhook_autoregister?
+
+      TelegramBotEngine::WebhookRegistrar.remove(self)
+    rescue StandardError => e
+      log_webhook_failure(e)
+    end
+
+    def webhook_autoregister?
+      return false if skip_webhook_autoregister
+
+      TelegramBotEngine.config.webhook_base_url.present? &&
+        TelegramBotEngine.config.auto_register_webhooks
+    end
+
+    def log_webhook_failure(error)
+      TelegramBotEngine::Event.log(
+        event_type: "webhook", action: "register_failed",
+        bot_id: id, details: { bot: slug, error: error.message }
+      )
+      Rails.logger.warn("[TelegramBotEngine] webhook sync failed for bot #{slug}: #{error.message}") if defined?(Rails)
+    end
+  end
+end

data/app/models/telegram_bot_engine/event.rb

@@ -8,22 +8,27 @@ module TelegramBotEngine
     scope :by_type, ->(type) { where(event_type: type) if type.present? }
     scope :by_action, ->(action) { where(action: action) if action.present? }
     scope :by_chat_id, ->(chat_id) { where(chat_id: chat_id) if chat_id.present? }
+    scope :by_bot, ->(bot_id) { where(bot_id: bot_id) if bot_id.present? }
     scope :since, ->(time) { where("created_at >= ?", time) }
 
     validates :event_type, presence: true
     validates :action, presence: true
 
-    def self.log(event_type:, action:, chat_id: nil, username: nil, details: {})
+    def self.log(event_type:, action:, chat_id: nil, username: nil, bot_id: nil, details: {})
       return unless TelegramBotEngine.config.event_logging
       return unless table_exists?
 
-      create!(
+      attrs = {
         event_type: event_type,
         action: action,
         chat_id: chat_id,
         username: username,
         details: details
-      )
+      }
+      # Guard the "code references bot_id before the column is migrated in" boot crash
+      # (docs/0001 §9): only write bot_id once the column actually exists.
+      attrs[:bot_id] = bot_id if column_names.include?("bot_id")
+      create!(attrs)
 
       purge_old_randomly!
     end

data/app/models/telegram_bot_engine/subscription.rb

@@ -4,8 +4,21 @@ module TelegramBotEngine
   class Subscription < ActiveRecord::Base
     self.table_name = "telegram_bot_engine_subscriptions"
 
+    belongs_to :bot, class_name: "TelegramBotEngine::Bot", optional: true
+
     scope :active, -> { where(active: true) }
 
-    validates :chat_id, presence: true, uniqueness: true
+    # The audience for a bot (docs/0001 §3.4). A subscription with a nil bot_id is
+    # treated as belonging to the default bot, so pre-multi-bot subscribers keep
+    # receiving default broadcasts without a data migration (§4 back-compat).
+    scope :for_bot, lambda { |bot|
+      if bot&.default?
+        where(bot_id: [bot.id, nil])
+      else
+        where(bot_id: bot&.id)
+      end
+    }
+
+    validates :chat_id, presence: true, uniqueness: { scope: :bot_id }
   end
 end

data/app/views/telegram_bot_engine/admin/allowlist/index.html.erb

@@ -18,6 +18,18 @@
              class="block w-full rounded-md border-gray-300 shadow-sm focus:ring-blue-500 focus:border-blue-500 text-sm px-3 py-2 border"
              placeholder="e.g. Tom - developer">
     </div>
+    <% if @bots.any? %>
+      <div>
+        <label for="allowed_user_bot_id" class="block text-sm font-medium text-gray-700 mb-1">Scope</label>
+        <select name="allowed_user[bot_id]" id="allowed_user_bot_id"
+                class="block rounded-md border-gray-300 shadow-sm focus:ring-blue-500 focus:border-blue-500 text-sm px-3 py-2 border">
+          <option value="">All bots (global)</option>
+          <% @bots.each do |bot| %>
+            <option value="<%= bot.id %>"><%= bot.name %></option>
+          <% end %>
+        </select>
+      </div>
+    <% end %>
     <div>
       <button type="submit"
               class="inline-flex items-center px-4 py-2 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 focus:ring-2 focus:ring-offset-2 focus:ring-blue-500">
@@ -32,6 +44,7 @@
     <thead class="bg-gray-50">
       <tr>
         <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Username</th>
+        <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Scope</th>
         <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Note</th>
         <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Added</th>
         <th class="px-6 py-3 text-right text-xs font-medium text-gray-500 uppercase tracking-wider">Actions</th>
@@ -43,6 +56,9 @@
           <td class="px-6 py-4 whitespace-nowrap text-sm font-medium text-gray-900">
             @<%= user.username %>
           </td>
+          <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">
+            <%= user.bot&.name || "All bots" %>
+          </td>
           <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">
             <%= user.note || "-" %>
           </td>
@@ -61,7 +77,7 @@
 
       <% if @allowed_users.empty? %>
         <tr>
-          <td colspan="4" class="px-6 py-12 text-center text-sm text-gray-500">
+          <td colspan="5" class="px-6 py-12 text-center text-sm text-gray-500">
             No usernames in the allowlist yet.
           </td>
         </tr>