action_bot.cr

Bots as first-class framework citizens: a unified message contract over messenger platforms (Telegram Bot API, WhatsApp Cloud API, web/SSE) — an original CRails component, not a port: Rails has no bot framework, so there is no Ruby original to mirror. The transport layer follows the ActionMailer/ActionMailbox idiom (ActionBot::Base DSL + adapters); the AI-agent loop (Brain/Tools) is deliberately left to a separate ActiveAgent shard that plugs in via reply.stream without touching the bot contract. Built oracle-first per the project rules: Telegram inbound fixtures are validated by the real telegram-bot-ruby 2.8.1 (vendored in oracle/vendor), WhatsApp fixtures follow the Cloud API webhook schema (whatsapp_sdk field layout), and outbound payloads are byte-identical to the documented API request bodies. Suite: 39 oracle cases + 9 integration specs (19/19).

⚠️ EXPERIMENTAL FRAMEWORK, DO NOT USE IN PRODUCTION YET.

Installation

dependencies:
  action_bot_cr:
    github: OrelSokolov/action_bot.cr

shards install

Depends on active_support.cr and active_job.cr.

Usage

class SupportBot < ActionBot::Base
  adapter "telegram"
  command "start" { |m| reply.text "Hi!" }
  message { |m| reply.text "You said: #{m.text}" }
  callback_query { |q| reply.text "Selected: #{q.data}" }
end

# dispatch a normalized Update (from webhook, poller or specs)
SupportBot.new.dispatch(update)

# streaming replies (editMessageText on Telegram, real SSE on web)
reply.stream do |emit|
  chunks.each { |c| emit << c }
end

Adapters are configured via ENV (TELEGRAM_BOT_TOKEN, TELEGRAM_SECRET_TOKEN, WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_APP_SECRET, WHATSAPP_VERIFY_TOKEN; *_API_BASE / TEST_* vars point them at fakes). HTTP endpoints come with the shard: POST /bot/webhooks/:platform/:bot (secret-checked, WhatsApp hub.challenge GET) and GET /bot/sse/:bot (chunks → data: events, final → event: done). Railties provide crails generate bot NAME --platform=…, config/bots.yml and crails bot:poll (getUpdates poller).

Feature comparison

Rails has no bot framework, so the table compares with the de-facto Ruby stack this shard replaces: telegram-bot-ruby 2.8.1 + whatsapp_sdk

• a hand-rolled webhook controller.

Core contract

Platforms

Railties / E2E

Deviations & Crystal-specific notes

• Symbol typing: Chat#type is a Symbol (:private/:group/:channel).
• Streaming into platform chats is emulated with progressive message edits — no messenger streams natively; the web side gets real SSE from the same reply.stream pipeline.
• The Telegram token contains : and is escaped with URI.encode_path in API-call paths.
• App mounting uses prefix matching (starts_with?("/bot/webhooks")), not exact routes: the path carries :platform/:bot segments.
• dispatch(update) resets a cached reply only on re-dispatch, so a pre-injected transport (SSE) survives the first dispatch.
• Contracts are frozen module-interfaces (deliver/stream/parse/verify) — additive evolution only.

Full details: PLAN.md (Russian).

Testing

crystal spec   # self-contained: fake HTTP servers, no PostgreSQL/Redis needed

Oracle: 39 cases recorded with the real telegram-bot-ruby 2.8.1 (oracle/cases.rb → oracle/expected.yml; Telegram fixtures parsed by the vendored gem, WhatsApp checked against the Cloud API schema); the Crystal specs replay them 1:1 without edits, plus 9 integration specs (webhooks, SSE, poller, byte-exact outbound payloads).