telegram-support-bot 0.1.06 → 0.1.08

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 443be16da398a9055e09a98aa7a828d887baa3828916f0afa2a509e9e228d1a3
-  data.tar.gz: 959d8dbe4eaeb3660bd688dafa26712575af0b0269d94acbea1e294ce9901af9
+  metadata.gz: d522d11e8602df8c2e6ab13df25de60eb2a376bb4983299092b277ad8ca81c15
+  data.tar.gz: 99739fa0654123c2b2052f9cdd09c78e2336c7cf1bfc4ac45983486e69a47c40
 SHA512:
-  metadata.gz: adfa333fb11bd3f68551a68a7b25f17d09a3840c5326ae65a0872741c326c7956e9d7ccdfe74f33d2e7f017f8e307f9fccd804a744df81004a05a6b460da0f7a
-  data.tar.gz: 75a42d5e219572496a5d3011a1c66373878a1cba685fbf7ff8574e9a00b451002df6b082f998e6d6be77c7b3dd8972d9d9e7faaaa3c486c83feece51724c8294
+  metadata.gz: 799182e98806ac1d0e550a89f37f81d867879b00221bf919f1c3665f20d3bb3a6e0c092dad0c1717d1dce3bc0aa10869be56589b7478e967c58a9dea40885018
+  data.tar.gz: f39e7efa2db2221af245b8641477a03936aa0ef285bcaf40cc21d3de79ece871fbc79c03321aef58602afbf701133b42b310279968f8cb6d07a0768a4de80388

data/.idea/workspace.xml

@@ -6,9 +6,7 @@
   <component name="ChangeListManager">
     <list default="true" id="edf498b0-8552-42f1-846d-0c79d29ff991" name="Changes" comment="">
       <change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/workspace.xml" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/Gemfile" beforeDir="false" afterPath="$PROJECT_DIR$/Gemfile" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/lib/telegram_support_bot/adapters/telegram_bot_adapter.rb" beforeDir="false" afterPath="$PROJECT_DIR$/lib/telegram_support_bot/adapters/telegram_bot_adapter.rb" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/spec/telegram_support_bot/adapters/telegram_bot_adapter_spec.rb" beforeDir="false" afterPath="$PROJECT_DIR$/spec/telegram_support_bot/adapters/telegram_bot_adapter_spec.rb" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
@@ -39,30 +37,30 @@
     <option name="hideEmptyMiddlePackages" value="true" />
     <option name="showLibraryContents" value="true" />
   </component>
-  <component name="PropertiesComponent"><![CDATA[{
-  "keyToString": {
-    "DefaultRubyCreateTestTemplate": "Minitest Spec",
-    "RSpec.Unnamed.executor": "Run",
-    "Ruby.scratch_61.executor": "Run",
-    "RunOnceActivity.OpenProjectViewOnStart": "true",
-    "RunOnceActivity.ShowReadmeOnStart": "true",
-    "git-widget-placeholder": "main",
-    "last_opened_file_path": "/home/max/code/gems/telegram_support_bot",
-    "node.js.detected.package.eslint": "true",
-    "node.js.detected.package.tslint": "true",
-    "node.js.selected.package.eslint": "(autodetect)",
-    "node.js.selected.package.tslint": "(autodetect)",
-    "nodejs_package_manager_path": "npm",
-    "ruby.structure.view.model.defaults.configured": "true",
-    "settings.editor.selected.configurable": "org.jetbrains.plugins.ruby.settings.RubyActiveModuleSdkConfigurable",
-    "vue.rearranger.settings.migration": "true"
+  <component name="PropertiesComponent">{
+  &quot;keyToString&quot;: {
+    &quot;DefaultRubyCreateTestTemplate&quot;: &quot;Minitest Spec&quot;,
+    &quot;RSpec.Unnamed.executor&quot;: &quot;Run&quot;,
+    &quot;Ruby.scratch_61.executor&quot;: &quot;Run&quot;,
+    &quot;RunOnceActivity.OpenProjectViewOnStart&quot;: &quot;true&quot;,
+    &quot;RunOnceActivity.ShowReadmeOnStart&quot;: &quot;true&quot;,
+    &quot;git-widget-placeholder&quot;: &quot;main&quot;,
+    &quot;last_opened_file_path&quot;: &quot;/home/max/code/tg-sample&quot;,
+    &quot;node.js.detected.package.eslint&quot;: &quot;true&quot;,
+    &quot;node.js.detected.package.tslint&quot;: &quot;true&quot;,
+    &quot;node.js.selected.package.eslint&quot;: &quot;(autodetect)&quot;,
+    &quot;node.js.selected.package.tslint&quot;: &quot;(autodetect)&quot;,
+    &quot;nodejs_package_manager_path&quot;: &quot;npm&quot;,
+    &quot;ruby.structure.view.model.defaults.configured&quot;: &quot;true&quot;,
+    &quot;settings.editor.selected.configurable&quot;: &quot;org.jetbrains.plugins.ruby.settings.RubyActiveModuleSdkConfigurable&quot;,
+    &quot;vue.rearranger.settings.migration&quot;: &quot;true&quot;
   },
-  "keyToStringList": {
-    "com.intellij.ide.scratch.ScratchImplUtil$2/New Scratch File": [
-      "ruby"
+  &quot;keyToStringList&quot;: {
+    &quot;com.intellij.ide.scratch.ScratchImplUtil$2/New Scratch File&quot;: [
+      &quot;ruby&quot;
     ]
   }
-}]]></component>
+}</component>
   <component name="RecentsManager">
     <key name="CopyFile.RECENT_KEYS">
       <recent name="$PROJECT_DIR$/spec/telegram_support_bot/adapters" />
@@ -139,6 +137,10 @@
       <updated>1708600824931</updated>
       <workItem from="1708600827139" duration="10157000" />
       <workItem from="1708784534887" duration="682000" />
+      <workItem from="1708944130416" duration="99000" />
+      <workItem from="1708944249622" duration="627000" />
+      <workItem from="1708949675518" duration="80000" />
+      <workItem from="1708951183744" duration="310000" />
     </task>
     <servers />
   </component>

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.08] - 2026-02-13
+
+### Added
+- Optional one-time contact sharing flow for user identification:
+  `request_contact_on_start`, `require_contact_for_support`, custom contact messages, and
+  `on_contact_received` callback.
+- In-memory user profile storage and lookup via `TelegramSupportBot.user_profile(chat_id)`.
+- Configurable state-store backend with Redis support for multi-pod deployments
+  (`state_store`, `state_store_options`, and state TTL settings).
+
+### Changed
+- Support reply routing now uses internal message mapping first, with `forward_from` as fallback.
+  This removes the dependency on user forwarding privacy settings for normal reply flows.
+- Message processing no longer relies on shared `@message_chat_id`, reducing thread-safety risks.
+
+## [0.1.07] - 2026-02-13
+
+### Added
+- Mirroring of `message_reaction` updates between support chat and user chats.
+- Message mapping storage (`message_map` and `reverse_message_map`) to correlate forwarded/replied messages for reaction sync.
+- Adapter API method `set_message_reaction` with implementations for both supported adapters.
+- Test coverage for reaction handling and adapter reaction calls.
+- Local polling helper script for development testing without Rails (`script/dev_poll.rb`).
+- README documentation for local development testing workflow.
+
+### Fixed
+- Local polling script now uses the proper polling call for `telegram-bot` gem (`get_updates`) and supports multiple client styles.
+- Reaction mapping now correctly handles wrapped Telegram API responses (`{ "ok": true, "result": ... }`).
+- Reaction mirroring now gracefully handles `REACTIONS_TOO_MANY` by retrying with a single reaction instead of crashing.
+- Reaction mapping lookup now tolerates chat/message ID type mismatches (string vs integer).
+- Added optional reaction-flow debug logs via `TSB_DEBUG=1`.
+- Support-chat reaction mirroring now also handles `message_reaction_count` updates (anonymous reaction counts).

data/README.md

@@ -43,6 +43,15 @@ TelegramSupportBot.configure do |config|
   config.adapter_options = { token: 'YOUR_TELEGRAM_BOT_TOKEN' }
   config.support_chat_id = 'YOUR_SUPPORT_CHAT_ID'
   config.welcome_message = 'Hi! How can we help you?'
+  # Optional: ask users to share their phone once for account lookup.
+  config.request_contact_on_start = true
+  # Optional: block forwarding until contact is shared.
+  config.require_contact_for_support = false
+  # Optional callback to persist/lookup user profile in your app.
+  config.on_contact_received = ->(profile) { YourUserMatcher.sync_from_telegram(profile) }
+  # Recommended in Kubernetes/multi-pod setup:
+  # config.state_store = :redis
+  # config.state_store_options = { url: ENV.fetch('REDIS_URL'), namespace: 'telegram_support_bot' }
 end
 ```
 
@@ -115,13 +124,107 @@ end
 Implement custom adapters by inheriting from `TelegramSupportBot::Adapter::Base` and defining
 message sending and forwarding methods.
 
+## User Identification With Phone Sharing
+
+If you want support agents to identify users quickly in your CRM, you can request phone sharing once:
+
+```ruby
+TelegramSupportBot.configure do |config|
+  config.request_contact_on_start = true
+  config.require_contact_for_support = false
+  config.contact_request_message = 'Please share your phone number so we can identify your account.'
+  config.contact_received_message = 'Thanks! We have saved your phone number.'
+  config.on_contact_received = ->(profile) do
+    # profile keys:
+    # :chat_id, :user_id, :phone_number, :first_name, :last_name, :username, :language_code
+    UserIdentitySync.call(profile)
+  end
+end
+```
+
+If you set `require_contact_for_support = true`, the bot will ask for contact and will not forward
+other user messages until contact is shared.
+
+Support replies are routed by internal message mapping, so users do not need to change Telegram
+forwarding privacy settings to receive replies.
+
+## State Storage (Single Pod vs Multi-Pod)
+
+By default, runtime state is stored in-memory (`state_store = :memory`). This is fine for local
+development or a single process.
+
+For Kubernetes / multiple pods, configure Redis so message mappings, reaction state, and user
+profiles are shared:
+
+```ruby
+TelegramSupportBot.configure do |config|
+  config.state_store = :redis
+  config.state_store_options = {
+    url: ENV.fetch('REDIS_URL'),
+    namespace: 'telegram_support_bot'
+  }
+  # Optional TTL tuning:
+  # config.mapping_ttl_seconds = 30 * 24 * 60 * 60
+  # config.reaction_count_ttl_seconds = 7 * 24 * 60 * 60
+  # config.user_profile_ttl_seconds = nil
+end
+```
 
 ## Development
 
 - Run `bin/setup` to install dependencies.
 - Use `rake spec` for tests and `bin/console` for an interactive prompt.
 - To install locally, use `bundle exec rake install`.
-- For releases, update `version.rb`, and run `bundle exec rake release`.
+- For releases, update `lib/telegram_support_bot/version.rb` and `CHANGELOG.md`, then run `bundle exec rake release`.
+
+### Local Testing Without Rails (Polling)
+
+You can run the bot locally without a Rails app by using the included script:
+
+Prerequisites:
+- Add the bot as an **administrator** in the support chat if you want support-side reactions to be delivered as updates.
+- Bots can set only one reaction per message via Bot API, so only one mirrored reaction is applied when multiple are present.
+
+1. Export required environment variables:
+
+```bash
+export TELEGRAM_BOT_TOKEN=your_bot_token
+export SUPPORT_CHAT_ID=your_support_chat_id
+# optional; defaults to telegram_bot
+export TSB_ADAPTER=telegram_bot
+# optional; used by telegram_bot adapter
+export TELEGRAM_BOT_USERNAME=your_bot_username
+```
+
+2. Disable webhook mode for that bot token (polling and webhooks cannot be used together):
+
+```bash
+curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/deleteWebhook" > /dev/null
+```
+
+3. Start the local poller:
+
+```bash
+bundle exec ruby script/dev_poll.rb
+```
+
+4. In Telegram, verify:
+- user message is forwarded to support chat
+- support reply is sent back to user
+- reactions are mirrored in both directions
+
+If you want to test with `telegram_bot_ruby` adapter, set `TSB_ADAPTER=telegram_bot_ruby` and add
+the `telegram-bot-ruby` gem in your environment.
+
+### Switch Back To Webhook Mode
+
+After polling tests, set your webhook again:
+
+```bash
+curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://YOUR_PUBLIC_HOST/telegram/webhook","allowed_updates":["message","message_reaction","message_reaction_count","my_chat_member"]}'
+```
 
 ## Contributing
 

data/lib/telegram_support_bot/adapter_factory.rb

@@ -8,15 +8,24 @@ module TelegramSupportBot
     }.freeze
 
     def self.build(adapter_specification, adapter_options = {})
+      adapter_options ||= {}
       case adapter_specification
       when Symbol
-        adapter_class = ADAPTERS[adapter_specification].constantize
-        adapter_class.new(adapter_options)
+        class_name = ADAPTERS[adapter_specification]
+        raise ArgumentError, "Unsupported adapter specification: #{adapter_specification}" unless class_name
+
+        adapter_class = constantize(class_name)
+        adapter_class.new(**adapter_options)
       when Class
-        adapter_specification.new(adapter_options)
+        adapter_specification.new(**adapter_options)
       else
         raise ArgumentError, "Unsupported adapter specification: #{adapter_specification}"
       end
     end
+
+    def self.constantize(class_name)
+      class_name.split('::').reject(&:empty?).inject(Object) { |namespace, constant| namespace.const_get(constant) }
+    end
+    private_class_method :constantize
   end
 end

data/lib/telegram_support_bot/adapters/base.rb

@@ -35,6 +35,10 @@ module TelegramSupportBot
         # forward messages to the support chat
       end
 
+      def set_message_reaction(chat_id:, message_id:, reaction:, **options)
+        # set reaction to a message
+      end
+
       def on_message(&block)
         # Implementation to register a block to be called on new messages
       end

data/lib/telegram_support_bot/adapters/telegram_bot.rb

@@ -50,6 +50,15 @@ module TelegramSupportBot
           message_id:   message_id
         )
       end
+
+      def set_message_reaction(chat_id:, message_id:, reaction:, **options)
+        @bot.set_message_reaction(
+          chat_id:    chat_id,
+          message_id: message_id,
+          reaction:   reaction,
+          **options
+        )
+      end
     end
   end
 end

data/lib/telegram_support_bot/adapters/telegram_bot_ruby.rb

@@ -43,6 +43,10 @@ module TelegramSupportBot
       def forward_message(from_chat_id:, chat_id:, message_id:)
         bot.api.forward_message(chat_id: chat_id, from_chat_id: from_chat_id, message_id: message_id)
       end
+
+      def set_message_reaction(chat_id:, message_id:, reaction:, **options)
+        bot.api.set_message_reaction(chat_id: chat_id, message_id: message_id, reaction: reaction, **options)
+      end
     end
   end
 end

data/lib/telegram_support_bot/configuration.rb

@@ -3,7 +3,11 @@
 module TelegramSupportBot
   class Configuration
     attr_accessor :adapter, :adapter_options, :support_chat_id, :welcome_message,
-                  :auto_away_message, :auto_away_interval, :ignore_unknown_commands
+                  :auto_away_message, :auto_away_interval, :ignore_unknown_commands,
+                  :request_contact_on_start, :require_contact_for_support, :contact_request_message,
+                  :contact_received_message, :contact_invalid_message, :on_contact_received,
+                  :state_store, :state_store_options, :mapping_ttl_seconds,
+                  :reaction_count_ttl_seconds, :user_profile_ttl_seconds
 
     def initialize
       @adapter                 = :telegram_bot
@@ -12,6 +16,17 @@ module TelegramSupportBot
       @ignore_unknown_commands = true
       @auto_away_interval      = 10 # seconds
       @auto_away_message       = 'We are sorry, all operators are busy at the moment. Please wait'
+      @request_contact_on_start = false
+      @require_contact_for_support = false
+      @contact_request_message = 'Please share your phone number so we can quickly identify your account.'
+      @contact_received_message = 'Thanks! We have saved your phone number.'
+      @contact_invalid_message = 'Please use the button below to share your own phone number.'
+      @on_contact_received = nil
+      @state_store = :memory
+      @state_store_options = {}
+      @mapping_ttl_seconds = 30 * 24 * 60 * 60
+      @reaction_count_ttl_seconds = 7 * 24 * 60 * 60
+      @user_profile_ttl_seconds = nil
     end
   end
 end

data/lib/telegram_support_bot/state_store.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module TelegramSupportBot
+  module StateStore
+    class MapProxy
+      def initialize(get_proc:, set_proc:, clear_proc:, size_proc:)
+        @get_proc = get_proc
+        @set_proc = set_proc
+        @clear_proc = clear_proc
+        @size_proc = size_proc
+      end
+
+      def [](key)
+        @get_proc.call(key)
+      end
+
+      def []=(key, value)
+        @set_proc.call(key, value)
+      end
+
+      def clear
+        @clear_proc.call
+      end
+
+      def size
+        @size_proc.call
+      end
+    end
+
+    def self.build(configuration)
+      backend = configuration.state_store.to_sym
+      options = configuration.state_store_options || {}
+
+      case backend
+      when :memory
+        StateStores::Memory.new(
+          mapping_ttl_seconds: configuration.mapping_ttl_seconds,
+          reaction_count_ttl_seconds: configuration.reaction_count_ttl_seconds,
+          user_profile_ttl_seconds: configuration.user_profile_ttl_seconds,
+          **options
+        )
+      when :redis
+        require_relative 'state_stores/redis'
+        StateStores::Redis.new(
+          mapping_ttl_seconds: configuration.mapping_ttl_seconds,
+          reaction_count_ttl_seconds: configuration.reaction_count_ttl_seconds,
+          user_profile_ttl_seconds: configuration.user_profile_ttl_seconds,
+          **options
+        )
+      else
+        raise ArgumentError, "Unsupported state store backend: #{backend}"
+      end
+    end
+  end
+end
+
+require_relative 'state_stores/memory'

data/lib/telegram_support_bot/state_stores/memory.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'monitor'
+
+module TelegramSupportBot
+  module StateStores
+    class Memory
+      def initialize(**_options)
+        @monitor = Monitor.new
+        @message_map = {}
+        @reverse_message_map = {}
+        @reaction_count_state = {}
+        @user_profiles = {}
+      end
+
+      def message_map
+        @message_map_proxy ||= StateStore::MapProxy.new(
+          get_proc:   ->(key) { get_message_mapping(key) },
+          set_proc:   ->(key, value) { set_message_mapping(key, value) },
+          clear_proc: -> { clear_message_mappings },
+          size_proc:  -> { message_mappings_size }
+        )
+      end
+
+      def reverse_message_map
+        @reverse_map_proxy ||= StateStore::MapProxy.new(
+          get_proc:   ->(key) { get_reverse_mapping(key) },
+          set_proc:   ->(key, value) { set_reverse_mapping(key, value) },
+          clear_proc: -> { clear_reverse_mappings },
+          size_proc:  -> { reverse_mappings_size }
+        )
+      end
+
+      def reaction_count_state
+        @reaction_state_proxy ||= StateStore::MapProxy.new(
+          get_proc:   ->(key) { get_reaction_count(key) },
+          set_proc:   ->(key, value) { set_reaction_count(key, value) },
+          clear_proc: -> { clear_reaction_counts },
+          size_proc:  -> { reaction_counts_size }
+        )
+      end
+
+      def user_profiles
+        @user_profiles_proxy ||= StateStore::MapProxy.new(
+          get_proc:   ->(key) { get_user_profile(key) },
+          set_proc:   ->(key, value) { set_user_profile(key, value) },
+          clear_proc: -> { clear_user_profiles },
+          size_proc:  -> { user_profiles_size }
+        )
+      end
+
+      def get_message_mapping(key)
+        synchronize { @message_map[normalize_key(key)] }
+      end
+
+      def set_message_mapping(key, value)
+        synchronize { @message_map[normalize_key(key)] = value }
+      end
+
+      def clear_message_mappings
+        synchronize { @message_map.clear }
+      end
+
+      def message_mappings_size
+        synchronize { @message_map.size }
+      end
+
+      def get_reverse_mapping(key)
+        synchronize { @reverse_message_map[normalize_key(key)] }
+      end
+
+      def set_reverse_mapping(key, value)
+        synchronize { @reverse_message_map[normalize_key(key)] = value }
+      end
+
+      def clear_reverse_mappings
+        synchronize { @reverse_message_map.clear }
+      end
+
+      def reverse_mappings_size
+        synchronize { @reverse_message_map.size }
+      end
+
+      def get_reaction_count(key)
+        synchronize { @reaction_count_state[normalize_key(key)] }
+      end
+
+      def set_reaction_count(key, value)
+        synchronize { @reaction_count_state[normalize_key(key)] = value }
+      end
+
+      def clear_reaction_counts
+        synchronize { @reaction_count_state.clear }
+      end
+
+      def reaction_counts_size
+        synchronize { @reaction_count_state.size }
+      end
+
+      def get_user_profile(key)
+        synchronize { @user_profiles[normalize_key(key)] }
+      end
+
+      def set_user_profile(key, value)
+        synchronize { @user_profiles[normalize_key(key)] = value }
+      end
+
+      def clear_user_profiles
+        synchronize { @user_profiles.clear }
+      end
+
+      def user_profiles_size
+        synchronize { @user_profiles.size }
+      end
+
+      private
+
+      def synchronize(&block)
+        @monitor.synchronize(&block)
+      end
+
+      def normalize_key(key)
+        key.to_s
+      end
+    end
+  end
+end