Usage Overview

This page covers the core concepts of ChatSDK Ruby. Each section links to a detailed page.

The Chat Instance

ChatSDK::Chat is the central object. It holds your adapters, state backend, and event handlers.

bot = ChatSDK::Chat.new(
  user_name: "my-bot",
  adapters: { slack: slack_adapter },
  state: ChatSDK::State::Memory.new
)

Required arguments:

Optional keyword arguments are documented in Getting Started.

Adapters

An adapter translates between ChatSDK's normalized API and a specific platform. Each adapter is a subclass of ChatSDK::Adapter::Base that implements methods like post_message, edit_message, and parse_events.

ChatSDK ships nine official platform adapters:

• ChatSDK::Slack::Adapter -- Slack
• ChatSDK::Teams::Adapter -- Microsoft Teams
• ChatSDK::GChat::Adapter -- Google Chat
• ChatSDK::Mattermost::Adapter -- Mattermost
• ChatSDK::Discord::Adapter -- Discord
• ChatSDK::Telegram::Adapter -- Telegram
• ChatSDK::Twilio::Adapter -- Twilio
• ChatSDK::Messenger::Adapter -- Messenger
• ChatSDK::WhatsApp::Adapter -- WhatsApp

See Platform Adapters for the full capability matrix.

State

The state backend stores thread subscriptions, event deduplication records, per-thread locks, and arbitrary key-value data. Four implementations ship out of the box:

• ChatSDK::State::Memory -- In-process, no dependencies. Good for development and single-process deployments.
• ChatSDK::State::Redis -- Uses Redis. Recommended for production multi-process deployments.
• ChatSDK::State::Pg -- Uses PostgreSQL with JSONB storage and auto-migration.
• ChatSDK::State::Mysql -- Uses MySQL with JSON storage and auto-migration.

See State Adapters for details.

Event Handlers

Register blocks that run when events arrive:

bot.on_new_mention { |thread, message| ... }
bot.on_subscribed_message { |thread, message| ... }
bot.on_direct_message { |thread, message| ... }
bot.on_new_message(/deploy/) { |thread, message| ... }
bot.on_reaction { |event| ... }
bot.on_action("approve_btn") { |event| ... }
bot.on_slash_command("/deploy") { |event| ... }

Handlers for mentions, subscribed messages, and direct messages receive (thread, message). Handlers for reactions, actions, and slash commands receive a single event object that includes a thread method.

See Handling Events for details on each handler.

Threads and Channels

A Thread represents a conversation thread. It is your primary interface for sending messages:

bot.on_new_mention do |thread, message|
  thread.post("Hello!")
  thread.post(ChatSDK.card(title: "Status") { text "All systems go" })
  thread.subscribe  # receive future messages in this thread
end

A Channel represents a chat channel. Use it for posting messages outside of event handlers:

channel = bot.channel("C12345", adapter_name: :slack)
channel.post("Scheduled announcement")

See Threads, Messages & Channels for the full API.

Webhooks

ChatSDK exposes Rack-compatible webhook endpoints. Mount them in your web framework to receive events from each platform:

# Single adapter
run bot.webhooks[:slack]

# Multi-adapter router (dispatches by path)
run bot.webhooks.router

See Getting Started and Rails Integration.