flow_chat

FlowChat

FlowChat is a Rails framework for building sophisticated conversational workflows for USSD and WhatsApp messaging. Define multi-step conversations as Ruby classes with automatic session management, input validation, and cross-platform compatibility.

Key Features

• 🎯 Declarative Flow Definition - Define conversations as Ruby classes
• 🔄 Automatic Session Management - Persistent state across requests
• ✅ Input Validation & Transformation - Built-in validation and data conversion
• 📱 USSD & WhatsApp Support - Single codebase, multiple platforms
• 💬 Rich WhatsApp Features - Interactive buttons, lists, media support
• 🔧 Standalone WhatsApp Client - Send messages outside of flows
• 📊 Built-in Instrumentation - Monitoring and metrics out of the box
• 🧪 Testing Tools - Built-in simulator for development and testing

Installation

Add to your Gemfile:

gem 'flow_chat'

Then run:

bundle install

Quick Start

USSD Example

Create a flow in app/flow_chat/welcome_flow.rb:

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

    language = app.screen(:language) do |prompt|
      prompt.select "Choose language:", ["English", "French", "Spanish"]
    end

    app.say "Hello #{name}! Language set to #{language}."
  end
end

Create a controller:

class UssdController < ApplicationController
  skip_forgery_protection

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

Add route in config/routes.rb:

  post 'ussd' => 'ussd#process_request'

WhatsApp Example

Configure credentials in config/credentials.yml.enc:

whatsapp:
  access_token: "your_access_token"
  phone_number_id: "your_phone_number_id"
  verify_token: "your_verify_token"
  app_secret: "your_app_secret"

Create a controller:

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

Add route:

  match '/whatsapp/webhook', to: 'whatsapp#webhook', via: [:get, :post]

Core Concepts

Flows and Screens

Flows define conversation logic. Screens collect user input with automatic validation:

class RegistrationFlow < FlowChat::Flow
  def main_page
email = app.screen(:email) do |prompt|
      prompt.ask "Enter email:",
        validate: ->(input) { "Invalid email" unless input.include?("@") },
        transform: ->(input) { input.downcase.strip }
    end

confirmed = app.screen(:confirm) do |prompt|
      prompt.yes? "Create account for #{email}?"
end

if confirmed
      create_account(email)
      app.say "Account created successfully!"
    else
      app.say "Registration cancelled."
    end
  end
end

Input Methods

• prompt.ask() - Free-form input with optional validation
• prompt.select() - Force selection from predefined options
• prompt.yes?() - Simple yes/no questions

WhatsApp Client

Send messages outside of flows:

config = FlowChat::Whatsapp::Configuration.from_credentials
client = FlowChat::Whatsapp::Client.new(config)

# Send messages
client.send_text("[phone]", "Hello!")
client.send_buttons("[phone]", "Choose:", [
  { id: 'option1', title: 'Option 1' },
  { id: 'option2', title: 'Option 2' }
])

Testing Simulator

FlowChat includes a powerful built-in simulator with a modern web interface for testing both USSD and WhatsApp flows:

Features:

• 📱 Visual Interface - Phone-like display with real conversation flow
• 🔄 Environment Switching - Toggle between USSD and WhatsApp modes
• 📊 Request Logging - Real-time HTTP request/response monitoring
• 🎯 Interactive Testing - Test flows with character counting and validation
• 🛠️ Developer Tools - Session management and connection status

See the Testing Guide for complete setup instructions and testing strategies.

Documentation

• WhatsApp Setup - Comprehensive WhatsApp configuration
• USSD Setup - USSD gateway configuration and examples
• Flow Development - Advanced flow patterns and techniques
• Session Management - Session architecture and configuration
• Media Support - Rich media handling for WhatsApp
• Testing Guide - Complete testing strategies
• Configuration Reference - All configuration options
• Instrumentation - Monitoring and metrics
• Security - Security best practices
• Examples - Complete working examples

Examples

See the examples directory for complete implementations:

• USSD Controller - Full USSD implementation
• WhatsApp Controller - Basic WhatsApp setup
• Multi-tenant WhatsApp - Advanced WhatsApp
• Background Jobs - Async message processing
• Simulator Controller - Testing setup

License

The gem is available as open source under the terms of the MIT License.