Ruby SDK Planned

Idiomatic Ruby gem for the message.com REST API. Rails-ready, Sidekiq-friendly, no monkey patches. Targets Ruby 3.1+. Comes with a one-line Rails initializer and a Sorbet-typed surface for static analysis fans.

Installation

Drop the gem in your Gemfile and bundle. The gem has no native extensions, so it installs cleanly on Alpine, Lambda layers, and Heroku-style buildpacks.

# Gemfile
gem "message-com", "~> 1.0"

# then
bundle install

# or directly
gem install message-com

Configure

Configuration is global by default. For multi-tenant apps where each workspace uses a different key, the gem also exposes a Message::Client.new constructor that takes an explicit key.

require "message_com"

Message.configure do |c|
  c.api_key = ENV.fetch("MESSAGE_API_KEY")
  c.timeout = 5
end

Sync visitors

Mirror your User or Customer table into the workspace visitor list. The upsert keys on external_id; pass your primary key.

# In an ActiveRecord after_save
Message::Visitor.upsert(
  email: "[email protected]",
  external_id: "crm-4567",
  name: "Alice Johnson",
  attributes: { plan: "pro", mrr: 99 }
)

Open tickets

Open a ticket from any backend event. The reply lands in your unified inbox tagged with whatever you pass.

# In a Sidekiq worker
Message::Ticket.create(
  visitor_email: "[email protected]",
  subject: "Auto-detected failed payment",
  body: "Stripe charge ch_xyz failed. Reach out within 4h.",
  tags: ["billing", "auto-created"]
)

Rails integration

The most common deployment is Rails. Drop the configuration in an initializer, then use a concern to sync any model.

# config/initializers/message.rb
Message.configure do |c|
  c.api_key = Rails.application.credentials.dig(:message, :api_key)
  c.logger  = Rails.logger
end

# app/models/concerns/messageable.rb
module Messageable
  extend ActiveSupport::Concern
  included do
    after_save_commit :sync_to_message
  end

  private

  def sync_to_message
    Message::Visitor.upsert(
      external_id: id.to_s,
      email: email,
      name: name,
      attributes: { plan: plan }
    )
  end
end

Background jobs

By default every call is synchronous. For high-throughput apps, wrap calls in your job runner of choice. The gem ships an optional Sidekiq adapter that handles backoff and idempotency keys for you.

Errors

All API errors raise subclasses of Message::Error with the status code, error code, and message preserved. See the Ruby exception guide if you want a primer on the rescue patterns.

Common pitfalls

• Do not call from controllers without timeouts. The default is 30s; set c.timeout = 5 globally or per call.
• Always use external_id for visitor identity. Emails change; primary keys do not.
• Wrap in a background job if you are syncing on hot paths like after_save_commit. The network call adds latency to every write.