FlowChat

FlowChat is a powerful Rails framework for building sophisticated conversational interfaces across multiple platforms with a pluggable gateway architecture. Create interactive flows with menus, prompts, validation, media support, and session management using a unified, intuitive API that works across USSD, WhatsApp, Telegram, HTTP, and any custom platforms you build.

✨ Key Features

• 🔄 Unified API: Single codebase that works across all platforms
• 🔌 Pluggable Gateways: Extensible architecture supporting multiple backends per platform
• 📱 Multi-Platform: Out of the box support for USSD, WhatsApp, Telegram, HTTP, and more, with simulator for testing
• 🎯 Screen-Based Navigation: Intuitive screen() method for building conversational flows
• 💾 Advanced Session Management: Flexible session boundaries and storage options
• 🔧 Middleware Architecture: Extensible middleware system for custom processing
• 🎨 Rich Prompts: Support for text, media, selections, yes/no prompts, validation, and transformations
• 📊 Built-in Instrumentation: Comprehensive logging and metrics collection
• 🧪 Testing Support: Built-in simulator for development and testing
• 🏢 Multi-Tenancy: In-built support for custom configuration per tenant and URL-based isolation
• 🚀 Background Processing: Job queue support for WhatsApp messaging

🚀 Quick Start

Installation

Add FlowChat to your Rails application:

# Gemfile
gem 'flow_chat'

bundle install

Define your flow

# app/flow_chat/welcome_flow.rb

class WelcomeFlow < FlowChat::Flow
  def main_page
    name = app.screen(:name) do |prompt|
      prompt.ask "Welcome! What's your name?",
        transform: ->(input) { input.strip.titleize }
    end

    choice = app.screen(:main_menu) do |prompt|
      prompt.select "Hi #{name}! Choose:", {
        "1" => "Account Info",
        "2" => "Make Payment",
        "3" => "Support"
      }
    end

    case choice
    when "1"
      show_account_info
    when "2"
      make_payment  
    when "3"
      app.say "Call us: 123-456-7890"
    end
  end

  # ... implement your flow methods
end

Basic USSD Application

# app/controllers/ussd_controller.rb
class UssdController < ApplicationController
  skip_forgery_protection

  def process_request
    processor = FlowChat::Processor.new(self) do |config|
      config.use_gateway FlowChat::Ussd::Gateway::Nalo
      config.use_session_store FlowChat::Session::CacheSessionStore
    end

    processor.run WelcomeFlow, :main_page
  end
end

Basic WhatsApp Application

# app/controllers/whatsapp_controller.rb
class WhatsappController < ApplicationController
  skip_forgery_protection

  def webhook
    processor = FlowChat::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

Basic Telegram Application

# app/controllers/telegram_controller.rb
class TelegramController < ApplicationController
  skip_forgery_protection

  def webhook
    processor = FlowChat::Processor.new(self) do |config|
      config.use_gateway FlowChat::Telegram::Gateway::BotApi
      config.use_session_store FlowChat::Session::CacheSessionStore
    end

    processor.run WelcomeFlow, :main_page
  end
end

Basic HTTP API Application

# app/controllers/api_controller.rb
class ApiController < ApplicationController
  def chat
    processor = FlowChat::Processor.new(self) do |config|
      config.use_gateway FlowChat::Http::Gateway::Simple
      config.use_session_store FlowChat::Session::CacheSessionStore
    end

    processor.run WelcomeFlow, :main_page
  end
end

Same WelcomeFlow works across ALL platforms!

🏗️ Architecture

FlowChat uses a composition-based architecture with these core components:

• Processor: Orchestrates request processing through middleware stack
• Gateway: Platform-specific request/response handling (Nalo, WhatsApp Cloud API)
• App: Unified application interface with screen-based navigation
• Session: Flexible session management with configurable boundaries
• Middleware: Extensible processing pipeline

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│   Gateway   │ -> │ Session      │ -> │ Custom      │
│             │    │ Middleware   │    │ Middleware  │
└─────────────┘    └──────────────┘    └─────────────┘
                                              │
                                              v
┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│ Flow/Action │ <- │   Executor   │ <- │     App     │
│             │    │              │    │             │
└─────────────┘    └──────────────┘    └─────────────┘

🔌 Pluggable Gateway Architecture

FlowChat's power comes from its pluggable gateway system. Each platform can have multiple gateway implementations:

# Create your own SMS gateway
class MyCompany::Sms::Gateway::Twilio
  def initialize(app, config)
    @app = app
    @config = config
  end

  def call(context)
    # Parse Twilio webhook, set context values
    context["request.msisdn"] = params["From"]
    context["request.platform"] = :sms
    context.input = params["Body"]
    
    # Process through middleware
    type, prompt, choices, media = @app.call(context)
    
    # Send response via Twilio API
    send_sms_response(prompt, to: context["request.msisdn"])
  end

  # Optional: Configure platform-specific middleware
  def self.configure_middleware_stack(builder, custom_middleware)
    builder.use MyCompany::Sms::MessageTransformMiddleware
    builder.use custom_middleware
  end
end

# Use your custom gateway
processor = FlowChat::Processor.new(self) do |config|
  config.use_gateway MyCompany::Sms::Gateway::Twilio, sms_config
end

📚 Documentation

Getting Started

• Getting Started Guide - Comprehensive setup and first app
• Architecture Overview - Deep dive into FlowChat's design
• Configuration - Complete configuration reference

Platform Guides

• USSD Development - USSD-specific features and examples
• WhatsApp Development - WhatsApp Business API integration
• Telegram Development - Telegram Bot API integration
• HTTP Development 🚧 - API endpoints and webhooks
• Multi-Platform Apps 🚧 - Building unified experiences

Advanced Topics

• Gateway Development - Creating custom gateways and platforms
• Session Management 🚧 - Session boundaries and storage
• Middleware Development 🚧 - Creating custom middleware
• Testing & Simulation - Testing strategies and simulator usage
• Background Jobs 🚧 - Async processing for WhatsApp
• Instrumentation - Monitoring, logging, and error tracking

API Reference

• Core API 🚧 - Processor, App, Flow classes
• Prompts & Validation 🚧 - Interactive prompts and validation
• Gateways 🚧 - Platform gateway interfaces
• Session Stores 🚧 - Session storage options

🎯 Core Concepts

Screen-Based Navigation

Build conversational flows using the intuitive screen() method:

def registration_flow
  # Each screen automatically handles state and navigation
  email = app.screen(:email) do |prompt|
    prompt.ask "Enter your email:",
      validate: ->(input) { 
        "Invalid email" unless input.include?("@")
      }
  end

  name = app.screen(:name) do |prompt|
    prompt.ask "Enter your full name:",
      transform: ->(input) { input.strip.titleize }
  end

  # Confirmation screen with rich prompts
  confirmed = app.screen(:confirm) do |prompt|
    prompt.yes? "Confirm registration for #{name} (#{email})?"
  end

  if confirmed
    create_user(name, email)
    app.say "Welcome #{name}! Registration complete."
  else
    app.say "Registration cancelled."
  end
end

Multi-Platform Compatibility

Write once, run everywhere:

class MenuFlow < FlowChat::Flow
  def main_menu
    choice = app.screen(:menu) do |prompt|
      prompt.select "Choose an option:", {
        "info" => "📋 Information",      # Rich for WhatsApp
        "help" => "❓ Help",             # Falls back to text for USSD  
        "exit" => "👋 Exit"
      }
    end
    
    # Same logic works on both platforms
    handle_choice(choice)
  end
end

Flexible Session Management

Configure sessions for your use case:

# Durable sessions across timeouts
processor = FlowChat::Processor.new(self) do |config|
  config.use_durable_sessions  # Uses user identifier (usually phone number) for session ID
end

# Cross-platform sessions
processor = FlowChat::Processor.new(self) do |config|
  config.use_cross_platform_sessions  # Share sessions between platforms (e.g. USSD & WhatsApp)
end

# URL-based multi-tenancy
processor = FlowChat::Processor.new(self) do |config|
  config.use_url_isolation  # tenant1.app.com vs tenant2.app.com
end

🛠️ Supported Platforms & Gateways

Platform	Available Gateways	Features
USSD	Nalo ✅, Custom	Pagination, choice mapping, session management
WhatsApp	CloudApi ✅, Custom	Rich media, buttons, lists, templates, background jobs
Telegram	BotApi ✅, Custom	Inline keyboards, rich media, callbacks, group chats
HTTP	Simple ✅, Custom	Testing, webhooks, API endpoints, JSON responses
Simulator	Built-in ✅	Development testing, conversation replay, flow debugging
Custom	Your Gateway	Implement any platform by creating a gateway class

✅ = Included with FlowChat

Gateway Examples

# Built-in gateways (included with FlowChat)
config.use_gateway FlowChat::Ussd::Gateway::Nalo
config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, whatsapp_config
config.use_gateway FlowChat::Telegram::Gateway::BotApi, telegram_config
config.use_gateway FlowChat::Http::Gateway::Simple

# Custom gateway examples (you would build these)
config.use_gateway MyCompany::Sms::Gateway::Twilio, twilio_config
config.use_gateway MyCompany::Slack::Gateway::BoltJS, slack_config

📦 Example Applications

• USSD Banking App 🚧 - Complete banking flow with validation
• WhatsApp Customer Service 🚧 - Media support and templates
• HTTP API Chatbot 🚧 - JSON API for web/mobile integration
• Multi-Platform E-commerce 🚧 - Unified shopping across USSD, WhatsApp, and HTTP
• Multi-Tenant SaaS 🚧 - URL-based tenant isolation
• Custom Gateway Example 🚧 - Building a Telegram gateway

🧪 Testing & Development

FlowChat includes a built-in simulator interface for easy development and testing:

# Simulator is automatically enabled in development
processor = FlowChat::Processor.new(self) do |config|
  config.use_gateway FlowChat::Ussd::Gateway::Nalo  # or any gateway
end

# Explicitly control simulator mode if needed
processor = FlowChat::Processor.new(self, enable_simulator: false) do |config|
  # Disable simulator even in development
end

The simulator provides a web interface for testing your flows during development. It works the same regardless of which gateway you're using, allowing you to test your conversational logic before deploying to actual platforms.

Learn more: Testing & Simulation Guide

🤝 Contributing

We welcome contributions!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

FlowChat is released under the MIT License.

🆘 Support

• Documentation: Comprehensive guides in the docs/ directory
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🏢 Commercial Support

FlowChat is developed by Radioactive Labs. Commercial support, custom development, and consulting services are available.

---

Ready to build amazing conversational experiences? Check out the Getting Started Guide to create your first FlowChat application.