RailsChatbot

A powerful Rails engine gem that provides an intelligent chatbot system with knowledge base integration for your Ruby on Rails application. The chatbot can answer questions about your application by indexing your models and content.

Add this line to your application's Gemfile:

gem "rails_chatbot"

Then execute:

$ bundle install

$ rails rails_chatbot:install:migrations
$ rails db:migrate

Create config/initializers/rails_chatbot.rb:

RailsChatbot.configure do |config|
  config.openai_api_key = ENV['OPENAI_API_KEY'] # Required
  config.openai_model = 'gpt-4o-mini' # Optional
  config.chatbot_title = 'My App Assistant' # Optional
end

Set your OpenAI API key:

export OPENAI_API_KEY=your_openai_api_key_here

Add to your config/routes.rb:

Rails.application.routes.draw do
  mount RailsChatbot::Engine => "/chatbot"
  
  # Your other routes...
end

To enable the floating chatbot widget, add this to your application layout:

<%# In app/views/layouts/application.html.erb %>
<%= RailsChatbot::ApplicationHelper.new.include_chatbot_widget if RailsChatbot::ApplicationHelper.new.chatbot_widget_enabled? %>

Or simply add to any view:

<%= include_chatbot_widget %>

The widget will automatically appear in the bottom-right corner of your screen.

rails server

Visit http://localhost:3000/chatbot to see your chatbot, or look for the floating chat icon in the bottom-right corner of any page!

• Open http://localhost:3000/chatbot
• Type "Hello" and send a message
• The chatbot should respond

# Add custom knowledge
rails runner "RailsChatbot::KnowledgeIndexer.add_custom_knowledge(
  title: 'User Registration',
  content: 'Users can register by clicking the Sign Up button...',
  source_type: 'help'
)"

In the chat, try asking:

• "How do users register?"
• "What features are available?"
• "Tell me about user management"

# Test search
curl "http://localhost:3000/chatbot/search?q=user"

# Test conversation creation
curl -X POST "http://localhost:3000/chatbot/conversations" \
  -H "Content-Type: application/json" \
  -d '{}'

rake app:rails_chatbot:stats

# Index specific models
rake app:rails_chatbot:index_models[User,Post,Product]

# Index all models
rake app:rails_chatbot:index_all

# Via code
RailsChatbot::KnowledgeBase.create!(
  title: "How to Reset Password",
  content: "Click 'Forgot Password' on the login page...",
  source_type: "help"
)

# Via rake task
rake app:rails_chatbot:add_knowledge['Title','Content','Type']

RailsChatbot.configure do |config|
  config.openai_api_key = ENV['OPENAI_API_KEY']
  config.openai_model = 'gpt-4o-mini'
  config.chatbot_title = 'Support Assistant'
  config.current_user_proc = proc { |controller| controller.current_user }
  config.indexable_models = [User, Product, Order] # Custom models to index
end

# Knowledge base management
rake app:rails_chatbot:stats                    # View statistics
rake app:rails_chatbot:clear_knowledge_base     # Clear all entries
rake app:rails_chatbot:add_knowledge['Title','Content','Type'] # Add knowledge
rake app:rails_chatbot:index_all               # Index all models
rake app:rails_chatbot:index_models[User,Post] # Index specific models

# Index products
rake app:rails_chatbot:index_models[Product,Category]

# Add help content
RailsChatbot::KnowledgeIndexer.add_custom_knowledge(
  title: "Shipping Policy",
  content: "We ship within 3-5 business days...",
  source_type: "policy"
)

# Index user models and features
rake app:rails_chatbot:index_models[User,Feature,Subscription]

# Add feature documentation
RailsChatbot::KnowledgeIndexer.add_custom_knowledge(
  title: "Dashboard Overview",
  content: "The dashboard shows your usage statistics...",
  source_type: "documentation"
)

1. OpenAI API Errors

   • Check your API key is valid
   • Verify you have credits in your OpenAI account
   • Try a different model (gpt-3.5-turbo)

2. No Knowledge Found

   • Run rake app:rails_chatbot:index_all to populate knowledge base
   • Add custom knowledge entries
   • Check rake app:rails_chatbot:stats for entries

3. Search Not Working

   • Ensure PostgreSQL is configured
   • Check database migrations ran successfully
   • Verify knowledge base has content

4. Routing Issues

   • Confirm engine is mounted in routes.rb
   • Check for route conflicts with existing paths
   • Restart Rails server after route changes

# In development, add to initializer
RailsChatbot.configure do |config|
  # ... other config
  Rails.logger.level = :debug
end

• GET /chatbot - Chat interface
• POST /chatbot/conversations - Create conversation
• GET /chatbot/conversations - List conversations
• POST /chatbot/conversations/:id/messages - Send message
• GET /chatbot/search?q=query - Search knowledge

{
  "message": {
    "role": "assistant",
    "content": "Here's the answer...",
    "created_at": "2026-02-12T12:00:00Z"
  },
  "knowledge_sources": [
    {
      "title": "User Guide",
      "source_type": "documentation",
      "source_url": "/docs/users"
    }
  ]
}

Create app/views/rails_chatbot/chat/index.html.erb in your app to customize the chat interface.

Add to app/assets/stylesheets/rails_chatbot/custom.css:

.chatbot-container {
  background: your-brand-color;
  border-radius: your-preference;
}

Extend functionality in app/javascript/rails_chatbot/custom.js.

For comprehensive documentation, visit our Documentation Site.

• 🚀 Quick Start Guide - Get up and running in 5 minutes
• 📖 API Reference - Complete API documentation
• 💡 Examples & Use Cases - Real-world implementation examples
• 🧪 Testing Guide - How to test your integration
• 🚀 Deployment Guide - Production deployment instructions
• 🤝 Contributing - How to contribute to the project

• Ruby on Rails 8.0.4 or higher
• PostgreSQL (for full-text search)
• OpenAI API key
• Modern web browser

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

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions