flow_chat 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31c7630d410bbcff17307ade16634f5d5c9662f91eeeab8365b98681886de6b3
-  data.tar.gz: 4a7d4059a7a60dee5af2b189fa33c4638a439af903a72f38ffa5a67f9325115d
+  metadata.gz: e4bd1ce536b9d214041fdd2926426449969918262f04829aca7f7e7251b8b4b6
+  data.tar.gz: 989238eac1d423e28d4139d2267200cea86e666992b400e8d2299b0ddc1ed8bf
 SHA512:
-  metadata.gz: 6040ccd725fa1a24b7ff46b5d288e11a1f1a4a2d58b4e773a843153a7d2cf3fb7c1fd7971dd27ed2bc938bf12da17a42b9bdbee9db06152507051eca57592fdb
-  data.tar.gz: 002d2fc1f5b6ea0b20e4229220801bc94311b5237ce24891a571f6f544abaf072a6fdf71de15632069a40d1b29b58e349f937b80ff3975f97bd3a607053b2c39
+  metadata.gz: a26004d9e08aa4244f24f8ea57e6529699f827ca6d009042db0028bba611cbc5077ad39a11d654c9f4e6b3125881ff72893695f00c3d197a786770e484b209ac
+  data.tar.gz: e22bbf5a0ec53174e44b4eb1d5d453a6d9f3e5b2dd8107d1d14039fc315235aa28c3bbfb7877f882795fd3e978ddedf8deddd836a99d1c551f311c6410e55ea8

data/README.md

@@ -1,13 +1,14 @@
 # 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
+- 📱 **USSD Gateway Support** - Currently supports Nalo gateways
+- 💬 **WhatsApp Integration** - Full WhatsApp Cloud API support with interactive messages
 - 🧪 **Built-in Testing Tools** - USSD simulator for local development
 
 ## Architecture Overview
@@ -21,9 +22,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 +44,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 +65,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 +94,233 @@ 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_whatsapp_config(custom_config)  # Pass custom config
+  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+  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. Create WhatsApp Controller
+
+```ruby
+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
+```
+
+### 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).
+
+## 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.
+
 ## Core Concepts
 
 ### Flows and Screens
@@ -240,7 +472,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 +570,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
@@ -556,12 +785,32 @@ end
 
 ## Configuration
 
+### Cache Configuration
+
+The `CacheSessionStore` requires a cache to be configured. Set it up in your Rails application:
+
+```ruby
+# config/application.rb or config/environments/*.rb
+FlowChat::Config.cache = Rails.cache
+
+# Or use a specific cache store
+FlowChat::Config.cache = ActiveSupport::Cache::MemoryStore.new
+
+# For Redis (requires redis gem)
+FlowChat::Config.cache = ActiveSupport::Cache::RedisCacheStore.new(url: "redis://localhost:6379/1")
+```
+
+💡 **Tip**: See [examples/initializer.rb](examples/initializer.rb) for a complete configuration example.
+
 ### Session Storage Options
 
 Configure different session storage backends:
 
 ```ruby
-# Rails session (default)
+# Cache session store (default) - uses FlowChat::Config.cache
+config.use_session_store FlowChat::Session::CacheSessionStore
+
+# Rails session (for USSD)
 config.use_session_store FlowChat::Session::RailsSessionStore
 
 # Custom session store
@@ -611,12 +860,13 @@ bundle exec rake test TESTOPTS="--name=test_flow_initialization"
 
 ## 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
+- 🔄 **Sub-flows** - Reusable conversation components and flow composition
+- 📊 **Analytics Integration** - Built-in conversation analytics and user journey tracking
+- 🌐 **Multi-language Support** - Internationalization and localization features
+- ⚡ **Performance Optimizations** - Improved middleware performance and caching
+- 🎯 **Advanced Validation** - More validation helpers and custom validators
+- 🔐 **Enhanced Security** - Rate limiting, input sanitization, and fraud detection
 
 ## License
 
@@ -626,4 +876,4 @@ FlowChat is available as open source under the terms of the [MIT License](https:
 
 - 📖 **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
+- 💬 **Community**: Join our discussions for help and feature requests

data/examples/initializer.rb

@@ -0,0 +1,31 @@
+# Example FlowChat Initializer
+# Add this to your Rails application as config/initializers/flow_chat.rb
+
+# Configure cache for session storage
+# This is required when using FlowChat::Session::CacheSessionStore
+FlowChat::Config.cache = Rails.cache
+
+# Alternative cache configurations:
+
+# Use a specific cache store
+# FlowChat::Config.cache = ActiveSupport::Cache::MemoryStore.new
+
+# Use Redis (requires redis gem)
+# FlowChat::Config.cache = ActiveSupport::Cache::RedisCacheStore.new(url: "redis://localhost:6379/1")
+
+# Use Memcached (requires dalli gem)
+# FlowChat::Config.cache = ActiveSupport::Cache::MemCacheStore.new("localhost:11211")
+
+# Configure logger (optional)
+FlowChat::Config.logger = Rails.logger
+
+# Configure USSD pagination (optional)
+FlowChat::Config.ussd.pagination_page_size = 140
+FlowChat::Config.ussd.pagination_back_option = "0"
+FlowChat::Config.ussd.pagination_back_text = "Back"
+FlowChat::Config.ussd.pagination_next_option = "#"
+FlowChat::Config.ussd.pagination_next_text = "More"
+
+# Configure resumable sessions (optional)
+FlowChat::Config.ussd.resumable_sessions_enabled = true
+FlowChat::Config.ussd.resumable_sessions_timeout_seconds = 300 # 5 minutes 

data/examples/multi_tenant_whatsapp_controller.rb

@@ -0,0 +1,248 @@
+# Example Multi-Tenant WhatsApp Controller
+# This shows how to configure different WhatsApp accounts per tenant/client
+
+class MultiTenantWhatsappController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    # Determine tenant from subdomain, path, or other logic
+    tenant = determine_tenant(request)
+    
+    # Get tenant-specific WhatsApp configuration
+    whatsapp_config = get_whatsapp_config_for_tenant(tenant)
+    
+    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+      config.use_whatsapp_config(whatsapp_config)
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    # Use tenant-specific flow
+    flow_class = get_flow_for_tenant(tenant)
+    processor.run flow_class, :main_page
+  end
+
+  private
+
+  def determine_tenant(request)
+    # Option 1: From subdomain
+    return request.subdomain if request.subdomain.present?
+    
+    # Option 2: From path
+    tenant_from_path = request.path.match(%r{^/whatsapp/(\w+)/})&.captures&.first
+    return tenant_from_path if tenant_from_path
+    
+    # Option 3: From custom header
+    return request.headers['X-Tenant-ID'] if request.headers['X-Tenant-ID']
+    
+    # Fallback to default
+    'default'
+  end
+
+  def get_whatsapp_config_for_tenant(tenant)
+    case tenant
+    when 'acme_corp'
+      FlowChat::Whatsapp::Configuration.new.tap do |config|
+        config.access_token = ENV['ACME_WHATSAPP_ACCESS_TOKEN']
+        config.phone_number_id = ENV['ACME_WHATSAPP_PHONE_NUMBER_ID']
+        config.verify_token = ENV['ACME_WHATSAPP_VERIFY_TOKEN']
+        config.app_id = ENV['ACME_WHATSAPP_APP_ID']
+        config.app_secret = ENV['ACME_WHATSAPP_APP_SECRET']
+        config.business_account_id = ENV['ACME_WHATSAPP_BUSINESS_ACCOUNT_ID']
+      end
+    
+    when 'tech_startup'
+      FlowChat::Whatsapp::Configuration.new.tap do |config|
+        config.access_token = ENV['TECHSTARTUP_WHATSAPP_ACCESS_TOKEN']
+        config.phone_number_id = ENV['TECHSTARTUP_WHATSAPP_PHONE_NUMBER_ID']
+        config.verify_token = ENV['TECHSTARTUP_WHATSAPP_VERIFY_TOKEN']
+        config.app_id = ENV['TECHSTARTUP_WHATSAPP_APP_ID']
+        config.app_secret = ENV['TECHSTARTUP_WHATSAPP_APP_SECRET']
+        config.business_account_id = ENV['TECHSTARTUP_WHATSAPP_BUSINESS_ACCOUNT_ID']
+      end
+      
+    when 'retail_store'
+      # Load from database
+      tenant_config = WhatsappConfiguration.find_by(tenant: tenant)
+      FlowChat::Whatsapp::Configuration.new.tap do |config|
+        config.access_token = tenant_config.access_token
+        config.phone_number_id = tenant_config.phone_number_id
+        config.verify_token = tenant_config.verify_token
+        config.app_id = tenant_config.app_id
+        config.app_secret = tenant_config.app_secret
+        config.business_account_id = tenant_config.business_account_id
+      end
+      
+    else
+      # Use default/global configuration
+      FlowChat::Whatsapp::Configuration.from_credentials
+    end
+  end
+
+  def get_flow_for_tenant(tenant)
+    case tenant
+    when 'acme_corp'
+      AcmeCorpFlow
+    when 'tech_startup'
+      TechStartupFlow
+    when 'retail_store'
+      RetailStoreFlow
+    else
+      WelcomeFlow  # Default flow
+    end
+  end
+end
+
+# Example: Dynamic Configuration from Database
+class DatabaseWhatsappController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    # Get account from business phone number or other identifier
+    business_account = find_business_account(params)
+    
+    if business_account.nil?
+      return head :not_found
+    end
+
+    # Create configuration from database record
+    whatsapp_config = FlowChat::Whatsapp::Configuration.new.tap do |config|
+      config.access_token = business_account.whatsapp_access_token
+      config.phone_number_id = business_account.whatsapp_phone_number_id
+      config.verify_token = business_account.whatsapp_verify_token
+      config.app_id = business_account.whatsapp_app_id
+      config.app_secret = business_account.whatsapp_app_secret
+      config.business_account_id = business_account.whatsapp_business_account_id
+    end
+
+    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+      config.use_whatsapp_config(whatsapp_config)
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run business_account.flow_class.constantize, :main_page
+  end
+
+  private
+
+  def find_business_account(params)
+    # You could identify the account by:
+    # 1. Phone number ID from webhook
+    # 2. Business account ID from webhook
+    # 3. Custom routing parameter
+    
+    # Example: Find by phone number ID in webhook
+    phone_number_id = extract_phone_number_id_from_webhook(params)
+    BusinessAccount.find_by(whatsapp_phone_number_id: phone_number_id)
+  end
+
+  def extract_phone_number_id_from_webhook(params)
+    # Extract from webhook payload structure
+    # This would need to be implemented based on your webhook structure
+    nil
+  end
+end
+
+# Example: Environment-based Configuration
+class EnvironmentWhatsappController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    # Different configurations for different environments
+    whatsapp_config = case Rails.env
+    when 'production'
+      production_whatsapp_config
+    when 'staging'
+      staging_whatsapp_config
+    when 'development'
+      development_whatsapp_config
+    else
+      FlowChat::Whatsapp::Configuration.from_credentials
+    end
+
+    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+      config.use_whatsapp_config(whatsapp_config)
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+
+  private
+
+  def production_whatsapp_config
+    FlowChat::Whatsapp::Configuration.new.tap do |config|
+      config.access_token = ENV['PROD_WHATSAPP_ACCESS_TOKEN']
+      config.phone_number_id = ENV['PROD_WHATSAPP_PHONE_NUMBER_ID']
+      config.verify_token = ENV['PROD_WHATSAPP_VERIFY_TOKEN']
+      config.app_id = ENV['PROD_WHATSAPP_APP_ID']
+      config.app_secret = ENV['PROD_WHATSAPP_APP_SECRET']
+      config.business_account_id = ENV['PROD_WHATSAPP_BUSINESS_ACCOUNT_ID']
+    end
+  end
+
+  def staging_whatsapp_config
+    FlowChat::Whatsapp::Configuration.new.tap do |config|
+      config.access_token = ENV['STAGING_WHATSAPP_ACCESS_TOKEN']
+      config.phone_number_id = ENV['STAGING_WHATSAPP_PHONE_NUMBER_ID']
+      config.verify_token = ENV['STAGING_WHATSAPP_VERIFY_TOKEN']
+      config.app_id = ENV['STAGING_WHATSAPP_APP_ID']
+      config.app_secret = ENV['STAGING_WHATSAPP_APP_SECRET']
+      config.business_account_id = ENV['STAGING_WHATSAPP_BUSINESS_ACCOUNT_ID']
+    end
+  end
+
+  def development_whatsapp_config
+    FlowChat::Whatsapp::Configuration.new.tap do |config|
+      config.access_token = ENV['DEV_WHATSAPP_ACCESS_TOKEN']
+      config.phone_number_id = ENV['DEV_WHATSAPP_PHONE_NUMBER_ID']
+      config.verify_token = ENV['DEV_WHATSAPP_VERIFY_TOKEN']
+      config.app_id = ENV['DEV_WHATSAPP_APP_ID']
+      config.app_secret = ENV['DEV_WHATSAPP_APP_SECRET']
+      config.business_account_id = ENV['DEV_WHATSAPP_BUSINESS_ACCOUNT_ID']
+    end
+  end
+end
+
+# Example: Simple Custom Configuration
+class CustomWhatsappController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    # Create custom configuration for this specific endpoint
+    my_config = FlowChat::Whatsapp::Configuration.new
+    my_config.access_token = "EAABs..." # Your specific access token
+    my_config.phone_number_id = "123456789"
+    my_config.verify_token = "my_verify_token"
+    my_config.app_id = "your_app_id"
+    my_config.app_secret = "your_app_secret"
+    my_config.business_account_id = "your_business_account_id"
+
+    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+      config.use_whatsapp_config(my_config)
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run CustomFlow, :main_page
+  end
+end
+
+# Add routes for different tenants:
+# Rails.application.routes.draw do
+#   # Subdomain-based routing
+#   constraints subdomain: /\w+/ do
+#     post '/whatsapp/webhook', to: 'multi_tenant_whatsapp#webhook'
+#   end
+#   
+#   # Path-based routing  
+#   post '/whatsapp/:tenant/webhook', to: 'multi_tenant_whatsapp#webhook'
+#   
+#   # Environment-specific
+#   post '/whatsapp/env/webhook', to: 'environment_whatsapp#webhook'
+#   
+#   # Custom endpoint
+#   post '/whatsapp/custom/webhook', to: 'custom_whatsapp#webhook'
+# end