flow_chat 0.3.0 → 0.4.1

data/README.md

@@ -1,14 +1,16 @@
 # FlowChat
 
-FlowChat is a Rails framework designed for building sophisticated conversational workflows, particularly for USSD (Unstructured Supplementary Service Data) systems. It provides an intuitive Ruby DSL for creating multi-step, menu-driven conversations with automatic session management, input validation, and flow control.
+FlowChat is a Rails framework designed for building sophisticated conversational workflows for both USSD (Unstructured Supplementary Service Data) systems and WhatsApp messaging. It provides an intuitive Ruby DSL for creating multi-step, menu-driven conversations with automatic session management, input validation, and flow control.
 
 **Key Features:**
 - 🎯 **Declarative Flow Definition** - Define conversation flows as Ruby classes
 - 🔄 **Automatic Session Management** - Persistent state across requests  
 - ✅ **Input Validation & Transformation** - Built-in validation and data conversion
 - 🌊 **Middleware Architecture** - Flexible request processing pipeline
-- 📱 **USSD Gateway Support** - Currently supports Nalo and Nsano gateways
-- 🧪 **Built-in Testing Tools** - USSD simulator for local development
+- 📱 **USSD Gateway Support** - Currently supports Nalo gateways
+- 💬 **WhatsApp Integration** - Full WhatsApp Cloud API support with multiple processing modes
+- 🔧 **Reusable WhatsApp Client** - Standalone client for out-of-band messaging
+- 🧪 **Built-in Testing Tools** - Unified simulator for both USSD and WhatsApp testing
 
 ## Architecture Overview
 
@@ -21,9 +23,9 @@ User Input → Gateway → Session → Pagination → Custom → Executor → Fl
 ```
 
 **Middleware Pipeline:**
-- **Gateway**: USSD provider communication (Nalo/Nsano)
+- **Gateway**: Communication with providers (USSD: Nalo, WhatsApp: Cloud API)
 - **Session**: Load/save conversation state  
-- **Pagination**: Split long responses into pages
+- **Pagination**: Split long responses into pages (USSD only)
 - **Custom**: Your application middleware (logging, auth, etc.)
 - **Executor**: Execute flow methods and handle interrupts
 
@@ -43,6 +45,10 @@ bundle install
 
 ## Quick Start
 
+FlowChat supports both USSD and WhatsApp. Choose the platform that fits your needs:
+
+### USSD Setup
+
 ### 1. Create Your First Flow
 
 Create a flow class in `app/flow_chat/welcome_flow.rb`:
@@ -60,7 +66,7 @@ class WelcomeFlow < FlowChat::Flow
 end
 ```
 
-### 2. Set Up the Controller
+### 2. Set Up the USSD Controller
 
 Create a controller to handle USSD requests:
 
@@ -89,6 +95,501 @@ Rails.application.routes.draw do
 end
 ```
 
+💡 **Tip**: See [examples/ussd_controller.rb](examples/ussd_controller.rb) for a complete USSD controller example with payment flows, customer support, and custom middleware.
+
+### WhatsApp Setup
+
+### 1. Configure WhatsApp Credentials
+
+FlowChat supports two ways to configure WhatsApp credentials:
+
+**Option A: Using Rails Credentials**
+
+Add your WhatsApp credentials to Rails credentials:
+
+```bash
+rails credentials:edit
+```
+
+```yaml
+whatsapp:
+  access_token: "your_access_token"
+  phone_number_id: "your_phone_number_id"
+  verify_token: "your_verify_token"
+  app_id: "your_app_id"
+  app_secret: "your_app_secret"
+  webhook_url: "your_webhook_url"
+  business_account_id: "your_business_account_id"
+```
+
+**Option B: Using Environment Variables**
+
+Alternatively, you can use environment variables:
+
+```bash
+# Add to your .env file or environment
+export WHATSAPP_ACCESS_TOKEN="your_access_token"
+export WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id" 
+export WHATSAPP_VERIFY_TOKEN="your_verify_token"
+export WHATSAPP_APP_ID="your_app_id"
+export WHATSAPP_APP_SECRET="your_app_secret"
+export WHATSAPP_WEBHOOK_URL="your_webhook_url"
+export WHATSAPP_BUSINESS_ACCOUNT_ID="your_business_account_id"
+```
+
+FlowChat will automatically use Rails credentials first, falling back to environment variables if credentials are not available.
+
+**Option C: Per-Setup Configuration**
+
+For multi-tenant applications or when you need different WhatsApp accounts per endpoint:
+
+```ruby
+# Create custom configuration
+custom_config = FlowChat::Whatsapp::Configuration.new
+custom_config.access_token = "your_specific_access_token"
+custom_config.phone_number_id = "your_specific_phone_number_id"
+custom_config.verify_token = "your_specific_verify_token"
+custom_config.app_id = "your_specific_app_id"
+custom_config.app_secret = "your_specific_app_secret"
+custom_config.business_account_id = "your_specific_business_account_id"
+
+# Use in processor
+processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, custom_config
+  config.use_session_store FlowChat::Session::CacheSessionStore
+end
+```
+
+💡 **Tip**: See [examples/multi_tenant_whatsapp_controller.rb](examples/multi_tenant_whatsapp_controller.rb) for comprehensive multi-tenant and per-setup configuration examples.
+
+### 2. Choose Message Handling Mode
+
+FlowChat offers three WhatsApp message handling modes. Configure them in an initializer:
+
+**Create an initializer** `config/initializers/flowchat.rb`:
+
+```ruby
+# config/initializers/flowchat.rb
+
+# Configure WhatsApp message handling mode
+FlowChat::Config.whatsapp.message_handling_mode = :inline  # or :background, :simulator
+FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+```
+
+**Inline Mode (Default)** - Process messages synchronously:
+```ruby
+# config/initializers/flowchat.rb
+FlowChat::Config.whatsapp.message_handling_mode = :inline
+
+# app/controllers/whatsapp_controller.rb
+class WhatsappController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+end
+```
+
+**Background Mode** - Process flows synchronously, send responses asynchronously:
+```ruby
+# config/initializers/flowchat.rb
+FlowChat::Config.whatsapp.message_handling_mode = :background
+FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+
+# app/controllers/whatsapp_controller.rb
+class WhatsappController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+end
+```
+
+**Simulator Mode** - Return response data instead of sending via WhatsApp API:
+```ruby
+# config/initializers/flowchat.rb
+FlowChat::Config.whatsapp.message_handling_mode = :simulator
+
+# app/controllers/whatsapp_controller.rb
+class WhatsappController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+end
+```
+
+💡 **See [examples/README_whatsapp_modes.md](examples/README_whatsapp_modes.md) for detailed mode explanations and use cases.**
+
+### 3. Add WhatsApp Route
+
+```ruby
+Rails.application.routes.draw do
+  match '/whatsapp/webhook', to: 'whatsapp#webhook', via: [:get, :post]
+end
+```
+
+### 4. Enhanced Features for WhatsApp
+
+The same flow works for both USSD and WhatsApp, but WhatsApp provides additional data and better interactive features:
+
+```ruby
+class WelcomeFlow < FlowChat::Flow
+  def main_page
+    # Access WhatsApp-specific data
+    Rails.logger.info "Contact: #{app.contact_name}, Phone: #{app.phone_number}"
+    Rails.logger.info "Message ID: #{app.message_id}, Timestamp: #{app.timestamp}"
+    
+    # Handle location sharing
+    if app.location
+      app.say "Thanks for sharing your location! We see you're at #{app.location['latitude']}, #{app.location['longitude']}"
+      return
+    end
+    
+    # Handle media messages  
+    if app.media
+      app.say "Thanks for the #{app.media['type']} file! We received: #{app.media['id']}"
+      return
+    end
+
+    name = app.screen(:name) do |prompt|
+      prompt.ask "Hello! Welcome to our WhatsApp service. What's your name?",
+        transform: ->(input) { input.strip.titleize }
+    end
+
+    # WhatsApp supports interactive buttons and lists via prompt.select
+    choice = app.screen(:main_menu) do |prompt|
+      prompt.select "Hi #{name}! How can I help you?", {
+        "info" => "📋 Get Information",
+        "support" => "🆘 Contact Support",
+        "feedback" => "💬 Give Feedback"
+      }
+    end
+
+    case choice
+    when "info"
+      show_information_menu
+    when "support"
+      contact_support  
+    when "feedback"
+      collect_feedback
+    end
+  end
+
+  private
+
+  def show_information_menu
+    info_choice = app.screen(:info_menu) do |prompt|
+      prompt.select "What information do you need?", {
+        "hours" => "🕒 Business Hours",
+        "location" => "📍 Our Location", 
+        "services" => "💼 Our Services"
+      }
+    end
+
+    case info_choice
+    when "hours"
+      app.say "We're open Monday-Friday 9AM-6PM, Saturday 10AM-4PM. Closed Sundays."
+    when "location"
+      app.say "📍 Visit us at 123 Main Street, Downtown. We're next to the coffee shop!"
+    when "services"
+      app.say "💼 We offer: Web Development, Mobile Apps, Cloud Services, and IT Consulting."
+    end
+  end
+
+  def contact_support
+    support_choice = app.screen(:support_menu) do |prompt|
+      prompt.select "How would you like to contact support?", {
+        "call" => "📞 Call Us",
+        "email" => "📧 Email Us",
+        "chat" => "💬 Continue Here"
+      }
+    end
+
+    case support_choice
+    when "call"
+      app.say "📞 Call us at: +1-555-HELP (4357)\nAvailable Mon-Fri 9AM-5PM"
+    when "email"  
+      app.say "📧 Email us at: support@company.com\nWe typically respond within 24 hours"
+    when "chat"
+      app.say "💬 Great! Please describe your issue and we'll help you right away."
+    end
+  end
+
+  def collect_feedback
+    rating = app.screen(:rating) do |prompt|
+      prompt.select "How would you rate our service?", {
+        "5" => "⭐⭐⭐⭐⭐ Excellent",
+        "4" => "⭐⭐⭐⭐ Good",
+        "3" => "⭐⭐⭐ Average",
+        "2" => "⭐⭐ Poor",
+        "1" => "⭐ Very Poor"
+      }
+    end
+
+    feedback = app.screen(:feedback_text) do |prompt|
+      prompt.ask "Thank you for the #{rating}-star rating! Please share any additional feedback:"
+    end
+
+    # Use WhatsApp-specific data for logging
+    Rails.logger.info "Feedback from #{app.contact_name} (#{app.phone_number}): #{rating} stars - #{feedback}"
+
+    app.say "Thank you for your feedback! We really appreciate it. 🙏"
+  end
+end
+```
+
+For detailed WhatsApp setup instructions, see [WhatsApp Integration Guide](docs/whatsapp_setup.md).
+
+## 🔧 Reusable WhatsApp Client
+
+FlowChat provides a standalone WhatsApp client for out-of-band messaging:
+
+```ruby
+# Initialize client
+config = FlowChat::Whatsapp::Configuration.from_credentials
+client = FlowChat::Whatsapp::Client.new(config)
+
+# Send text message
+client.send_text("+1234567890", "Hello, World!")
+
+# Send interactive buttons
+client.send_buttons(
+  "+1234567890",
+  "Choose an option:",
+  [
+    { id: 'option1', title: 'Option 1' },
+    { id: 'option2', title: 'Option 2' }
+  ]
+)
+
+# Send interactive list
+client.send_list(
+  "+1234567890",
+  "Select from menu:",
+  [
+    {
+      title: "Services",
+      rows: [
+        { id: 'service1', title: 'Service 1', description: 'Description 1' },
+        { id: 'service2', title: 'Service 2', description: 'Description 2' }
+      ]
+    }
+  ]
+)
+
+# Handle media
+media_url = client.get_media_url("media_id_123")
+media_content = client.download_media("media_id_123")
+```
+
+### Out-of-Band Messaging Service Example
+
+```ruby
+class NotificationService
+  def initialize
+    @config = FlowChat::Whatsapp::Configuration.from_credentials
+    @client = FlowChat::Whatsapp::Client.new(@config)
+  end
+
+  def send_order_confirmation(phone_number, order_id, items, total)
+    item_list = items.map { |item| "• #{item[:name]} x#{item[:quantity]}" }.join("\n")
+    
+    @client.send_buttons(
+      phone_number,
+      "✅ Order Confirmed!\n\nOrder ##{order_id}\n\n#{item_list}\n\nTotal: $#{total}",
+      [
+        { id: 'track_order', title: '📦 Track Order' },
+        { id: 'contact_support', title: '💬 Contact Support' }
+      ]
+    )
+  end
+
+  def send_appointment_reminder(phone_number, appointment)
+    @client.send_buttons(
+      phone_number,
+      "🏥 Appointment Reminder\n\n#{appointment[:service]} with #{appointment[:provider]}\n📅 #{appointment[:date]}\n🕐 #{appointment[:time]}",
+      [
+        { id: 'confirm', title: '✅ Confirm' },
+        { id: 'reschedule', title: '📅 Reschedule' },
+        { id: 'cancel', title: '❌ Cancel' }
+      ]
+    )
+  end
+end
+```
+
+💡 **See [examples/whatsapp_controller_modes.rb](examples/whatsapp_controller_modes.rb) for comprehensive usage examples.**
+
+## Cross-Platform Compatibility
+
+FlowChat provides a unified API that works across both USSD and WhatsApp platforms, with graceful degradation for platform-specific features:
+
+### Shared Features (Both USSD & WhatsApp)
+- ✅ `app.screen()` - Interactive screens with prompts
+- ✅ `app.say()` - Send messages to users  
+- ✅ `prompt.ask()` - Text input collection
+- ✅ `prompt.select()` - Menu selection (renders as numbered list in USSD, interactive buttons/lists in WhatsApp)
+- ✅ `prompt.yes?()` - Yes/no questions
+- ✅ `app.phone_number` - User's phone number
+- ✅ `app.message_id` - Unique message identifier  
+- ✅ `app.timestamp` - Message timestamp
+
+### WhatsApp-Only Features
+- ✅ `app.contact_name` - WhatsApp contact name (returns `nil` in USSD)
+- ✅ `app.location` - Location sharing data (returns `nil` in USSD)  
+- ✅ `app.media` - Media file attachments (returns `nil` in USSD)
+- ✅ Rich interactive elements (buttons, lists) automatically generated from `prompt.select()`
+
+This design allows you to write flows once and deploy them on both platforms, with WhatsApp users getting enhanced interactive features automatically.
+
+## 📱 Media Support
+
+FlowChat supports rich media attachments for enhanced conversational experiences. Media can be attached to `ask()` and `say()` prompts, with automatic cross-platform optimization.
+
+### Supported Media Types
+
+- **📷 Images** (`type: :image`) - Photos, screenshots, diagrams
+- **📄 Documents** (`type: :document`) - PDFs, forms, receipts  
+- **🎥 Videos** (`type: :video`) - Tutorials, demos, explanations
+- **🎵 Audio** (`type: :audio`) - Voice messages, recordings
+- **😊 Stickers** (`type: :sticker`) - Fun visual elements
+
+### Basic Usage
+
+```ruby
+class ProductFlow < FlowChat::Flow
+  def main_page
+    # ✅ Text input with context image
+    feedback = app.screen(:feedback) do |prompt|
+      prompt.ask "What do you think of our new product?",
+        media: {
+          type: :image,
+          url: "https://cdn.example.com/products/new_product.jpg"
+        }
+    end
+
+    # ✅ Send informational media
+    app.say "Thanks for your feedback! Here's what's coming next:",
+      media: {
+        type: :video,
+        url: "https://videos.example.com/roadmap.mp4"
+      }
+
+    # ✅ Document with filename
+    app.say "Here's your receipt:",
+      media: {
+        type: :document,
+        url: "https://api.example.com/receipt.pdf",
+        filename: "receipt.pdf"
+      }
+  end
+end
+```
+
+### Media Hash Format
+
+```ruby
+{
+  type: :image,        # Required: :image, :document, :audio, :video, :sticker
+  url: "https://...",  # Required: URL to the media file OR WhatsApp media ID
+  filename: "doc.pdf"  # Optional: Only for documents
+}
+```
+
+### Using WhatsApp Media IDs
+
+For better performance and to avoid external dependencies, you can upload files to WhatsApp and use the media ID:
+
+```ruby
+# Upload a file first
+client = FlowChat::Whatsapp::Client.new(config)
+media_id = client.upload_media('path/to/image.jpg', 'image/jpeg')
+
+# Then use the media ID in your flow
+app.screen(:product_demo) do |prompt|
+  prompt.ask "What do you think?",
+    media: {
+      type: :image,
+      url: media_id  # Use the media ID instead of URL
+    }
+end
+```
+
+### Client Media Methods
+
+The WhatsApp client provides methods for uploading and sending media:
+
+```ruby
+client = FlowChat::Whatsapp::Client.new(config)
+
+# Upload media and get media ID
+media_id = client.upload_media('image.jpg', 'image/jpeg')
+media_id = client.upload_media(file_io, 'image/jpeg', 'photo.jpg')
+
+# Send media directly
+client.send_image("+1234567890", "https://example.com/image.jpg", "Caption")
+client.send_image("+1234567890", media_id, "Caption")
+
+# Send document with MIME type and filename
+client.send_document("+1234567890", "https://example.com/doc.pdf", "Your receipt", "receipt.pdf", "application/pdf")
+
+# Send other media types
+client.send_video("+1234567890", "https://example.com/video.mp4", "Demo video", "video/mp4")
+client.send_audio("+1234567890", "https://example.com/audio.mp3", "audio/mpeg")
+client.send_sticker("+1234567890", "https://example.com/sticker.webp", "image/webp")
+```
+
+### Cross-Platform Behavior
+
+**WhatsApp Experience:**
+- Media is sent directly to the chat
+- Prompt text becomes the media caption
+- Rich, native messaging experience
+
+**USSD Experience:**  
+- Media URL is included in text message
+- Graceful degradation with clear media indicators
+- Users can access media via the provided link
+
+```ruby
+# This code works on both platforms:
+app.screen(:help) do |prompt|
+  prompt.ask "Describe your issue:",
+    media: {
+      type: :image,
+      url: "https://support.example.com/help_example.jpg"
+    }
+end
+```
+
+**WhatsApp Result:** Image sent with caption "Describe your issue:"
+
+**USSD Result:** 
+```
+Describe your issue:
+
+📷 Image: https://support.example.com/help_example.jpg
+```
+
 ## Core Concepts
 
 ### Flows and Screens
@@ -228,6 +729,68 @@ app.screen(:credit_card) do |prompt|
 end
 ```
 
+### Background Job Support
+
+For high-volume WhatsApp applications, use background response delivery:
+
+```ruby
+# app/jobs/whatsapp_message_job.rb
+class WhatsappMessageJob < ApplicationJob
+  include FlowChat::Whatsapp::SendJobSupport
+
+  def perform(send_data)
+    perform_whatsapp_send(send_data)
+  end
+end
+
+# config/initializers/flowchat.rb
+FlowChat::Config.whatsapp.message_handling_mode = :background
+FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+
+# config/application.rb
+config.active_job.queue_adapter = :sidekiq
+```
+
+**The `SendJobSupport` module provides:**
+- ✅ **Automatic config resolution** - Resolves named configurations automatically
+- ✅ **Response delivery** - Handles sending responses to WhatsApp
+- ✅ **Error handling** - Comprehensive error handling with user notifications
+- ✅ **Retry logic** - Built-in exponential backoff retry
+- ✅ **Extensible** - Override methods for custom behavior
+
+**How it works:**
+1. **Controller receives webhook** - WhatsApp message arrives
+2. **Flow processes synchronously** - Maintains controller context and session state
+3. **Response queued for delivery** - Only the sending is moved to background
+4. **Job sends response** - Background job handles API call to WhatsApp
+
+**Advanced job with custom callbacks:**
+
+```ruby
+class AdvancedWhatsappMessageJob < ApplicationJob
+  include FlowChat::Whatsapp::SendJobSupport
+
+  def perform(send_data)
+    perform_whatsapp_send(send_data)
+  end
+
+  private
+
+  # Override for custom success handling
+  def on_whatsapp_send_success(send_data, result)
+    Rails.logger.info "Successfully sent WhatsApp message to #{send_data[:msisdn]}"
+    UserEngagementTracker.track_message_sent(phone: send_data[:msisdn])
+  end
+
+  # Override for custom error handling
+  def on_whatsapp_send_error(error, send_data)
+    ErrorTracker.notify(error, user_phone: send_data[:msisdn])
+  end
+end
+```
+
+💡 **See [examples/whatsapp_message_job.rb](examples/whatsapp_message_job.rb) for complete job implementation examples.**
+
 ### Middleware Configuration
 
 FlowChat uses a **middleware architecture** to process USSD requests through a configurable pipeline. Each request flows through multiple middleware layers in a specific order.
@@ -240,7 +803,7 @@ When you run a flow, FlowChat automatically builds this middleware stack:
 User Input → Gateway → Session → Pagination → Custom Middleware → Executor → Flow
 ```
 
-1. **Gateway Middleware** - Handles USSD provider communication (Nalo/Nsano)
+1. **Gateway Middleware** - Handles USSD provider communication (Nalo)
 2. **Session Middleware** - Manages session storage and retrieval
 3. **Pagination Middleware** - Automatically splits long responses across pages
 4. **Custom Middleware** - Your application-specific middleware (optional)
@@ -338,9 +901,6 @@ FlowChat supports multiple USSD gateways:
 ```ruby
 # Nalo Solutions Gateway
 config.use_gateway FlowChat::Ussd::Gateway::Nalo
-
-# Nsano Gateway  
-config.use_gateway FlowChat::Ussd::Gateway::Nsano
 ```
 
 ## Testing
@@ -465,27 +1025,79 @@ class ProcessorMiddlewareTest < Minitest::Test
 end
 ```
 
-### USSD Simulator
+### FlowChat Unified Simulator
 
-Use the built-in simulator for interactive testing:
+Use the built-in unified simulator for interactive testing of both USSD and WhatsApp flows:
 
 ```ruby
-class UssdSimulatorController < ApplicationController
-  include FlowChat::Ussd::Simulator::Controller
+class SimulatorController < ApplicationController
+  include FlowChat::Simulator::Controller
+
+  def index
+    flowchat_simulator
+  end
 
   protected
 
-  def default_endpoint
-    '/ussd'
+  def configurations
+    {
+      production_ussd: {
+        name: "Production USSD",
+        icon: "🏭",
+        processor_type: "ussd",
+        provider: "nalo", 
+        endpoint: "/ussd",
+        color: "#28a745"
+      },
+      staging_whatsapp: {
+        name: "Staging WhatsApp", 
+        icon: "🧪",
+        processor_type: "whatsapp",
+        provider: "cloud_api",
+        endpoint: "/whatsapp/webhook",
+        color: "#17a2b8"
+      },
+      local_ussd: {
+        name: "Local USSD",
+        icon: "💻", 
+        processor_type: "ussd",
+        provider: "nalo",
+        endpoint: "http://localhost:3000/ussd",
+        color: "#6f42c1"
+      }
+    }
   end
 
-  def default_provider
-    :nalo
+  def default_config_key
+    :local_ussd
+  end
+
+  def default_phone_number
+    "+254712345678"
+  end
+
+  def default_contact_name
+    "John Doe"
   end
 end
 ```
 
-Add to routes and visit `http://localhost:3000/ussd_simulator`.
+Add to routes and visit `http://localhost:3000/simulator`.
+
+**Key Features:**
+- 🔄 **Platform Toggle** - Switch between USSD and WhatsApp modes with configuration selection
+- 📱 **USSD Mode** - Classic green-screen terminal simulation with provider support (Nalo, Nsano)
+- 💬 **WhatsApp Mode** - Full WhatsApp interface with interactive buttons, lists, and rich messaging
+- ⚙️ **Multi-Environment** - Support for different configurations (local, staging, production)
+- 🎨 **Modern UI** - Beautiful, responsive interface with real-time status indicators
+- 📊 **Request Logging** - View all HTTP requests and responses in real-time
+- 🔧 **Developer Tools** - Character counts, connection status, and comprehensive error handling
+
+The simulator automatically adapts its interface based on the selected configuration:
+- **USSD**: Shows traditional terminal-style interface with character limits and pagination
+- **WhatsApp**: Displays realistic WhatsApp chat interface with support for interactive elements
+
+💡 **Tip**: See [examples/simulator_controller.rb](examples/simulator_controller.rb) for advanced configurations including multi-tenant support and environment-specific endpoints.
 
 ## Best Practices
 
@@ -554,76 +1166,20 @@ def main_page
 end
 ```
 
-## Configuration
-
-### Session Storage Options
+### 5. Choose the Right WhatsApp Mode
 
-Configure different session storage backends:
+Configure the appropriate mode in your initializer:
 
 ```ruby
-# Rails session (default)
-config.use_session_store FlowChat::Session::RailsSessionStore
-
-# Custom session store
-class MySessionStore
-  def initialize(context)
-    @context = context
-  end
-
-  def get(key)
-    # Your storage logic
-  end
-
-  def set(key, value)
-    # Your storage logic
-  end
-end
-
-config.use_session_store MySessionStore
-```
-
-## Development
-
-### Running Tests
-
-FlowChat uses Minitest for testing:
-
-```bash
-# Run all tests
-bundle exec rake test
-
-# Run specific test file
-bundle exec rake test TEST=test/unit/flow_test.rb
-
-# Run specific test
-bundle exec rake test TESTOPTS="--name=test_flow_initialization"
-```
-
-### Contributing
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Add tests for your changes
-4. Ensure all tests pass (`bundle exec rake test`)
-5. Commit your changes (`git commit -am 'Add amazing feature'`)
-6. Push to the branch (`git push origin feature/amazing-feature`)
-7. Open a Pull Request
-
-## Roadmap
-
-- 📱 **WhatsApp Integration** - Support for WhatsApp Business API
-- 💬 **Telegram Bot Support** - Native Telegram bot integration  
-- 🔄 **Sub-flows** - Reusable conversation components
-- 📊 **Analytics Integration** - Built-in conversation analytics
-- 🌐 **Multi-language Support** - Internationalization features
-- ⚡ **Performance Optimizations** - Improved middleware performance
-
-## License
+# config/initializers/flowchat.rb
 
-FlowChat is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+# Development/Testing - use simulator mode
+FlowChat::Config.whatsapp.message_handling_mode = :simulator
 
-## Support
+# Low-volume Applications - use inline mode  
+FlowChat::Config.whatsapp.message_handling_mode = :inline
 
-- 📖 **Documentation**: [GitHub Repository](https://github.com/radioactive-labs/flow_chat)
-- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/radioactive-labs/flow_chat/issues)
-- 💬 **Community**: Join our discussions for help and feature requests
+# High-volume Production - use background mode (sync processing + async sending)
+FlowChat::Config.whatsapp.message_handling_mode = :background
+FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+```