Convo

Convo is a Rails engine that provides a flexible and customizable conversation system for your Rails application. It enables easy implementation of messaging and conversation features between users of your application.

Features

• Easy-to-use conversation system
• Support for multiple participants in conversations
• Automatic conversation threading and topic management
• Model-agnostic implementation (works with any user model)
• Built-in validations and security measures
• Clean and simple API

Installation

Add this line to your application's Gemfile:

gem 'convo'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install convo

Setup

1. Install the migrations:

$ rails convo:install:migrations
$ rails db:migrate

1. Include the HasConvo module in your user model:

class User < ApplicationRecord
  include Convo::HasConvo
end

Usage

Starting a Conversation

To send a message to one or multiple recipients:

# Send to a single recipient
user.send_message(
  recipients: recipient,
  body: "Hello!"
)

# Send to multiple recipients
user.send_message(
  recipients: [recipient1, recipient2],
  body: "Hello everyone!"
)

Accessing Conversations

# Get all topics for a user
user.topics

# Get all messages for a user
user.messages

# Get messages from a specific topic
topic.messages

Understanding Topics

Topics are unique per combination of participants. For example:

• If a topic exists between User1 and User2
• And you send a message to User1, User2, and User3
• A new topic will be created for this three-person conversation
• The original topic between User1 and User2 remains separate

This ensures that conversations between different groups of participants stay organized and separate, even if there's overlap in the participants.

Context and Tenant Support

Messages can be associated with a context (any record) and a tenant (for broader visibility):

# Send a message with context and tenant
user.send_message(
  recipients: recipient,
  body: "Hello!",
  context: some_record,  # Optional: Any ActiveRecord model
  tenant: organization   # Optional: Any ActiveRecord model
)

# Find topics by context
Topic.with_context(some_record)

# Find topics by tenant
Topic.with_tenant(organization)

# Find topics by both context and tenant
Topic.with_context_and_tenant(some_record, organization)

This allows you to:

• Organize conversations around specific records (e.g., Order, Project, Task)
• Control visibility of conversations across different scopes (e.g., Organizations, Teams)
• Query conversations based on their context or tenant

Requirements

• Ruby >= 3.0.0
• Rails >= 8.0.1
• PostgreSQL (for array type support)

Development

After checking out the repo, run:

$ bundle install
$ bundle exec rake spec

Contributing

1. Fork it
2. Create your feature branch (git checkout -b feature/my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin feature/my-new-feature)
5. Create new Pull Request

License

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

Credits

Developed and maintained by Ben.