telegram-support-bot 0.1.07 → 0.1.08

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0dba7130ca446bc645510735687aa8501f31a6671cfb63fc29e7eb5e535c957
-  data.tar.gz: 3fa484d6c00969af671bdce6e964fd1484fce7ff96496aac9e92c3cd7e694dba
+  metadata.gz: d522d11e8602df8c2e6ab13df25de60eb2a376bb4983299092b277ad8ca81c15
+  data.tar.gz: 99739fa0654123c2b2052f9cdd09c78e2336c7cf1bfc4ac45983486e69a47c40
 SHA512:
-  metadata.gz: c23fe383ec0166b10ab54edf9b536a83bc8973afbd9d373f04e9d281def477682406fd7b665f31c52b622b6e52ab33e47a7478c2193bc28e0a1a9139b06da840
-  data.tar.gz: ede12ddc03a8cb4cf213507d5fa8e35faeed2bb78d5c9dc76dfa1978901164130842f055b8b66fa604b2e9d3cf3a43881752ece10a94dd2063f09a92ebce19cd
+  metadata.gz: 799182e98806ac1d0e550a89f37f81d867879b00221bf919f1c3665f20d3bb3a6e0c092dad0c1717d1dce3bc0aa10869be56589b7478e967c58a9dea40885018
+  data.tar.gz: f39e7efa2db2221af245b8641477a03936aa0ef285bcaf40cc21d3de79ece871fbc79c03321aef58602afbf701133b42b310279968f8cb6d07a0768a4de80388

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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

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,28 +124,51 @@ end
 Implement custom adapters by inheriting from `TelegramSupportBot::Adapter::Base` and defining
 message sending and forwarding methods.
 
-## Handling User Privacy Settings for Message Forwarding
+## User Identification With Phone Sharing
 
-Due to Telegram's privacy settings, users may have restricted the ability for bots to forward their
-messages with identifiable information. This restriction impacts the `forward_from` key, necessary
-for the bot to recognize and reply to users directly. To ensure seamless communication and support,
-we recommend including instructions in your bot's welcome message, asking users to allow message
-forwarding from your bot. Here's an example of how you can phrase this request:
+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
 ```
-Please mind, that your privacy settings might prevent the bot from sending you the reply from the support team. Please consider adding this bot to your allow-list for forwarding. Here’s how you can do it:
-  
-1. Go to Settings in your Telegram app.
-2. Tap on 'Privacy and Security'.
-3. Scroll to 'Forwarded Messages'.
-4. Add this bot to the list of exceptions by selecting 'Always Allow' for it.
 
-This will allow the bot to send you back replies from the support team.
+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)
 
-Including such instructions can help in reducing the friction in user support interactions and
-ensure that your support team can effectively communicate with users through the bot.
+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
 

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

data/lib/telegram_support_bot/state_stores/redis.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module TelegramSupportBot
+  module StateStores
+    class Redis
+      DEFAULT_NAMESPACE = 'telegram_support_bot'
+
+      def initialize(url: nil, redis: nil, namespace: DEFAULT_NAMESPACE,
+                     mapping_ttl_seconds: nil, reaction_count_ttl_seconds: nil, user_profile_ttl_seconds: nil, **_options)
+        @redis = redis || begin
+          require 'redis'
+          ::Redis.new(url: url)
+        rescue LoadError => e
+          raise LoadError, "Redis backend requires the 'redis' gem. #{e.message}"
+        end
+        @namespace = namespace
+        @mapping_ttl_seconds = mapping_ttl_seconds
+        @reaction_count_ttl_seconds = reaction_count_ttl_seconds
+        @user_profile_ttl_seconds = user_profile_ttl_seconds
+      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)
+        payload = parse_json(@redis.get(map_key(:message_map, key)))
+        symbolize_hash(payload)
+      end
+
+      def set_message_mapping(key, value)
+        write_json(map_key(:message_map, key), value, @mapping_ttl_seconds)
+      end
+
+      def clear_message_mappings
+        delete_by_prefix(prefix(:message_map))
+      end
+
+      def message_mappings_size
+        count_by_prefix(prefix(:message_map))
+      end
+
+      def get_reverse_mapping(key)
+        raw = @redis.get(map_key(:reverse_message_map, key))
+        coerce_scalar(raw)
+      end
+
+      def set_reverse_mapping(key, value)
+        write_scalar(map_key(:reverse_message_map, key), value, @mapping_ttl_seconds)
+      end
+
+      def clear_reverse_mappings
+        delete_by_prefix(prefix(:reverse_message_map))
+      end
+
+      def reverse_mappings_size
+        count_by_prefix(prefix(:reverse_message_map))
+      end
+
+      def get_reaction_count(key)
+        parse_json(@redis.get(map_key(:reaction_count_state, key)))
+      end
+
+      def set_reaction_count(key, value)
+        write_json(map_key(:reaction_count_state, key), value, @reaction_count_ttl_seconds)
+      end
+
+      def clear_reaction_counts
+        delete_by_prefix(prefix(:reaction_count_state))
+      end
+
+      def reaction_counts_size
+        count_by_prefix(prefix(:reaction_count_state))
+      end
+
+      def get_user_profile(key)
+        payload = parse_json(@redis.get(map_key(:user_profiles, key)))
+        symbolize_hash(payload)
+      end
+
+      def set_user_profile(key, value)
+        write_json(map_key(:user_profiles, key), value, @user_profile_ttl_seconds)
+      end
+
+      def clear_user_profiles
+        delete_by_prefix(prefix(:user_profiles))
+      end
+
+      def user_profiles_size
+        count_by_prefix(prefix(:user_profiles))
+      end
+
+      private
+
+      def prefix(name)
+        "#{@namespace}:#{name}:"
+      end
+
+      def map_key(name, key)
+        "#{prefix(name)}#{key}"
+      end
+
+      def write_json(key, value, ttl_seconds)
+        payload = JSON.generate(value)
+        write_raw(key, payload, ttl_seconds)
+      end
+
+      def write_scalar(key, value, ttl_seconds)
+        write_raw(key, value.to_s, ttl_seconds)
+      end
+
+      def write_raw(key, value, ttl_seconds)
+        @redis.set(key, value)
+        @redis.expire(key, ttl_seconds.to_i) if ttl_seconds && ttl_seconds.to_i.positive?
+      end
+
+      def parse_json(raw)
+        return nil if raw.nil?
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def symbolize_hash(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), memo| memo[k.to_sym] = symbolize_hash(v) }
+        when Array
+          obj.map { |item| symbolize_hash(item) }
+        else
+          obj
+        end
+      end
+
+      def coerce_scalar(raw)
+        return nil if raw.nil?
+
+        return raw.to_i if /\A-?\d+\z/.match?(raw)
+
+        raw
+      end
+
+      def delete_by_prefix(key_prefix)
+        scan_each(key_prefix) do |key|
+          @redis.del(key)
+        end
+      end
+
+      def count_by_prefix(key_prefix)
+        count = 0
+        scan_each(key_prefix) { count += 1 }
+        count
+      end
+
+      def scan_each(key_prefix)
+        cursor = '0'
+        pattern = "#{key_prefix}*"
+
+        loop do
+          cursor, keys = @redis.scan(cursor, match: pattern, count: 1000)
+          keys.each { |key| yield key }
+          break if cursor == '0'
+        end
+      end
+    end
+  end
+end

data/lib/telegram_support_bot/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TelegramSupportBot
-  VERSION = "0.1.07"
+  VERSION = "0.1.08"
 end

data/lib/telegram_support_bot.rb

@@ -4,6 +4,7 @@ require_relative "telegram_support_bot/version"
 require_relative 'telegram_support_bot/configuration'
 require_relative 'telegram_support_bot/auto_away_scheduler'
 require_relative 'telegram_support_bot/adapter_factory'
+require_relative 'telegram_support_bot/state_store'
 require_relative 'telegram_support_bot/adapters/base'
 require_relative 'telegram_support_bot/adapters/telegram_bot'
 require_relative 'telegram_support_bot/adapters/telegram_bot_ruby'
@@ -11,7 +12,6 @@ require_relative 'telegram_support_bot/adapters/telegram_bot_ruby'
 module TelegramSupportBot
   class << self
     attr_accessor :configuration
-    attr_reader :message_chat_id
 
     # Provides a method to configure the gem.
     def configure
@@ -25,16 +25,28 @@ module TelegramSupportBot
       @adapter ||= AdapterFactory.build(configuration.adapter, configuration.adapter_options)
     end
 
+    def state_store
+      @state_store ||= StateStore.build(configuration)
+    end
+
     def message_map
-      @message_map ||= {}
+      state_store.message_map
     end
 
     def reverse_message_map
-      @reverse_message_map ||= {}
+      state_store.reverse_message_map
     end
 
     def reaction_count_state
-      @reaction_count_state ||= {}
+      state_store.reaction_count_state
+    end
+
+    def user_profiles
+      state_store.user_profiles
+    end
+
+    def user_profile(chat_id)
+      user_profiles[chat_id] || user_profiles[chat_id.to_s] || user_profiles[chat_id.to_i]
     end
 
     def scheduler
@@ -63,94 +75,129 @@ module TelegramSupportBot
     private
 
     def process_message(message)
-      @message_chat_id = message['chat']['id']
+      chat_id = message.dig('chat', 'id')
 
-      if message_chat_id == configuration.support_chat_id
-        process_support_chat_message(message)
+      if same_chat_id?(chat_id, configuration.support_chat_id)
+        process_support_chat_message(message, chat_id: chat_id)
       else
-        # Message is from an individual user, forward it to the support chat
-        if message['text'] == '/start'
-          # Send welcome message to the user
-          adapter.send_message(chat_id: message_chat_id, text: configuration.welcome_message)
-        else
-          forward_message_to_support_chat(message)
-        end
+        process_user_chat_message(message, chat_id: chat_id)
+      end
+    end
+
+    def process_user_chat_message(message, chat_id:)
+      if message.key?('contact')
+        process_user_contact(message, chat_id: chat_id)
+        return
+      end
+
+      if message['text'] == '/start'
+        adapter.send_message(chat_id: chat_id, text: configuration.welcome_message)
+        request_contact_from_user(chat_id: chat_id) if should_request_contact?(chat_id)
+        return
+      end
+
+      if configuration.require_contact_for_support && !contact_known_for_user?(chat_id)
+        request_contact_from_user(chat_id: chat_id)
+        return
       end
+
+      forward_message_to_support_chat(message, chat_id: chat_id)
     end
 
-    def process_support_chat_message(message)
+    def process_user_contact(message, chat_id:)
+      contact = message['contact'] || {}
+
+      unless valid_contact_for_chat?(contact: contact, chat_id: chat_id)
+        request_contact_from_user(chat_id: chat_id, text: configuration.contact_invalid_message)
+        return
+      end
+
+      profile = build_contact_profile(chat_id: chat_id, message: message, contact: contact)
+      store_user_profile(chat_id: chat_id, profile: profile)
+      notify_contact_received(profile)
+
+      adapter.send_message(
+        chat_id: chat_id,
+        text: configuration.contact_received_message,
+        reply_markup: remove_keyboard_markup
+      )
+    end
+
+    def process_support_chat_message(message, chat_id:)
       if message.key?('reply_to_message')
         # It's a reply in the support chat
         process_reply_in_support_chat(message)
       elsif message['text']&.start_with?('/')
-        process_command(message)
+        process_command(message, chat_id: chat_id)
       else
         # For non-command messages, you might want to handle differently or just ignore
         # For now, let's just acknowledge the message
-        acknowledge_non_command_message(message)
+        acknowledge_non_command_message(message, chat_id: chat_id)
       end
     end
 
-    def acknowledge_non_command_message(message)
+    def acknowledge_non_command_message(message, chat_id:)
       reply_message = 'I received your message, but I only respond to commands. Please use /start to get started.'
       adapter.send_message(
-        chat_id:             message_chat_id,
+        chat_id:             chat_id,
         text:                reply_message,
         reply_to_message_id: message['message_id']
       )
     end
 
-    def process_command(message)
+    def process_command(message, chat_id:)
       command = message['text'].split(/[ \@]/).first.downcase # Extract the command, normalize to lowercase
 
       case command
       when '/start'
-        send_welcome_message(chat_id: message_chat_id)
+        send_welcome_message(chat_id: chat_id)
       else
         # Respond to unknown commands
         unless configuration.ignore_unknown_commands
           unknown_command_response = "I don't know the command #{command}. Please use /start to begin or check the available commands."
-          adapter.send_message(chat_id: message_chat_id, text: unknown_command_response)
+          adapter.send_message(chat_id: chat_id, text: unknown_command_response)
         end
       end
     end
 
     def process_reply_in_support_chat(message)
       reply_to_message = message['reply_to_message']
+      reply_to_message_id = reply_to_message['message_id']
+      mapping = find_message_mapping(reply_to_message_id)
 
-      if reply_to_message.key?('forward_from')
-        # The reply is to a forwarded message
-        original_user_id = reply_to_message['forward_from']['id']
-        caption          = message['caption'] if message.key?('caption')
-
-        # Determine the type of media and prepare the content and options
-        type, media, options = extract_media_info(message)
-        options[:caption]    = caption if caption
-
-        message_id = message['message_id']
-        if :unknown == type
-          # Handle other types of messages or default case
-          warning_message = "Warning: The message type received from the user is not supported by the bot. Please assist the user directly."
-          adapter.send_message(
-            chat_id:             configuration.support_chat_id,
-            text:                warning_message,
-            reply_to_message_id: message_id
-          )
-        else
-          result = adapter.send_media(chat_id: original_user_id, type: type, media: media, **options)
-          if result
-            user_message_id = extract_message_id(result)
-            if user_message_id
-              support_message_id = message['message_id']
-              store_message_mapping(
-                support_message_id: support_message_id,
-                user_chat_id:       original_user_id,
-                user_message_id:    user_message_id
-              )
-            end
+      original_user_id = mapping && mapping[:chat_id]
+      original_user_id ||= reply_to_message.dig('forward_from', 'id')
+      return unless original_user_id
+
+      caption          = message['caption'] if message.key?('caption')
+
+      # Determine the type of media and prepare the content and options
+      type, media, options = extract_media_info(message)
+      options[:caption]    = caption if caption
+
+      message_id = message['message_id']
+      if :unknown == type
+        # Handle other types of messages or default case
+        warning_message = "Warning: The message type received from the user is not supported by the bot. Please assist the user directly."
+        adapter.send_message(
+          chat_id:             configuration.support_chat_id,
+          text:                warning_message,
+          reply_to_message_id: message_id
+        )
+      else
+        result = adapter.send_media(chat_id: original_user_id, type: type, media: media, **options)
+        if result
+          user_message_id = extract_message_id(result)
+          if user_message_id
+            support_message_id = message['message_id']
+            store_message_mapping(
+              support_message_id: support_message_id,
+              user_chat_id:       original_user_id,
+              user_message_id:    user_message_id
+            )
           end
-          # scheduler.cancel_scheduled_task(message_id)
         end
+        # scheduler.cancel_scheduled_task(message_id)
       end
     end
 
@@ -181,10 +228,10 @@ module TelegramSupportBot
       end
     end
 
-    def forward_message_to_support_chat(message)
+    def forward_message_to_support_chat(message, chat_id:)
       message_id = message['message_id']
       result = adapter.forward_message(
-        from_chat_id: message_chat_id,
+        from_chat_id: chat_id,
         message_id:   message_id,
         chat_id:      configuration.support_chat_id)
 
@@ -193,7 +240,7 @@ module TelegramSupportBot
         if support_message_id
           store_message_mapping(
             support_message_id: support_message_id,
-            user_chat_id:       message_chat_id,
+            user_chat_id:       chat_id,
             user_message_id:    message_id
           )
         end
@@ -312,6 +359,63 @@ module TelegramSupportBot
       warn "Failed to mirror reaction to chat_id=#{chat_id} message_id=#{message_id}: #{error.class}: #{error.message}"
     end
 
+    def request_contact_from_user(chat_id:, text: configuration.contact_request_message)
+      adapter.send_message(chat_id: chat_id, text: text, reply_markup: contact_request_keyboard)
+    end
+
+    def contact_request_keyboard
+      {
+        keyboard: [[{ text: 'Share phone number', request_contact: true }]],
+        resize_keyboard: true,
+        one_time_keyboard: true
+      }
+    end
+
+    def remove_keyboard_markup
+      { remove_keyboard: true }
+    end
+
+    def should_request_contact?(chat_id)
+      configuration.request_contact_on_start && !contact_known_for_user?(chat_id)
+    end
+
+    def contact_known_for_user?(chat_id)
+      !user_profile(chat_id).nil?
+    end
+
+    def valid_contact_for_chat?(contact:, chat_id:)
+      contact_user_id = contact['user_id'] || contact[:user_id]
+      return false if contact_user_id.nil?
+
+      same_chat_id?(contact_user_id, chat_id)
+    end
+
+    def build_contact_profile(chat_id:, message:, contact:)
+      sender = message['from'] || {}
+      {
+        chat_id: chat_id,
+        user_id: contact['user_id'] || contact[:user_id],
+        phone_number: contact['phone_number'] || contact[:phone_number],
+        first_name: contact['first_name'] || contact[:first_name] || sender['first_name'],
+        last_name: contact['last_name'] || contact[:last_name] || sender['last_name'],
+        username: sender['username'],
+        language_code: sender['language_code']
+      }
+    end
+
+    def store_user_profile(chat_id:, profile:)
+      user_profiles[chat_id] = profile
+      user_profiles[chat_id.to_s] = profile
+    end
+
+    def notify_contact_received(profile)
+      return unless configuration.on_contact_received.respond_to?(:call)
+
+      configuration.on_contact_received.call(profile)
+    rescue StandardError => error
+      warn "Failed to run on_contact_received callback: #{error.class}: #{error.message}"
+    end
+
     def extract_reaction_counts(reactions)
       counts = {}
       reaction_types = {}
@@ -414,4 +518,8 @@ module TelegramSupportBot
   def self.reset_adapter!
     @adapter = nil
   end
+
+  def self.reset_state_store!
+    @state_store = nil
+  end
 end

data/script/dev_poll.rb

@@ -3,6 +3,7 @@
 
 require 'telegram_support_bot'
 require 'telegram/bot'
+require 'json'
 
 token = ENV.fetch('TELEGRAM_BOT_TOKEN')
 support_chat_id = Integer(ENV.fetch('SUPPORT_CHAT_ID'))
@@ -16,7 +17,13 @@ TelegramSupportBot.configure do |config|
   config.adapter = adapter.to_sym
   config.adapter_options = adapter_options
   config.support_chat_id = support_chat_id
+  config.request_contact_on_start = true
+  # config.require_contact_for_support = true
   config.welcome_message = 'Hi! How can we help you?'
+  config.on_contact_received = lambda do |profile|
+    puts '[TSB CONTACT] Contact received profile:'
+    puts JSON.pretty_generate(profile)
+  end
 end
 
 client = Telegram::Bot::Client.new(token)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: telegram-support-bot
 version: !ruby/object:Gem::Version
-  version: 0.1.07
+  version: 0.1.08
 platform: ruby
 authors:
 - Max Buslaev
@@ -9,7 +9,21 @@ autorequire:
 bindir: exe
 cert_chain: []
 date: 2026-02-13 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.8'
 description: |-
   The telegram_support_bot gem provides Rails applications with an
   easy-to-integrate Telegram bot, designed to enhance customer support services.
@@ -41,6 +55,9 @@ files:
 - lib/telegram_support_bot/adapters/telegram_bot_ruby.rb
 - lib/telegram_support_bot/auto_away_scheduler.rb
 - lib/telegram_support_bot/configuration.rb
+- lib/telegram_support_bot/state_store.rb
+- lib/telegram_support_bot/state_stores/memory.rb
+- lib/telegram_support_bot/state_stores/redis.rb
 - lib/telegram_support_bot/version.rb
 - script/dev_poll.rb
 - sig/telegram_support_bot.rbs