API: Chat

ChatSDK::Chat is the central object that holds adapters, state, event handlers, and webhook endpoints.

Constructor

ChatSDK::Chat.new(
  user_name:,
  adapters:,
  state:,
  **options
)

Raises ConfigurationError if user_name is blank, adapters is empty, or state is nil.

Instance Methods

Event Registration

on_new_mention

chat.on_new_mention { |thread, message| ... }

Register a handler for @-mentions of the bot.

on_new_message(pattern = nil)

chat.on_new_message(/deploy/) { |thread, message| ... }

Register a handler for @-mentions matching a Regexp or String pattern. If pattern is nil, matches all mentions (equivalent to on_new_mention).

on_subscribed_message

chat.on_subscribed_message { |thread, message| ... }

Register a handler for messages in threads the bot has subscribed to.

on_direct_message

chat.on_direct_message { |thread, message| ... }

Register a handler for direct messages sent to the bot.

on_reaction(emojis = nil)

chat.on_reaction(%w[thumbsup thumbsdown]) { |event| ... }

Register a handler for emoji reactions. Pass an Array of emoji names to filter, or nil to match all reactions.

on_action(action_id)

chat.on_action("approve_btn") { |event| ... }

Register a handler for interactive card actions (buttons, selects) matching action_id.

on_slash_command(command)

chat.on_slash_command("/deploy") { |event| ... }

Register a handler for slash commands matching command.

Adapter Access

adapter(name)

chat.adapter(:slack) # => Adapter::Base

Returns the adapter registered under name. Raises ConfigurationError if not found.

Channel / DM Access

channel(id, adapter_name: nil)

chat.channel("C123")                        # => Channel (uses first adapter)
chat.channel("C123", adapter_name: :slack)   # => Channel (explicit adapter)

Returns a Channel for the given ID. If adapter_name is omitted, uses the first registered adapter.

open_dm(user_id, adapter_name: nil)

dm = chat.open_dm("U456", adapter_name: :slack)
dm.post("Hello via DM!")

Opens a DM conversation with the user via the adapter's open_dm and returns a Channel bound to that DM channel ID.

Webhooks

chat.webhooks[:slack]     # => Webhook::Endpoint (Rack app for a single adapter)
chat.webhooks.router      # => Webhook::Router   (Rack app routing to all adapters)

webhooks[adapter_name] returns a Webhook::Endpoint Rack application for the named adapter. Endpoints are memoized on first access.

webhooks.router returns a Webhook::Router Rack application that routes incoming requests to the correct adapter endpoint.

Dispatch

dispatch(event, adapter_name:)

chat.dispatch(event, adapter_name: :slack)

Dispatches a parsed event through the handler pipeline. Called internally by webhook endpoints; you can also call it directly for testing or custom ingestion.

Attributes