{"id":24922426,"url":"https://github.com/radioactive-labs/flow_chat","last_synced_at":"2025-10-24T22:16:14.049Z","repository":{"id":37387940,"uuid":"505707411","full_name":"radioactive-labs/flow_chat","owner":"radioactive-labs","description":"Framework for building Menu based conversations (e.g. USSD) in Rails.","archived":false,"fork":false,"pushed_at":"2024-04-05T15:35:28.000Z","size":95,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-05T05:07:29.843Z","etag":null,"topics":["chatbot","rails","telegram-bot","ussd","ussd-menu-builder","whatsapp"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/flow_chat","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/radioactive-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-06-21T05:50:21.000Z","updated_at":"2025-01-27T12:05:02.000Z","dependencies_parsed_at":"2024-04-05T13:45:53.813Z","dependency_job_id":"0cf1bc13-c27f-4ac9-9f82-b3198bd1b529","html_url":"https://github.com/radioactive-labs/flow_chat","commit_stats":null,"previous_names":["radioactive-labs/flow_chat"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radioactive-labs%2Fflow_chat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radioactive-labs%2Fflow_chat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radioactive-labs%2Fflow_chat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radioactive-labs%2Fflow_chat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/radioactive-labs","download_url":"https://codeload.github.com/radioactive-labs/flow_chat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248090420,"owners_count":21046089,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","rails","telegram-bot","ussd","ussd-menu-builder","whatsapp"],"created_at":"2025-02-02T11:19:38.318Z","updated_at":"2025-10-24T22:16:14.043Z","avatar_url":"https://github.com/radioactive-labs.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FlowChat\n\n[![CI](https://github.com/radioactive-labs/flow_chat/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/radioactive-labs/flow_chat/actions/workflows/ci.yml)\n[![Gem Version](https://badge.fury.io/rb/flow_chat.svg)](https://badge.fury.io/rb/flow_chat)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.3.0-red.svg)](https://www.ruby-lang.org/)\n[![Rails](https://img.shields.io/badge/rails-%3E%3D%206.0-red.svg)](https://rubyonrails.org/)\n\nFlowChat 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.\n\n## Key Features\n\n- 🎯 **Declarative Flow Definition** - Define conversations as Ruby classes\n- 🔄 **Automatic Session Management** - Persistent state across requests  \n- ✅ **Input Validation \u0026 Transformation** - Built-in validation and data conversion\n- 📱 **USSD \u0026 WhatsApp Support** - Single codebase, multiple platforms\n- 💬 **Rich WhatsApp Features** - Interactive buttons, lists, media support\n- 🔧 **Standalone WhatsApp Client** - Send messages outside of flows\n- 📊 **Built-in Instrumentation** - Monitoring and metrics out of the box\n- 🧪 **Testing Tools** - Built-in simulator for development and testing\n\n## Installation\n\nAdd to your Gemfile:\n\n```ruby\ngem 'flow_chat'\n```\n\nThen run:\n\n```bash\nbundle install\n```\n\n## Quick Start\n\n### USSD Example\n\nCreate a flow in `app/flow_chat/welcome_flow.rb`:\n\n```ruby\nclass WelcomeFlow \u003c FlowChat::Flow\n  def main_page\n    name = app.screen(:name) do |prompt|\n      prompt.ask \"What's your name?\",\n        transform: -\u003e(input) { input.strip.titleize }\n    end\n\n    language = app.screen(:language) do |prompt|\n      prompt.select \"Choose language:\", [\"English\", \"French\", \"Spanish\"]\n    end\n\n    app.say \"Hello #{name}! Language set to #{language}.\"\n  end\nend\n```\n\nCreate a controller:\n\n```ruby\nclass UssdController \u003c ApplicationController\n  skip_forgery_protection\n\n  def process_request\n    processor = FlowChat::Ussd::Processor.new(self) do |config|\n      config.use_gateway FlowChat::Ussd::Gateway::Nalo\n      config.use_session_store FlowChat::Session::CacheSessionStore\n    end\n\n    processor.run WelcomeFlow, :main_page\n  end\nend\n```\n\nAdd route in `config/routes.rb`:\n\n```ruby\n  post 'ussd' =\u003e 'ussd#process_request'\n```\n\n### WhatsApp Example\n\nConfigure credentials in `config/credentials.yml.enc`:\n\n```yaml\nwhatsapp:\n  access_token: \"your_access_token\"\n  phone_number_id: \"your_phone_number_id\"\n  verify_token: \"your_verify_token\"\n  app_secret: \"your_app_secret\"\n```\n\nCreate a controller:\n\n```ruby\nclass WhatsappController \u003c ApplicationController\n  skip_forgery_protection\n\n  def webhook\n    processor = FlowChat::Whatsapp::Processor.new(self) do |config|\n      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi\n      config.use_session_store FlowChat::Session::CacheSessionStore\n    end\n\n    processor.run WelcomeFlow, :main_page\n  end\nend\n```\n\nAdd route:\n\n```ruby\n  match '/whatsapp/webhook', to: 'whatsapp#webhook', via: [:get, :post]\n```\n\n## Core Concepts\n\n### Flows and Screens\n\n**Flows** define conversation logic. **Screens** collect user input with automatic validation:\n\n```ruby\nclass RegistrationFlow \u003c FlowChat::Flow\n  def main_page\nemail = app.screen(:email) do |prompt|\n      prompt.ask \"Enter email:\",\n        validate: -\u003e(input) { \"Invalid email\" unless input.include?(\"@\") },\n        transform: -\u003e(input) { input.downcase.strip }\n    end\n\nconfirmed = app.screen(:confirm) do |prompt|\n      prompt.yes? \"Create account for #{email}?\"\nend\n\nif confirmed\n      create_account(email)\n      app.say \"Account created successfully!\"\n    else\n      app.say \"Registration cancelled.\"\n    end\n  end\nend\n```\n\n### Input Methods\n\n- **`prompt.ask()`** - Free-form input with optional validation\n- **`prompt.select()`** - Force selection from predefined options  \n- **`prompt.yes?()`** - Simple yes/no questions\n\n## WhatsApp Client\n\nSend messages outside of flows:\n\n```ruby\nconfig = FlowChat::Whatsapp::Configuration.from_credentials\nclient = FlowChat::Whatsapp::Client.new(config)\n\n# Send messages\nclient.send_text(\"+1234567890\", \"Hello!\")\nclient.send_buttons(\"+1234567890\", \"Choose:\", [\n  { id: 'option1', title: 'Option 1' },\n  { id: 'option2', title: 'Option 2' }\n])\n```\n\n## Testing Simulator\n\nFlowChat includes a powerful built-in simulator with a modern web interface for testing both USSD and WhatsApp flows:\n\n![FlowChat Simulator](docs/images/simulator.png)\n\nFeatures:\n- 📱 **Visual Interface** - Phone-like display with real conversation flow\n- 🔄 **Environment Switching** - Toggle between USSD and WhatsApp modes\n- 📊 **Request Logging** - Real-time HTTP request/response monitoring\n- 🎯 **Interactive Testing** - Test flows with character counting and validation\n- 🛠️ **Developer Tools** - Session management and connection status\n\nSee the [Testing Guide](docs/testing.md) for complete setup instructions and testing strategies.\n\n\n## Documentation\n\n- **[WhatsApp Setup](docs/whatsapp-setup.md)** - Comprehensive WhatsApp configuration\n- **[USSD Setup](docs/ussd-setup.md)** - USSD gateway configuration and examples\n- **[Flow Development](docs/flows.md)** - Advanced flow patterns and techniques\n- **[Session Management](docs/sessions.md)** - Session architecture and configuration\n- **[Media Support](docs/media.md)** - Rich media handling for WhatsApp\n- **[Testing Guide](docs/testing.md)** - Complete testing strategies\n- **[Configuration Reference](docs/configuration.md)** - All configuration options\n- **[Instrumentation](docs/instrumentation.md)** - Monitoring and metrics\n- **[Security](docs/security.md)** - Security best practices\n- **[Examples](examples/)** - Complete working examples\n\n## Examples\n\nSee the [examples directory](examples/) for complete implementations:\n\n- **[USSD Controller](examples/ussd_controller.rb)** - Full USSD implementation\n- **[WhatsApp Controller](examples/whatsapp_controller.rb)** - Basic WhatsApp setup\n- **[Multi-tenant WhatsApp](examples/multi_tenant_whatsapp_controller.rb)** - Advanced WhatsApp\n- **[Background Jobs](examples/whatsapp_message_job.rb)** - Async message processing\n- **[Simulator Controller](examples/simulator_controller.rb)** - Testing setup\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradioactive-labs%2Fflow_chat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fradioactive-labs%2Fflow_chat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradioactive-labs%2Fflow_chat/lists"}