flow_chat 0.4.0 → 0.4.1

data/lib/flow_chat/whatsapp/gateway/cloud_api.rb

@@ -11,6 +11,7 @@ module FlowChat
         def initialize(app, config = nil)
           @app = app
           @config = config || FlowChat::Whatsapp::Configuration.from_credentials
+          @client = FlowChat::Whatsapp::Client.new(@config)
         end
 
         def call(context)
@@ -30,8 +31,23 @@ module FlowChat
           controller.head :bad_request
         end
 
+        # Expose client for out-of-band messaging
+        def client
+          @client
+        end
+
         private
 
+        def determine_message_handler(context)
+          # Check for simulator parameter in request (highest priority)
+          if context["simulator_mode"] || context.controller.request.params["simulator_mode"]
+            return :simulator
+          end
+
+          # Use global WhatsApp configuration
+          FlowChat::Config.whatsapp.message_handling_mode
+        end
+
         def handle_verification(context)
           controller = context.controller
           params = controller.request.params
@@ -49,6 +65,11 @@ module FlowChat
           controller = context.controller
           body = JSON.parse(controller.request.body.read)
 
+          # Check for simulator mode parameter in request
+          if body.dig("simulator_mode") || controller.request.params["simulator_mode"]
+            context["simulator_mode"] = true
+          end
+
           # Extract message data from WhatsApp webhook
           entry = body.dig("entry", 0)
           return controller.head :ok unless entry
@@ -72,139 +93,118 @@ module FlowChat
             context["request.timestamp"] = message["timestamp"]
 
             # Extract message content based on type
-            case message["type"]
-            when "text"
-              context.input = message.dig("text", "body")
-            when "interactive"
-              # Handle button/list replies
-              if message.dig("interactive", "type") == "button_reply"
-                context.input = message.dig("interactive", "button_reply", "id")
-              elsif message.dig("interactive", "type") == "list_reply"
-                context.input = message.dig("interactive", "list_reply", "id")
-              end
-            when "location"
-              context["request.location"] = {
-                latitude: message.dig("location", "latitude"),
-                longitude: message.dig("location", "longitude"),
-                name: message.dig("location", "name"),
-                address: message.dig("location", "address")
-              }
-              # Set input so screen can proceed
-              context.input = "$location$"
-            when "image", "document", "audio", "video"
-              context["request.media"] = {
-                type: message["type"],
-                id: message.dig(message["type"], "id"),
-                mime_type: message.dig(message["type"], "mime_type"),
-                caption: message.dig(message["type"], "caption")
-              }
-              # Set input so screen can proceed
-              context.input = "$media$"
+            extract_message_content(message, context)
+
+            # Determine message handling mode
+            handler_mode = determine_message_handler(context)
+
+            # Process the message based on handling mode
+            case handler_mode
+            when :inline
+              handle_message_inline(context, controller)
+            when :background
+              handle_message_background(context, controller)
+            when :simulator
+              # Return early from simulator mode to preserve the JSON response
+              return handle_message_simulator(context, controller)
             end
-
-            response = @app.call(context)
-            send_whatsapp_message(context, response)
           end
 
           # Handle message status updates
           if value["statuses"]&.any?
-            # Log status updates but don't process them
             Rails.logger.info "WhatsApp status update: #{value["statuses"]}"
           end
 
           controller.head :ok
         end
 
-        def send_whatsapp_message(context, response)
-          return unless response
-
-          phone_number_id = @config.phone_number_id
-          access_token = @config.access_token
-          to = context["request.msisdn"]
-
-          message_data = build_message_payload(response, to)
-
-          uri = URI("#{WHATSAPP_API_URL}/#{phone_number_id}/messages")
-          http = Net::HTTP.new(uri.host, uri.port)
-          http.use_ssl = true
+        def extract_message_content(message, context)
+          case message["type"]
+          when "text"
+            context.input = message.dig("text", "body")
+          when "interactive"
+            # Handle button/list replies
+            if message.dig("interactive", "type") == "button_reply"
+              context.input = message.dig("interactive", "button_reply", "id")
+            elsif message.dig("interactive", "type") == "list_reply"
+              context.input = message.dig("interactive", "list_reply", "id")
+            end
+          when "location"
+            context["request.location"] = {
+              latitude: message.dig("location", "latitude"),
+              longitude: message.dig("location", "longitude"),
+              name: message.dig("location", "name"),
+              address: message.dig("location", "address")
+            }
+            context.input = "$location$"
+          when "image", "document", "audio", "video"
+            context["request.media"] = {
+              type: message["type"],
+              id: message.dig(message["type"], "id"),
+              mime_type: message.dig(message["type"], "mime_type"),
+              caption: message.dig(message["type"], "caption")
+            }
+            context.input = "$media$"
+          end
+        end
 
-          request = Net::HTTP::Post.new(uri)
-          request["Authorization"] = "Bearer #{access_token}"
-          request["Content-Type"] = "application/json"
-          request.body = message_data.to_json
+        def handle_message_inline(context, controller)
+          response = @app.call(context)
+          if response
+            result = @client.send_message(context["request.msisdn"], response)
+            context["whatsapp.message_result"] = result
+          end
+        end
 
-          response = http.request(request)
+        def handle_message_background(context, controller)
+          # Process the flow synchronously (maintaining controller context)
+          response = @app.call(context)
           
-          unless response.is_a?(Net::HTTPSuccess)
-            Rails.logger.error "WhatsApp API error: #{response.body}"
+          if response
+            # Queue only the response delivery asynchronously
+            send_data = {
+              msisdn: context["request.msisdn"],
+              response: response,
+              config_name: @config.name
+            }
+
+            # Get job class from configuration
+            job_class_name = FlowChat::Config.whatsapp.background_job_class
+            
+            # Enqueue background job for sending only
+            begin
+              job_class = job_class_name.constantize
+              job_class.perform_later(send_data)
+            rescue NameError
+              # Fallback to inline sending if no job system
+              Rails.logger.warn "Background mode requested but no #{job_class_name} found. Falling back to inline sending."
+              result = @client.send_message(context["request.msisdn"], response)
+              context["whatsapp.message_result"] = result
+            end
           end
         end
 
-        def build_message_payload(response, to)
-          type, content, options = response
-
-          case type
-          when :text
-            {
-              messaging_product: "whatsapp",
-              to: to,
-              type: "text",
-              text: { body: content }
-            }
-          when :interactive_buttons
-            {
-              messaging_product: "whatsapp",
-              to: to,
-              type: "interactive",
-              interactive: {
-                type: "button",
-                body: { text: content },
-                action: {
-                  buttons: options[:buttons].map.with_index do |button, index|
-                    {
-                      type: "reply",
-                      reply: {
-                        id: button[:id] || index.to_s,
-                        title: button[:title]
-                      }
-                    }
-                  end
-                }
-              }
-            }
-          when :interactive_list
-            {
-              messaging_product: "whatsapp",
-              to: to,
-              type: "interactive",
-              interactive: {
-                type: "list",
-                body: { text: content },
-                action: {
-                  button: options[:button_text] || "Choose",
-                  sections: options[:sections]
-                }
-              }
-            }
-          when :template
-            {
-              messaging_product: "whatsapp",
-              to: to,
-              type: "template",
-              template: {
-                name: options[:template_name],
-                language: { code: options[:language] || "en_US" },
-                components: options[:components] || []
+        def handle_message_simulator(context, controller)
+          response = @app.call(context)
+          
+          if response
+            # For simulator mode, return the response data in the HTTP response
+            # instead of actually sending via WhatsApp API
+            message_payload = @client.build_message_payload(response, context["request.msisdn"])
+            
+            simulator_response = {
+              mode: "simulator",
+              webhook_processed: true,
+              would_send: message_payload,
+              message_info: {
+                to: context["request.msisdn"],
+                contact_name: context["request.contact_name"],
+                timestamp: Time.now.iso8601
               }
             }
-          else
-            # Default to text message
-            {
-              messaging_product: "whatsapp",
-              to: to,
-              type: "text",
-              text: { body: content.to_s }
-            }
+
+            controller.render json: simulator_response
+            return
           end
         end
       end

data/lib/flow_chat/whatsapp/processor.rb

@@ -6,15 +6,6 @@ module FlowChat
         self
       end
 
-      def use_gateway(gateway_class)
-        if gateway_class == FlowChat::Whatsapp::Gateway::CloudApi
-          @gateway = @whatsapp_config ? gateway_class.new(nil, @whatsapp_config) : gateway_class.new(nil)
-        else
-          @gateway = gateway_class.new(nil)
-        end
-        self
-      end
-
       protected
 
       def middleware_name
@@ -26,7 +17,6 @@ module FlowChat
       end
 
       def configure_middleware_stack(builder)
-        builder.use gateway
         builder.use FlowChat::Session::Middleware
         builder.use middleware
         builder.use FlowChat::Whatsapp::Middleware::Executor

data/lib/flow_chat/whatsapp/prompt.rb

@@ -7,14 +7,33 @@ module FlowChat
         @input = input
       end
 
-      def ask(message, transform: nil, validate: nil, convert: nil)
+      def ask(message, transform: nil, validate: nil, convert: nil, media: nil)
         if input.present?
-          processed_input = process_input(input, transform, validate, convert)
-          return processed_input unless processed_input.nil?
+          begin
+            processed_input = process_input(input, transform, validate, convert)
+            return processed_input unless processed_input.nil?
+          rescue FlowChat::Interrupt::Prompt => validation_error
+            # If validation failed, include the error message with the original prompt
+            error_message = validation_error.prompt[1]
+            combined_message = "#{message}\n\n#{error_message}"
+            raise FlowChat::Interrupt::Prompt.new([:text, combined_message, {}])
+          end
         end
 
-        # Send message and wait for response
-        raise FlowChat::Interrupt::Prompt.new([:text, message, {}])
+        # Send message and wait for response, optionally with media
+        if media
+          raise FlowChat::Interrupt::Prompt.new(build_media_prompt(message, media))
+        else
+          raise FlowChat::Interrupt::Prompt.new([:text, message, {}])
+        end
+      end
+
+      def say(message, media: nil)
+        if media
+          raise FlowChat::Interrupt::Terminate.new(build_media_prompt(message, media))
+        else
+          raise FlowChat::Interrupt::Terminate.new([:text, message, {}])
+        end
       end
 
       def select(message, choices, transform: nil, validate: nil, convert: nil)
@@ -26,39 +45,119 @@ module FlowChat
         # Validate choices
         validate_choices(choices)
 
+        # Standard selection without media support
+        interactive_prompt = build_selection_prompt(message, choices)
+        raise FlowChat::Interrupt::Prompt.new(interactive_prompt)
+      end
+
+      def yes?(message, transform: nil, validate: nil, convert: nil)
+        if input.present?
+          processed_input = process_boolean(input, transform, validate, convert)
+          return processed_input unless processed_input.nil?
+        end
+
+        buttons = [
+          { id: "yes", title: "Yes" },
+          { id: "no", title: "No" }
+        ]
+        raise FlowChat::Interrupt::Prompt.new([:interactive_buttons, message, { buttons: buttons }])
+      end
+
+      private
+
+      def build_media_prompt(message, media)
+        media_type = media[:type] || :image
+        url = media[:url] || media[:path]
+        filename = media[:filename]
+
+        case media_type.to_sym
+        when :image
+          [:media_image, "", { url: url, caption: message }]
+        when :document
+          [:media_document, "", { url: url, caption: message, filename: filename }]
+        when :audio
+          [:media_audio, "", { url: url, caption: message }]
+        when :video
+          [:media_video, "", { url: url, caption: message }]
+        when :sticker
+          [:media_sticker, "", { url: url }] # Stickers don't support captions
+        else
+          raise ArgumentError, "Unsupported media type: #{media_type}"
+        end
+      end
+
+      def build_selection_prompt(message, choices)
         # Determine the best way to present choices
         if choices.is_a?(Array)
           # Convert array to hash with index-based keys
           choice_hash = choices.each_with_index.to_h { |choice, index| [index.to_s, choice] }
-          present_choices_as_list(message, choice_hash)
+          build_list_prompt(message, choice_hash)
         elsif choices.is_a?(Hash)
           if choices.length <= 3
             # Use buttons for 3 or fewer choices
-            present_choices_as_buttons(message, choices)
+            build_buttons_prompt(message, choices)
           else
             # Use list for more than 3 choices
-            present_choices_as_list(message, choices)
+            build_list_prompt(message, choices)
           end
         else
           raise ArgumentError, "choices must be an Array or Hash"
         end
       end
 
-      def yes?(message, transform: nil, validate: nil, convert: nil)
-        if input.present?
-          processed_input = process_boolean(input, transform, validate, convert)
-          return processed_input unless processed_input.nil?
+      def build_buttons_prompt(message, choices)
+        buttons = choices.map do |key, value|
+          {
+            id: key.to_s,
+            title: truncate_text(value.to_s, 20) # WhatsApp button titles have a 20 character limit
+          }
         end
 
-        buttons = [
-          { id: "yes", title: "Yes" },
-          { id: "no", title: "No" }
-        ]
-
-        raise FlowChat::Interrupt::Prompt.new([:interactive_buttons, message, { buttons: buttons }])
+        [:interactive_buttons, message, { buttons: buttons }]
       end
 
-      private
+      def build_list_prompt(message, choices)
+        items = choices.map do |key, value|
+          original_text = value.to_s
+          truncated_title = truncate_text(original_text, 24)
+          
+          # If title was truncated, put full text in description (up to 72 chars)
+          description = if original_text.length > 24
+                         truncate_text(original_text, 72)
+                       else
+                         nil
+                       end
+          
+          {
+            id: key.to_s,
+            title: truncated_title,
+            description: description
+          }.compact
+        end
+
+        # If 10 or fewer items, use single section
+        if items.length <= 10
+          sections = [
+            {
+              title: "Options",
+              rows: items
+            }
+          ]
+        else
+          # Paginate into multiple sections (max 10 items per section)
+          sections = items.each_slice(10).with_index.map do |section_items, index|
+            start_num = (index * 10) + 1
+            end_num = start_num + section_items.length - 1
+            
+            {
+              title: "#{start_num}-#{end_num}",
+              rows: section_items
+            }
+          end
+        end
+
+        [:interactive_list, message, { sections: sections }]
+      end
 
       def process_input(input, transform, validate, convert)
         # Apply transformation
@@ -115,60 +214,6 @@ module FlowChat
         process_input(boolean_value, transform, validate, convert)
       end
 
-      def present_choices_as_buttons(message, choices)
-        buttons = choices.map do |key, value|
-          {
-            id: key.to_s,
-            title: truncate_text(value.to_s, 20) # WhatsApp button titles have a 20 character limit
-          }
-        end
-
-        raise FlowChat::Interrupt::Prompt.new([:interactive_buttons, message, { buttons: buttons }])
-      end
-
-      def present_choices_as_list(message, choices)
-        items = choices.map do |key, value|
-          original_text = value.to_s
-          truncated_title = truncate_text(original_text, 24)
-          
-          # If title was truncated, put full text in description (up to 72 chars)
-          description = if original_text.length > 24
-                         truncate_text(original_text, 72)
-                       else
-                         nil
-                       end
-          
-          {
-            id: key.to_s,
-            title: truncated_title,
-            description: description
-          }.compact
-        end
-
-        # If 10 or fewer items, use single section
-        if items.length <= 10
-          sections = [
-            {
-              title: "Options",
-              rows: items
-            }
-          ]
-        else
-          # Paginate into multiple sections (max 10 items per section)
-          sections = items.each_slice(10).with_index.map do |section_items, index|
-            start_num = (index * 10) + 1
-            end_num = start_num + section_items.length - 1
-            
-            {
-              title: "#{start_num}-#{end_num}",
-              rows: section_items
-            }
-          end
-        end
-
-        raise FlowChat::Interrupt::Prompt.new([:interactive_list, message, { sections: sections }])
-      end
-
       def validate_choices(choices)
         # Check for empty choices
         if choices.nil? || choices.empty?

data/lib/flow_chat/whatsapp/send_job_support.rb

@@ -0,0 +1,79 @@
+module FlowChat
+  module Whatsapp
+    # Module to be included in background jobs for WhatsApp response delivery
+    # Only handles sending responses, not processing flows
+    module SendJobSupport
+      extend ActiveSupport::Concern
+
+      included do
+        # Set up job configuration
+        queue_as :default
+        retry_on StandardError, wait: :exponentially_longer, attempts: 3
+      end
+
+      # Main job execution method for sending responses
+      def perform_whatsapp_send(send_data)
+        config = resolve_whatsapp_config(send_data)
+        client = FlowChat::Whatsapp::Client.new(config)
+        
+        result = client.send_message(send_data[:msisdn], send_data[:response])
+        
+        if result
+          Rails.logger.info "WhatsApp message sent successfully: #{result['messages']&.first&.dig('id')}"
+          on_whatsapp_send_success(send_data, result)
+        else
+          Rails.logger.error "Failed to send WhatsApp message to #{send_data[:msisdn]}"
+          raise "WhatsApp API call failed"
+        end
+      rescue => e
+        on_whatsapp_send_error(e, send_data)
+        handle_whatsapp_send_error(e, send_data, config)
+      end
+
+      private
+
+      # Resolve WhatsApp configuration by name or fallback
+      def resolve_whatsapp_config(send_data)
+        # Try to resolve by name first (preferred method)
+        if send_data[:config_name] && FlowChat::Whatsapp::Configuration.exists?(send_data[:config_name])
+          return FlowChat::Whatsapp::Configuration.get(send_data[:config_name])
+        end
+
+        # Final fallback to default configuration
+        FlowChat::Whatsapp::Configuration.from_credentials
+      end
+
+      # Handle errors with user notification
+      def handle_whatsapp_send_error(error, send_data, config = nil)
+        Rails.logger.error "WhatsApp send job error: #{error.message}"
+        Rails.logger.error error.backtrace&.join("\n") if error.backtrace
+        
+        # Try to send error message to user if we have config
+        if config
+          begin
+            client = FlowChat::Whatsapp::Client.new(config)
+            client.send_text(
+              send_data[:msisdn], 
+              "⚠️ We're experiencing technical difficulties. Please try again in a few minutes."
+            )
+          rescue => send_error
+            Rails.logger.error "Failed to send error message: #{send_error.message}"
+          end
+        end
+        
+        # Re-raise for job retry logic
+        raise error
+      end
+
+      # Override this method in your job for custom behavior
+      def on_whatsapp_send_success(send_data, result)
+        # Optional callback for successful message sending
+      end
+
+      # Override this method in your job for custom error handling
+      def on_whatsapp_send_error(error, send_data)
+        # Optional callback for error handling
+      end
+    end
+  end
+end 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flow_chat
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Stefan Froelich
@@ -98,9 +98,12 @@ files:
 - bin/console
 - bin/setup
 - examples/initializer.rb
+- examples/media_prompts_examples.rb
 - examples/multi_tenant_whatsapp_controller.rb
 - examples/ussd_controller.rb
 - examples/whatsapp_controller.rb
+- examples/whatsapp_media_examples.rb
+- examples/whatsapp_message_job.rb
 - flow_chat.gemspec
 - images/ussd_simulator.png
 - lib/flow_chat.rb
@@ -112,6 +115,8 @@ files:
 - lib/flow_chat/session/cache_session_store.rb
 - lib/flow_chat/session/middleware.rb
 - lib/flow_chat/session/rails_session_store.rb
+- lib/flow_chat/simulator/controller.rb
+- lib/flow_chat/simulator/views/simulator.html.erb
 - lib/flow_chat/ussd/app.rb
 - lib/flow_chat/ussd/gateway/nalo.rb
 - lib/flow_chat/ussd/gateway/nsano.rb
@@ -121,15 +126,15 @@ files:
 - lib/flow_chat/ussd/processor.rb
 - lib/flow_chat/ussd/prompt.rb
 - lib/flow_chat/ussd/renderer.rb
-- lib/flow_chat/ussd/simulator/controller.rb
-- lib/flow_chat/ussd/simulator/views/simulator.html.erb
 - lib/flow_chat/version.rb
 - lib/flow_chat/whatsapp/app.rb
+- lib/flow_chat/whatsapp/client.rb
 - lib/flow_chat/whatsapp/configuration.rb
 - lib/flow_chat/whatsapp/gateway/cloud_api.rb
 - lib/flow_chat/whatsapp/middleware/executor.rb
 - lib/flow_chat/whatsapp/processor.rb
 - lib/flow_chat/whatsapp/prompt.rb
+- lib/flow_chat/whatsapp/send_job_support.rb
 - lib/flow_chat/whatsapp/template_manager.rb
 homepage: https://github.com/radioactive-labs/flow_chat
 licenses: